mail-time 5.1.0 → 5.2.1

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'];
 
@@ -75,11 +79,19 @@ const createPool = (concurrency) => {
   let active = 0;
   let drainResolvers = [];
 
+  const settleDrain = () => {
+    if (active === 0 && queue.length === 0 && drainResolvers.length > 0) {
+      const resolvers = drainResolvers;
+      drainResolvers = [];
+      for (const r of resolvers) r();
+    }
+  };
+
   const tryStart = () => {
     while (active < limit && queue.length > 0) {
       const job = queue.shift();
       active++;
-      job.resolveSlot();
+      job.resolveSlot(true);
       Promise.resolve()
         .then(job.fn)
         .catch((poolError) => {
@@ -87,11 +99,7 @@ const createPool = (concurrency) => {
         })
         .finally(() => {
           active--;
-          if (active === 0 && queue.length === 0 && drainResolvers.length > 0) {
-            const resolvers = drainResolvers;
-            drainResolvers = [];
-            for (const r of resolvers) r();
-          }
+          settleDrain();
           tryStart();
         });
     }
@@ -100,10 +108,11 @@ const createPool = (concurrency) => {
   return {
     /**
      * Queue `fn` for execution under the concurrency limit.
-     * The returned Promise resolves as soon as a slot is acquired and `fn` has started.
+     * The returned Promise resolves `true` as soon as a slot is acquired and `fn` has started,
+     * or `false` if `cancelQueued()` dropped the job before it started (`fn` never runs).
      * It does NOT wait for `fn` to finish. Use `drain()` to wait for all running jobs to settle.
      * @param {() => Promise<void>} fn
-     * @returns {Promise<void>}
+     * @returns {Promise<boolean>}
      */
     dispatch(fn) {
       return new Promise((resolveSlot) => {
@@ -111,6 +120,16 @@ const createPool = (concurrency) => {
         tryStart();
       });
     },
+    /**
+     * Drop every job still waiting for a slot. Running jobs are untouched.
+     * @returns {number} dropped jobs
+     */
+    cancelQueued() {
+      const dropped = queue.splice(0);
+      for (const job of dropped) job.resolveSlot(false);
+      settleDrain();
+      return dropped.length;
+    },
     drain() {
       if (active === 0 && queue.length === 0) {
         return Promise.resolve();
@@ -208,11 +227,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 +260,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 +268,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 +280,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 +304,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 +344,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';
@@ -332,6 +381,7 @@ class MailTime {
     this.__isDestroyed = false;
     this.__abortInFlight = false;
     this.__isPaused = false;
+    this.__schedulerScans = 0;
     this.__readyPromise = null;
     this.__schedulerTimer = null;
     this.__inFlight = new Set();
@@ -509,8 +559,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. Sends still waiting for a `concurrency` slot are dropped at once; their rows stay unclaimed for the next scan. 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 the queue scan exceeds `schedulerTimeout` (default 10000ms) or JoSk shutdown throws (logged); never rejects. In-flight SMTP does not count against the timeout, and 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 +568,32 @@ 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();
+    // Queued jobs never started SMTP; dropping them lets a scan blocked on a
+    // pool slot return, so JoSk shutdown does not wait for in-flight sends.
+    this.__pool.cancelQueued();
+    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`
@@ -555,7 +623,7 @@ class MailTime {
   /**
    * @memberOf MailTime
    * @name pause
-   * @description Pause this server instance from competing for the queue-drain lease. In-flight SMTP sends finish; peer server instances keep draining. Reversible (unlike `destroy()`). No-op on `client` instances or after `destroy()`. To stop scanning *and* wait for in-flight sends: `mailTime.pause(); await mailTime.drain();`.
+   * @description Pause this server instance from competing for the queue-drain lease. In-flight SMTP sends finish; sends still waiting for a `concurrency` slot are dropped and their rows stay unclaimed; peer server instances keep draining. Reversible (unlike `destroy()`). No-op on `client` instances or after `destroy()`. To stop scanning *and* wait for in-flight sends: `mailTime.pause(); await mailTime.drain();`.
    * @returns {boolean} `true` if newly paused; `false` if already paused, a client instance, or destroyed
    */
   pause() {
@@ -566,6 +634,9 @@ class MailTime {
     const paused = this.scheduler.pause();
     if (paused) {
       this.__isPaused = true;
+      if (this.__schedulerScans > 0) {
+        this.__pool.cancelQueued();
+      }
     }
     return paused;
   }
@@ -646,7 +717,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 +878,7 @@ class MailTime {
       uuid: randomUUID(),
       tries: 0,
       isSent: false,
+      isSettled: false,
       sendAt: opts.sendAt,
       isFailed: false,
       isSending: false,
@@ -889,9 +962,11 @@ class MailTime {
       compiledOpts = deepMerge(compiledOpts, transport.options.mailOptions);
     }
 
-    compiledOpts.html ??= '';
-    compiledOpts.text ??= '';
-    compiledOpts.subject ??= '';
+    for (const field of ['html', 'text', 'subject']) {
+      if (compiledOpts[field] === void 0 || compiledOpts[field] === null) {
+        compiledOpts[field] = '';
+      }
+    }
 
     const mailOptionsList = task.mailOptions || [];
     const isMulti = mailOptionsList.length > 1;
@@ -939,7 +1014,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 +1227,7 @@ class MailTime {
     };
 
     const renew = async () => {
-      if (stopped || this.__isDestroyed || this.__abortInFlight) {
+      if (stopped || this.__abortInFlight) {
         halt();
         return;
       }
@@ -1205,17 +1280,215 @@ 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
    * @memberOf MailTime
    * @name ___dispatch
-   * @description Queue full-lifecycle send for `task` under the bounded send pool. Resolves as soon as a pool slot is acquired and the send has started — the SMTP roundtrip continues in the background so the adapter's `iterate` can move on to the next due row and the JoSk lease can be released. Call `await mailTime.drain()` to await in-flight sends; use `destroy({ drain: true })` for graceful shutdown.
+   * @description Queue full-lifecycle send for `task` under the bounded send pool. No-op after `destroy()`, or while paused during a scheduler-driven scan; `destroy()` and `pause()` also drop jobs still waiting for a slot. Resolves as soon as a pool slot is acquired and the send has started — the SMTP roundtrip continues in the background so the adapter's `iterate` can move on to the next due row and the JoSk lease can be released. Call `await mailTime.drain()` to await in-flight sends; use `destroy({ drain: true })` for graceful shutdown.
    * @param {MailTimeTask} task - email's task object from Storage
    * @returns {Promise<void 0>}
    */
   async ___dispatch(task) {
-    if (this.__isDestroyed) {
+    if (this.___isStopped) {
       return;
     }
     if (!task || task.isSent === true || task.isFailed === true || task.isCancelled === true) {
@@ -1226,9 +1499,9 @@ class MailTime {
       return;
     }
     this.__inFlight.add(task.uuid);
-    await this.__pool.dispatch(async () => {
+    const started = await this.__pool.dispatch(async () => {
       try {
-        if (this.__isDestroyed) {
+        if (this.___isStopped) {
           return;
         }
         await this.___send(task);
@@ -1236,6 +1509,20 @@ class MailTime {
         this.__inFlight.delete(task.uuid);
       }
     });
+    if (!started) {
+      this.__inFlight.delete(task.uuid);
+    }
+  }
+
+  /**
+   * @internal
+   * @memberOf MailTime
+   * @name ___isStopped
+   * @description `true` after `destroy()`, or while paused during a scheduler-driven scan. Queue adapters check it to end an `iterate` scan early.
+   * @returns {boolean}
+   */
+  get ___isStopped() {
+    return this.__isDestroyed || (this.__isPaused && this.__schedulerScans > 0);
   }
 
   /**
@@ -1248,6 +1535,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) {
@@ -1444,10 +1737,15 @@ class MailTime {
       return;
     }
     const limit = this.mode === 'one' ? 1 : Infinity;
-    return await this.queue.iterate({
-      limit,
-      sendingTimeout: this.sendingTimeout,
-    });
+    this.__schedulerScans++;
+    try {
+      return await this.queue.iterate({
+        limit,
+        sendingTimeout: this.sendingTimeout,
+      });
+    } finally {
+      this.__schedulerScans--;
+    }
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-time",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "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,18 +139,22 @@
   },
   "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",
     "@types/node": "^25.9.0",
+    "acorn": "^8.18.0",
     "chai": "^6.2.2",
     "jest": "^30.4.2",
     "mocha": "^11.8.0",