mail-time 5.1.0 → 5.2.0

package/index.js

@@ -7,6 +7,10 @@ import { PostgresQueue } from './adapters/postgres.js';
 import { mailTimePreset, presets, presetNames } from './presets.js';
 import { debug, escapeHtml, logError, hasOwnProp, deepMerge, equals, isPlainObject, extractEmail, toAddressList, filterAddressField } from './helpers.js';
 
+import { validateRecipientPolicies, policyError, normalizePolicyAddress, preparePolicyEnvelope, evaluatePolicyPhase, mergePolicyResults, summarizePolicyTask } from './recipient-policy.js';
+import { normalizeRejections } from './recipient-rejections.js';
+import { RecipientPolicyLease } from './recipient-policy-lease.js';
+
 const noop = () => {};
 const queueMethods = ['ping', 'iterate', 'getPendingTo', 'push', 'remove', 'update', 'cancel'];
 
@@ -208,11 +212,32 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
+ * @typedef {{ [key: string]: any, ping: () => Promise<MailTimePingResult>, setInterval: (func: (...args: any[]) => unknown, delay: number, uid: string) => Promise<string>, destroy: () => boolean, shutdown: (opts?: { timeout?: number }) => Promise<boolean>, pause: (timerId?: string) => boolean, resume: (timerId?: string) => boolean }} MailTimeScheduler
+ */
+
+/**
+ * @typedef {string | { address: string, name?: string }} MailTimeMailbox
  */
 
 /**
- * @typedef {{ uuid: string, to?: string | string[], tries: number, sendAt: number, isSent: boolean, isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
+ * @typedef {{ address: string, sources: Array<'envelope' | 'to' | 'cc' | 'bcc'> }} MailTimePolicyRecipient
+ * @typedef {{ address: string, status: 'suppressed' | 'rejected' | 'retry', reason: string }} MailTimePolicyDecision
+ * @typedef {{ decisions?: MailTimePolicyDecision[] }} MailTimePolicyResult
+ * @typedef {{ index: number, name?: string }} MailTimePolicyTransport
+ * @typedef {{ from?: string, to: string[] }} MailTimePolicyEnvelope
+ * @typedef {{ task: MailTimeTask, attempt: number, transport: MailTimePolicyTransport, envelope: MailTimePolicyEnvelope, recipients: MailTimePolicyRecipient[] }} MailTimePolicyContext
+ * @typedef {MailTimePolicyContext} MailTimeBeforeSendPolicyContext
+ * @typedef {{ address: string | null, command?: string, responseCode?: number, response?: string, message?: string, transportIndex: number, transportName?: string }} MailTimeStructuredRejection
+ * @typedef {MailTimePolicyContext & { error?: unknown, info?: unknown, rejections: MailTimeStructuredRejection[] }} MailTimeRejectionPolicyContext
+ * @typedef {{ address: string, status: 'sent' | 'error' | 'suppressed' | 'rejected', sources?: Array<'envelope' | 'to' | 'cc' | 'bcc'>, reasons: Array<{ provider: string, reason: string }>, attempt: number, transportIndex?: number, transportName?: string, command?: string, responseCode?: number, response?: string, message?: string }} MailTimeRecipientResult
+ * @typedef {MailTimeRejectionPolicyContext & { decisions: MailTimeRecipientResult[] }} MailTimeRecipientAttemptContext
+ * @typedef {{ uuid: string, tries: number, isSettled: boolean, recipients: { sent: MailTimeRecipientResult[], error: MailTimeRecipientResult[], suppressed: MailTimeRecipientResult[], rejected: MailTimeRecipientResult[] } }} MailTimeRecipientSummary
+ * @typedef {{ name: string, failureMode?: 'retry' | 'continue', beforeSend?: (context: MailTimeBeforeSendPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>, classifyRejections?: (context: MailTimeRejectionPolicyContext) => void | MailTimePolicyResult | Promise<void | MailTimePolicyResult>, observeAttempt?: (context: MailTimeRecipientAttemptContext) => void | Promise<void> }} MailTimeRecipientPolicy
+ * @description Policy contexts are read-only by contract. Providers must bound their own I/O; renewal budgets do not limit hook duration.
+ */
+
+/**
+ * @typedef {{ uuid: string, to?: MailTimeMailbox | MailTimeMailbox[], tries: number, sendAt: number, isSent: boolean, isSettled?: boolean, recipientResults?: MailTimeRecipientResult[], isCancelled: boolean, isFailed: boolean, isSending?: boolean, sendingAt?: number, template?: string | false, transport: number, concatSubject?: string | false, mailOptions: MailTimeMailOptions[] }} MailTimeTask
  */
 
 /**
@@ -220,7 +245,7 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ ping: () => Promise<MailTimePingResult>, iterate: (opts?: MailTimeIterateOptions) => Promise<void> | void, getPendingTo: (to: string, sendAt: number) => Promise<MailTimeTask | object | null>, push: (email: MailTimeTask) => Promise<void> | void, cancel: (uuid: string) => Promise<boolean>, remove: (email: MailTimeTask | object, opts?: { leaseTries: number, leaseSendingAt: number }) => Promise<boolean>, update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>, ready?: () => Promise<void> }} CustomQueue
+ * @typedef {{ ping: () => Promise<MailTimePingResult>, iterate: (opts?: MailTimeIterateOptions) => Promise<void> | void, getPendingTo: (to: string, sendAt: number) => Promise<MailTimeTask | object | null>, push: (email: MailTimeTask) => Promise<void> | void, cancel: (uuid: string) => Promise<boolean>, remove: (email: MailTimeTask | object, opts?: { leaseTries: number, leaseSendingAt: number }) => Promise<boolean>, update: (email: MailTimeTask | object, updateObj: object) => Promise<boolean>, ready?: () => Promise<void>, supportsRecipientPolicies?: boolean }} CustomQueue
  */
 
 /**
@@ -228,7 +253,7 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ [key: string]: any, to: string | string[], sendAt?: Date | number, template?: string, concatSubject?: string, text?: string | false, html?: string | false, subject?: string, accepted?: string[], rejected?: MailTimeRejectedRecipient[] }} MailTimeMailOptions
+ * @typedef {{ [key: string]: any, to: MailTimeMailbox | MailTimeMailbox[], cc?: MailTimeMailbox | MailTimeMailbox[], bcc?: MailTimeMailbox | MailTimeMailbox[], sendAt?: Date | number, template?: string, concatSubject?: string, text?: string | false, html?: string | false, subject?: string, accepted?: string[], rejected?: MailTimeRejectedRecipient[] }} MailTimeMailOptions
  */
 
 /**
@@ -240,10 +265,16 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, onError?: (error: unknown, email: MailTimeTask | null, details?: object) => void, onSent?: (email: MailTimeTask, details?: object) => void }} MailTimeOptions
+ * @typedef {{ queue: RedisQueue | MongoQueue | PostgresQueue | CustomQueue, type?: 'server' | 'client', from?: string | ((transport: MailTimeTransport, details: MailTimeFromDetails) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, shouldFailOver?: (error: unknown, info: object | undefined, email: MailTimeTask) => boolean, retries?: number, maxTries?: number, retryDelay?: number, interval?: number, keepHistory?: boolean, concatEmails?: boolean | MailTimeConcatEmailsOptions, concatSubject?: string, concatDelimiter?: string, concatDelay?: number, concatThrottling?: number, revolvingInterval?: number, mode?: 'one' | 'batch', concurrency?: number, sendingTimeout?: number, renewClaim?: boolean | number, maxRenewals?: number, strictPayload?: boolean, allowedMailFields?: string[], verifyTransports?: boolean, template?: string, prefix?: string, debug?: boolean, josk?: MailTimeJoSkOptions, recipientPolicies?: MailTimeRecipientPolicy[], onError?: (error: unknown, email: MailTimeTask | null, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>, onSent?: (email: MailTimeTask, details?: object, recipients?: MailTimeRecipientResult[], summary?: MailTimeRecipientSummary) => void | Promise<void>, onSuppressed?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void>, onRejected?: (email: MailTimeTask, recipients: MailTimeRecipientResult[], summary: MailTimeRecipientSummary) => void | Promise<void> }} MailTimeOptions
  */
 
-/** Class of MailTime */
+/**
+ * Class of MailTime.
+ * With recipientPolicies, terminal callbacks receive grouped recipients and a complete summary after persistence.
+ * isSettled includes exhausted errors; isSent means all accepted; isFailed means an error or permanent rejection.
+ * Unparseable terminal preparation failures invoke onError with an empty recipient group.
+ * Hooks must bound their own I/O. Callback notifications are best-effort, not durable exactly-once delivery.
+ */
 class MailTime {
   /**
    * Create a MailTime instance
@@ -258,6 +289,7 @@ class MailTime {
       throw new Error('[mail-time] {queue} option is required: provide a MongoQueue, RedisQueue, PostgresQueue, or CustomQueue instance');
     }
 
+    this.__recipientPolicies = validateRecipientPolicies(opts.recipientPolicies, opts.queue);
     this.queue = opts.queue;
 
     for (let i = queueMethods.length - 1; i >= 0; i--) {
@@ -297,6 +329,8 @@ class MailTime {
     this.keepHistory = opts.keepHistory === true;
     this.onSent = (typeof opts.onSent === 'function') ? opts.onSent.bind(this) : noop;
     this.onError = (typeof opts.onError === 'function') ? opts.onError.bind(this) : noop;
+    this.onSuppressed = (typeof opts.onSuppressed === 'function') ? opts.onSuppressed.bind(this) : noop;
+    this.onRejected = (typeof opts.onRejected === 'function') ? opts.onRejected.bind(this) : noop;
 
     this.revolvingInterval = (typeof opts.revolvingInterval === 'number' && opts.revolvingInterval > 0) ? opts.revolvingInterval : 1536;
     this.mode = (opts.mode === 'one' || opts.mode === 'batch') ? opts.mode : 'batch';
@@ -509,8 +543,8 @@ class MailTime {
   /**
    * @memberOf MailTime
    * @name destroy
-   * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, any in-flight SMTP attempts are neutralized on completion — they perform no storage writes, no `onSent`/`onError` callbacks, and no logging once `destroy()` returns; their claimed rows are recovered by stale-lock timeout (`sendingTimeout`). Pass `{ drain: true }` to instead let in-flight attempts run to completion (returns a Promise that resolves once they settle).
-   * @param {{ drain?: boolean }} [opts]
+   * @description Stop the scheduler and block future dispatches. Without `{ drain: true }`, in-flight SMTP attempts are neutralized and their claims recover after `sendingTimeout`. With `{ drain: true }`, await JoSk shutdown and in-flight SMTP; resolves false if a scheduler handler exceeds `schedulerTimeout` (default 10000ms) or JoSk shutdown throws (logged); never rejects. The timeout does not bound SMTP drain time.
+   * @param {{ drain?: boolean, schedulerTimeout?: number }} [opts] - schedulerTimeout must be finite and non-negative; used only with drain
    * @returns {boolean | Promise<boolean>}
    */
   destroy(opts) {
@@ -518,14 +552,29 @@ class MailTime {
     if (this.__isDestroyed) {
       return false;
     }
+    if (opts?.drain === true && opts.schedulerTimeout !== void 0
+      && (typeof opts.schedulerTimeout !== 'number' || !Number.isFinite(opts.schedulerTimeout) || opts.schedulerTimeout < 0)) {
+      throw new Error('[mail-time] [destroy] schedulerTimeout must be a finite non-negative number');
+    }
 
     this.__isDestroyed = true;
     this.__isPaused = false;
-    if (this.scheduler && typeof this.scheduler.destroy === 'function') {
-      this.scheduler.destroy();
+    if (opts?.drain === true) {
+      return (async () => {
+        let finished = true;
+        try {
+          if (this.scheduler) finished = await this.scheduler.shutdown({ timeout: opts.schedulerTimeout });
+        } catch (error) {
+          logError('[destroy] scheduler shutdown failed', error);
+          finished = false;
+        } finally {
+          await this.__pool.drain();
+        }
+        return finished;
+      })();
     }
-    if (opts && opts.drain === true && this.__pool) {
-      return this.__pool.drain().then(() => true);
+    if (this.scheduler) {
+      this.scheduler.destroy();
     }
     // No graceful drain requested: neutralize in-flight SMTP completions so a
     // destroyed instance performs no storage writes, no `onSent`/`onError`
@@ -646,7 +695,8 @@ class MailTime {
     delete mailOptions.template;
     delete mailOptions.concatSubject;
 
-    if (typeof mailOptions.to !== 'string' && (!Array.isArray(mailOptions.to) || !mailOptions.to.length)) {
+    const isMailbox = isPlainObject(mailOptions.to) && typeof mailOptions.to.address === 'string' && mailOptions.to.address.trim().length > 0;
+    if (!isMailbox && typeof mailOptions.to !== 'string' && (!Array.isArray(mailOptions.to) || !mailOptions.to.length)) {
       throw new Error('[mail-time] [sendMail] `mailOptions.to` is required and must be a string or non-empty Array');
     }
 
@@ -806,6 +856,7 @@ class MailTime {
       uuid: randomUUID(),
       tries: 0,
       isSent: false,
+      isSettled: false,
       sendAt: opts.sendAt,
       isFailed: false,
       isSending: false,
@@ -939,7 +990,7 @@ class MailTime {
     }
 
     const acceptedSet = collectAcceptedSet(task);
-    if (acceptedSet.size > 0) {
+    if (!this.__recipientPolicies && acceptedSet.size > 0) {
       compiledOpts.to = filterAddressField(compiledOpts.to, acceptedSet);
       compiledOpts.cc = filterAddressField(compiledOpts.cc, acceptedSet);
       compiledOpts.bcc = filterAddressField(compiledOpts.bcc, acceptedSet);
@@ -1152,7 +1203,7 @@ class MailTime {
     };
 
     const renew = async () => {
-      if (stopped || this.__isDestroyed || this.__abortInFlight) {
+      if (stopped || this.__abortInFlight) {
         halt();
         return;
       }
@@ -1205,6 +1256,204 @@ class MailTime {
     return { stop };
   }
 
+  /** @internal Serialize every policy checkpoint with this attempt's claim renewal. */
+  async ___sendWithRecipientPolicies(task) {
+    if (!task || task.isSent || task.isFailed || task.isCancelled || task.isSettled || this.__abortInFlight) return;
+    const recoveryOnly = Array.isArray(task.recipientResults) && (task.tries >= this.maxTries
+      || (task.recipientResults.length > 0 && task.recipientResults.every((r) => r.status === 'sent' || r.status === 'suppressed' || r.status === 'rejected')));
+    const fields = { tries: recoveryOnly ? task.tries : task.tries + 1, isSending: true, sendingAt: Math.max(Date.now(), (task.sendingAt || 0) + 1), recipientResults: task.recipientResults || [] };
+    try {
+      if (!await this.queue.update(task, fields)) return;
+    } catch (error) {
+      if (!this.__abortInFlight) logError('[recipientPolicies] claim failed', error);
+      return;
+    }
+    Object.assign(task, fields);
+    const lease = new RecipientPolicyLease({
+      task, queue: this.queue, interval: this.renewClaim, maxRenewals: this.maxRenewals,
+      shouldAbort: () => this.__abortInFlight,
+      report: (error) => logError('[recipientPolicies] lease persistence failed', error),
+    });
+    try {
+      if (!lease.active) return;
+      if (recoveryOnly) {
+        let preparationFailure = false;
+        if (!task.recipientResults.length) {
+          try {
+            const compiled = this.___compileMailOpts(this.transports[task.transport], task);
+            const prepared = preparePolicyEnvelope(compiled);
+            task.recipientResults = mergePolicyResults([], prepared.recipients, { retryFailure: false, decisions: [] }, {
+              phase: 'beforeSend', attempt: task.tries, transportIndex: task.transport, accepted: [...collectAcceptedSet(task)],
+            });
+          } catch { preparationFailure = true; }
+        }
+        await this.___completePolicyTask(task, lease, policyError('last attempt interrupted; completing durable recipient state'), void 0, preparationFailure);
+        return;
+      }
+      if (!this.___isHealthyTransport(task.transport)) task.transport = this.___nextHealthyTransport(task.transport);
+      const transport = this.transports[task.transport];
+      const compiled = this.___compileMailOpts(transport, task);
+      if (!compiled.from) compiled.from = MailTime.transportFrom(transport);
+      const prepared = preparePolicyEnvelope(compiled, task.recipientResults);
+      const transportName = typeof transport.name === 'string' ? transport.name : transport.options?.name;
+      const details = { phase: 'beforeSend', attempt: task.tries, transportIndex: task.transport, transportName, accepted: [...collectAcceptedSet(task)] };
+      task.recipientResults = mergePolicyResults(task.recipientResults, prepared.recipients, { retryFailure: false, decisions: [] }, details);
+      const pending = new Set(task.recipientResults.filter((r) => r.status === 'error').map((r) => r.address));
+      const context = {
+        task, attempt: task.tries, transport: { index: task.transport, ...(typeof transportName === 'string' ? { name: transportName.slice(0, 128) } : {}) },
+        envelope: { ...prepared.envelope, to: prepared.envelope.to.filter((a) => pending.has(a)) },
+        recipients: prepared.recipients.filter((r) => pending.has(r.address)),
+      };
+      if (!pending.size) {
+        await this.___completePolicyTask(task, lease);
+        return;
+      }
+      const evaluated = await evaluatePolicyPhase(this.__recipientPolicies, 'beforeSend', context, (error, name, hook) => {
+        if (!this.__abortInFlight) logError(`[recipientPolicies] ${name}.${hook} failed`, error);
+      });
+      if (!lease.active) return;
+      task.recipientResults = mergePolicyResults(task.recipientResults, context.recipients, evaluated, details);
+      if (!await lease.update({ recipientResults: task.recipientResults, mailOptions: task.mailOptions })) return;
+      if (!lease.active) return;
+      if (evaluated.retryFailure) {
+        await this.___retryPolicyTask(task, lease, policyError('beforeSend provider failed'), void 0, true);
+        return;
+      }
+      const eligible = new Set(task.recipientResults.filter((r) => r.status === 'error').map((r) => r.address));
+      if (!eligible.size) {
+        await this.___completePolicyTask(task, lease);
+        return;
+      }
+      context.envelope = { ...context.envelope, to: context.envelope.to.filter((a) => eligible.has(a)) };
+      context.recipients = context.recipients.filter((r) => eligible.has(r.address));
+      await this.___attemptPolicyTransport(task, lease, compiled, context);
+    } catch (error) {
+      if (lease.active) await this.___retryPolicyTask(task, lease, error, void 0, true, true);
+    } finally {
+      await lease.stop();
+    }
+  }
+
+  /** @internal Persist SMTP acceptance before awaiting rejection classification or observation. */
+  async ___attemptPolicyTransport(task, lease, compiled, context) {
+    const transport = this.transports[context.transport.index];
+    const outgoing = { ...compiled, envelope: context.envelope };
+    const { error, info } = await new Promise((resolve) => {
+      let called = false;
+      const done = (error, info) => {
+        if (called) return;
+        called = true;
+        resolve({ error, info });
+      };
+      try { transport.sendMail(outgoing, done); }
+      catch (error) { done(error, void 0); }
+    });
+    if (!lease.active) return;
+    const attempted = new Set(context.envelope.to);
+    const accepted = new Set();
+    for (const source of [info, error]) {
+      for (const value of Array.isArray(source?.accepted) ? source.accepted : []) {
+        try {
+          const address = normalizePolicyAddress(value);
+          if (attempted.has(address)) accepted.add(address);
+        } catch { /* Transport records outside supported address forms remain unresolved. */ }
+      }
+    }
+    const details = { phase: 'classifyRejections', attempt: task.tries, transportIndex: context.transport.index, transportName: context.transport.name, accepted: [...accepted] };
+    task.recipientResults = mergePolicyResults(task.recipientResults, context.recipients, { retryFailure: false, decisions: [] }, details);
+    this.___mapPolicyMailOptions(task, false);
+    if (!await lease.update({ recipientResults: task.recipientResults, mailOptions: task.mailOptions })) return;
+    if (!lease.active) return;
+    const unresolved = context.recipients.filter((r) => !accepted.has(r.address));
+    if (unresolved.length) {
+      const rejections = normalizeRejections(error, info, context.transport);
+      const rejectionContext = { ...context, recipients: unresolved, error, info, rejections };
+      const evaluated = await evaluatePolicyPhase(this.__recipientPolicies, 'classifyRejections', rejectionContext, (hookError, name, hook) => {
+        if (!this.__abortInFlight) logError(`[recipientPolicies] ${name}.${hook} failed`, hookError);
+      });
+      if (!lease.active) return;
+      task.recipientResults = mergePolicyResults(task.recipientResults, unresolved, evaluated, { ...details, rejections });
+      const observation = { ...rejectionContext, decisions: task.recipientResults };
+      for (const provider of this.__recipientPolicies) {
+        if (!lease.active) return;
+        if (typeof provider.observeAttempt !== 'function') continue;
+        try { await provider.observeAttempt(observation); }
+        catch (hookError) {
+          if (!this.__abortInFlight) logError(`[recipientPolicies] ${provider.name}.observeAttempt failed`, hookError);
+        }
+      }
+    }
+    if (!lease.active) return;
+    if (task.recipientResults.some((r) => r.status === 'error')) {
+      await this.___retryPolicyTask(task, lease, error || policyError('recipients remain unaccepted'), info, !!error || accepted.size === 0);
+    } else {
+      await this.___completePolicyTask(task, lease, error, info);
+    }
+  }
+
+  /** @internal Keep legacy per-mail-option state limited to actual envelope recipients. */
+  ___mapPolicyMailOptions(task, terminal) {
+    const results = new Map(task.recipientResults.map((r) => [r.address, r]));
+    for (const option of task.mailOptions || []) {
+      const addresses = new Set();
+      for (const field of ['to', 'cc', 'bcc']) {
+        const values = Array.isArray(option[field]) ? option[field] : [option[field]];
+        for (const value of values) {
+          try { addresses.add(normalizePolicyAddress(value)); } catch { /* Explicit envelopes permit complex headers. */ }
+        }
+      }
+      const accepted = new Set(Array.isArray(option.accepted) ? option.accepted : []);
+      const rejected = [];
+      for (const address of addresses) {
+        const result = results.get(address);
+        if (result?.status === 'sent') accepted.add(address);
+        if (terminal && (result?.status === 'error' || result?.status === 'rejected')) {
+          rejected.push({ address, error: result.message || result.response || result.reasons[0]?.reason || 'Recipient not accepted by transport' });
+        }
+      }
+      option.accepted = [...accepted];
+      if (terminal) option.rejected = rejected;
+    }
+  }
+
+  /** @internal Release a policy claim with all durable outcomes, or settle at exhaustion. */
+  async ___retryPolicyTask(task, lease, error, info, allowRotation, preparationFailure = false) {
+    if (!lease.active) return false;
+    if (task.tries >= this.maxTries) return await this.___completePolicyTask(task, lease, error, info, preparationFailure);
+    let transport = task.transport;
+    if (allowRotation && this.strategy === 'backup' && this.transports.length > 1
+      && task.tries % this.failsToNext === 0 && this.___mayFailOver(error, info, task)) transport = this.___nextHealthyTransport(transport);
+    return await lease.finish({ isSending: false, sendingAt: 0, sendAt: Date.now() + this.retryDelay, transport,
+      recipientResults: task.recipientResults, mailOptions: task.mailOptions }, false);
+  }
+
+  /** @internal Settle truthfully before invoking any best-effort terminal notification. */
+  async ___completePolicyTask(task, lease, error, info, preparationFailure = false) {
+    if (!lease.active) return false;
+    this.___mapPolicyMailOptions(task, true);
+    const results = task.recipientResults;
+    const fields = {
+      isSettled: true, isSent: results.length > 0 && results.every((r) => r.status === 'sent'),
+      isFailed: preparationFailure || results.some((r) => r.status === 'error' || r.status === 'rejected'),
+      isSending: false, sendingAt: 0, recipientResults: results, mailOptions: task.mailOptions,
+    };
+    const completed = await lease.finish(fields, !this.keepHistory);
+    if (completed && !this.__abortInFlight) this.___notifyPolicyGroups(task, error, info, preparationFailure);
+    return completed;
+  }
+
+  /** @internal Empty groups are silent except unparseable terminal preparation failures. */
+  ___notifyPolicyGroups(task, error, info, preparationFailure) {
+    const summary = summarizePolicyTask(task, true);
+    const groups = summary.recipients;
+    if (groups.sent.length) callHook('onSent', this.onSent, task, info, groups.sent, summary);
+    if (!this.__abortInFlight && (groups.error.length || (preparationFailure && !task.recipientResults.length))) {
+      callHook('onError', this.onError, error || policyError('recipients remain unaccepted'), task, info, groups.error, summary);
+    }
+    if (!this.__abortInFlight && groups.suppressed.length) callHook('onSuppressed', this.onSuppressed, task, groups.suppressed, summary);
+    if (!this.__abortInFlight && groups.rejected.length) callHook('onRejected', this.onRejected, task, groups.rejected, summary);
+  }
+
   /**
    * @async
    * @internal
@@ -1248,6 +1497,12 @@ class MailTime {
    * @returns {Promise<void 0>}
    */
   async ___send(task) {
+    if (this.__recipientPolicies) return await this.___sendWithRecipientPolicies(task);
+    if (task?.isSettled === true) return;
+    if (Array.isArray(task?.recipientResults)) {
+      logError('[recipientPolicies] active policy state requires a policy-configured worker', task.uuid);
+      return;
+    }
     this.__debug('[private send]', task);
     try {
       if (!task || task.isSent === true || task.isFailed === true || task.isCancelled === true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-time",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "📮 Email queue extending nodemailer with multi-SMTP transports and horizontally scaled apps support",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -13,6 +13,9 @@
     "adapters/redis.d.ts",
     "adapters/redis.js",
     "helpers.js",
+    "recipient-policy.js",
+    "recipient-rejections.js",
+    "recipient-policy-lease.js",
     "index.cjs",
     "index.d.cts",
     "index.d.ts",
@@ -68,6 +71,7 @@
     "test:mocha:mongo": "mocha ./test/npm-redis-mongo.js ./test/npm-mongo-redis.js ./test/npm-ha-mongo-redis.js",
     "test:mocha:postgres": "mocha ./test/npm-postgres.js",
     "test:types": "tsc -p ./tsconfig.types.json",
+    "test:types:meteor": "node ./test/meteor-types/check.mjs",
     "test:redis": "mocha ./test/npm-redis-redis.js",
     "test:mongo": "mocha ./test/npm-mongo-mongo.js",
     "test:postgres": "mocha ./test/npm-postgres.js",
@@ -135,14 +139,17 @@
   },
   "meteor": {
     "packageName": "ostrio:mailer",
-    "versionsFrom": ["2.14", "3.2"],
+    "versionsFrom": [
+      "2.14",
+      "3.2"
+    ],
     "node": {
       "2.14": ">=14",
       "3.2": ">=18"
     }
   },
   "dependencies": {
-    "josk": "^6.3.0"
+    "josk": "^6.4.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/recipient-policy-lease.js

@@ -0,0 +1,90 @@
+class RecipientPolicyLease {
+  constructor({ task, queue, interval, maxRenewals, shouldAbort, report }) {
+    this.__task = task;
+    this.__queue = queue;
+    this.__shouldAbort = shouldAbort;
+    this.__report = report;
+    this.__closed = false;
+    this.__finishing = false;
+    this.__tail = Promise.resolve();
+    this.__timer = null;
+    let pending = false;
+    let renewals = 0;
+    if (interval && maxRenewals) {
+      this.__timer = setInterval(() => {
+        if (!this.active || this.__finishing || renewals >= maxRenewals) {
+          this.__clearTimer();
+          return;
+        }
+        if (pending) return;
+        pending = true;
+        renewals++;
+        this.__enqueue(async (guard) => {
+          const fields = { isSending: true, sendingAt: Math.max(Date.now(), this.__task.sendingAt + 1) };
+          return await this.__write(fields, guard);
+        }).finally(() => { pending = false; });
+      }, interval);
+      this.__timer.unref?.();
+    }
+  }
+
+  get active() { return !this.__closed && !this.__shouldAbort(); }
+
+  __clearTimer() {
+    if (this.__timer) clearInterval(this.__timer);
+    this.__timer = null;
+  }
+
+  __halt() {
+    this.__clearTimer();
+    this.__closed = true;
+  }
+
+  __enqueue(operation) {
+    const pending = this.__tail.then(async () => {
+      if (!this.active) return false;
+      const guard = { leaseTries: this.__task.tries, leaseSendingAt: this.__task.sendingAt };
+      try {
+        const ok = await operation(guard);
+        if (!ok) this.__halt();
+        return ok;
+      } catch (error) {
+        this.__halt();
+        if (!this.__shouldAbort()) this.__report(error);
+        return false;
+      }
+    });
+    this.__tail = pending.then(() => void 0);
+    return pending;
+  }
+
+  async __write(fields, guard) {
+    const ok = await this.__queue.update(this.__task, { ...fields, ...guard });
+    if (ok) Object.assign(this.__task, fields);
+    return ok;
+  }
+
+  update(fields) {
+    if (this.__finishing) return Promise.resolve(false);
+    return this.__enqueue((guard) => this.__write(fields, guard));
+  }
+
+  finish(fields, remove) {
+    if (this.__finishing) return Promise.resolve(false);
+    this.__finishing = true;
+    this.__clearTimer();
+    return this.__enqueue(async (guard) => {
+      const ok = remove ? await this.__queue.remove(this.__task, guard) : await this.__queue.update(this.__task, { ...fields, ...guard });
+      if (ok) Object.assign(this.__task, fields);
+      this.__halt();
+      return ok;
+    });
+  }
+
+  async stop() {
+    this.__halt();
+    await this.__tail;
+  }
+}
+
+export { RecipientPolicyLease };