mail-time 5.0.0 → 5.2.0

package/index.cjs

@@ -371,6 +371,7 @@ class MongoQueue {
    */
   constructor (opts) {
     this.name = 'mongo-queue';
+    this.supportsRecipientPolicies = true;
     if (!opts || typeof opts !== 'object') {
       throw new TypeError('[mail-time] Configuration object must be passed into MongoQueue constructor');
     }
@@ -391,8 +392,8 @@ class MongoQueue {
     this.collection = this.db.collection(`__mailTimeQueue__${prefix}`);
     this.__readyPromise = Promise.all([
       ensureIndex(this.collection, { uuid: 1 }, { background: false }),
-      ensureIndex(this.collection, { isSent: 1, isFailed: 1, isCancelled: 1, to: 1, sendAt: 1 }, { background: false }),
-      ensureIndex(this.collection, { isSent: 1, isFailed: 1, isCancelled: 1, isSending: 1, sendingAt: 1, sendAt: 1, tries: 1 }, { background: false }),
+      ensureIndex(this.collection, { isSettled: 1, isSent: 1, isFailed: 1, isCancelled: 1, to: 1, sendAt: 1 }, { name: 'mailtime_policy_pending_to_v1', background: false }),
+      ensureIndex(this.collection, { isSettled: 1, isSent: 1, isFailed: 1, isCancelled: 1, isSending: 1, sendingAt: 1, sendAt: 1, tries: 1 }, { name: 'mailtime_policy_due_v1', background: false }),
     ]).then(() => void 0);
   }
 
@@ -491,12 +492,13 @@ class MongoQueue {
         sendAt: {
           $lte: now,
         },
-        tries: {
-          $lt: this.mailTimeInstance.maxTries,
-        },
-        $or: [
-          { isSending: { $ne: true } },
-          { sendingAt: { $lte: now - sendingTimeout } },
+        isSettled: { $ne: true },
+        $and: [
+          { $or: [{ isSending: { $ne: true } }, { sendingAt: { $lte: now - sendingTimeout } }] },
+          { $or: [
+            { tries: { $lt: this.mailTimeInstance.maxTries } },
+            { recipientResults: { $type: 'array' }, isSending: true, sendingAt: { $lte: now - sendingTimeout } },
+          ] },
         ],
       }, {
         projection: {
@@ -512,6 +514,8 @@ class MongoQueue {
           sendingAt: 1,
           mailOptions: 1,
           concatSubject: 1,
+          isSettled: 1,
+          recipientResults: 1,
         },
       });
 
@@ -553,6 +557,8 @@ class MongoQueue {
       isFailed: false,
       isCancelled: false,
       isSending: { $ne: true },
+      isSettled: { $ne: true },
+      recipientResults: { $exists: false },
       tries: { $lt: this.mailTimeInstance.maxTries },
       sendAt: {
         $lte: sendAt,
@@ -566,6 +572,8 @@ class MongoQueue {
         isSent: 1,
         isFailed: 1,
         isCancelled: 1,
+        isSettled: 1,
+        recipientResults: 1,
         mailOptions: 1,
       },
     });
@@ -613,20 +621,20 @@ class MongoQueue {
         uuid: 1,
         isSent: 1,
         isCancelled: 1,
+        isSettled: 1,
       },
     });
 
-    if (!task || task.isSent === true || task.isCancelled === true) {
+    if (!task || task.isSent === true || task.isCancelled === true || task.isSettled === true) {
       return false;
     }
-
+    const query = { _id: task._id, isSent: false, isCancelled: false, isSettled: { $ne: true },
+      $or: [{ recipientResults: { $exists: false } }, { isFailed: false }] };
     if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(task);
+      return ((await this.collection.deleteOne(query))?.deletedCount || 0) >= 1;
     }
-
-    return await this.update(task, {
-      isCancelled: true,
-    });
+    const result = await this.collection.updateOne(query, { $set: { isCancelled: true } });
+    return (result?.matchedCount || result?.modifiedCount || 0) >= 1;
   }
 
   /**
@@ -647,6 +655,8 @@ class MongoQueue {
 
     const query = { _id: task._id };
     if (isSendLeaseRemove(opts)) {
+      query.isSent = false;
+      query.isSettled = { $ne: true };
       query.tries = opts.leaseTries;
       query.isSending = true;
       query.sendingAt = opts.leaseSendingAt;
@@ -673,6 +683,8 @@ class MongoQueue {
       return false;
     }
     this.__ensurePrefix();
+    if ((hasOwnProp(updateObj, 'recipientResults') || hasOwnProp(updateObj, 'isSettled'))
+      && !isSendClaimUpdate(updateObj) && !isSendLeaseGuardedUpdate(updateObj)) return false;
 
     if (isAppendMailOptionUpdate(updateObj)) {
       const res = await this.collection.updateOne({
@@ -681,6 +693,8 @@ class MongoQueue {
         isFailed: false,
         isCancelled: false,
         isSending: { $ne: true },
+        isSettled: { $ne: true },
+        recipientResults: { $exists: false },
       }, {
         $push: {
           mailOptions: updateObj.appendMailOption,
@@ -699,12 +713,15 @@ class MongoQueue {
       query.isSent = false;
       query.isFailed = false;
       query.isCancelled = false;
+      query.isSettled = { $ne: true };
       query.tries = task.tries;
       query.$or = [
         { isSending: { $ne: true } },
         { sendingAt: { $lte: now - sendingTimeout } },
       ];
     } else if (isSendLeaseGuardedUpdate(updateObj)) {
+      query.isSent = false;
+      query.isSettled = { $ne: true };
       query.tries = updateObj.leaseTries;
       query.isSending = true;
       query.sendingAt = updateObj.leaseSendingAt;
@@ -715,7 +732,7 @@ class MongoQueue {
     const res = await this.collection.updateOne(query, {
       $set: stripInternalUpdateMeta(updateObj),
     });
-    if (isSendClaimUpdate(updateObj)) {
+    if (isSendClaimUpdate(updateObj) || isSendLeaseGuardedUpdate(updateObj)) {
       return (res?.modifiedCount || res?.matchedCount || 0) >= 1;
     }
     return (res?.modifiedCount || 0) >= 1;
@@ -728,8 +745,15 @@ class MongoQueue {
  * @property {(key: string) => Promise<string|null>} get
  * @property {(key: string, value: string, options?: object) => Promise<unknown>} set
  * @property {(key: string|string[]) => Promise<number>} del
- * @property {() => Promise<string>} ping
- * @property {(options: object) => AsyncIterable<string|string[]>} scanIterator
+ * @property {() => Promise<string>} [ping]
+ * @property {() => unknown} [getRandomNode]
+ * @property {(...args: any[]) => any} [nodeClient]
+ * @property {(firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>} [sendCommand]
+ * @property {(options: object) => AsyncIterable<string|string[]>} [scanIterator]
+ * @property {(key: string, field: string) => Promise<string|null|undefined>} [hGet]
+ * @property {(script: string, options: { keys: string[], arguments: string[] }) => Promise<unknown>} [eval]
+ * @property {(sha: string, options: { keys: string[], arguments: string[] }) => Promise<unknown>} [evalSha]
+ * @property {(script: string) => Promise<string>} [scriptLoad]
  * @property {(key: string) => Promise<unknown>} [watch]
  * @property {() => Promise<unknown>} [unwatch]
  * @property {() => object} [multi]
@@ -739,10 +763,189 @@ class MongoQueue {
  * @typedef {object} RedisQueueOption
  * @property {RedisClient} client
  * @property {string} [prefix]
+ * @property {boolean} [useHashTags] - Use Redis Cluster hash-tag keys (`mailtime:{prefix}:*`). Default keeps existing standalone keys.
  */
 
 const KEY_TYPES = new Set(['letter', 'sendat', 'concatletter']);
 const DEFAULT_PREFIX$1 = 'default';
+const VALID_PREFIX = /^[A-Za-z0-9_\-:.]+$/;
+const TAGGED_ITERATE_LIMIT = 100;
+const clientTransactions = new WeakMap();
+
+const PUSH_TAGGED_TASK_SCRIPT = `
+  redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+  redis.call('ZADD', KEYS[2], tonumber(ARGV[3]), ARGV[1])
+  if #KEYS > 3 then
+    redis.call('SET', KEYS[3], ARGV[1], 'PXAT', tonumber(ARGV[4]))
+    redis.call('ZADD', KEYS[4], tonumber(ARGV[4]), KEYS[3])
+  end
+  return 1
+`;
+
+const ITERATE_TAGGED_TASKS_SCRIPT = `
+  local now = tonumber(ARGV[1])
+  local maxTries = tonumber(ARGV[2])
+  local sendingTimeout = tonumber(ARGV[3])
+  local limit = tonumber(ARGV[4])
+  local scanLimit = tonumber(ARGV[5])
+  local tasks = {}
+  if #KEYS > 2 then
+    local expiredPointers = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', now, 'LIMIT', 0, 100)
+    for _, pointerKey in ipairs(expiredPointers) do
+      redis.call('DEL', pointerKey)
+      redis.call('ZREM', KEYS[3], pointerKey)
+    end
+  end
+  local due = redis.call('ZRANGEBYSCORE', KEYS[2], '-inf', now, 'LIMIT', 0, scanLimit)
+  for _, uuid in ipairs(due) do
+    local payload = redis.call('HGET', KEYS[1], uuid)
+    if not payload then
+      redis.call('ZREM', KEYS[2], uuid)
+    else
+      local task = cjson.decode(payload)
+      if task.isSent or task.isFailed or task.isCancelled or task.isSettled then
+        redis.call('ZREM', KEYS[2], uuid)
+      elseif tonumber(task.tries or 0) >= maxTries and not (type(task.recipientResults) == 'table' and task.isSending) then
+        redis.call('ZREM', KEYS[2], uuid)
+      elseif task.isSending then
+        local eligibleAt = tonumber(task.sendingAt or 0) + sendingTimeout
+        if eligibleAt > now then
+          redis.call('ZADD', KEYS[2], eligibleAt, uuid)
+        else
+          table.insert(tasks, payload)
+        end
+      elseif tonumber(task.sendAt or 0) <= now then
+        table.insert(tasks, payload)
+      else
+        redis.call('ZADD', KEYS[2], tonumber(task.sendAt), uuid)
+      end
+      if #tasks >= limit then
+        break
+      end
+    end
+  end
+
+  return cjson.encode(tasks)
+`;
+
+const UPDATE_TAGGED_TASK_SCRIPT = `
+  local payload = redis.call('HGET', KEYS[1], ARGV[1])
+  if not payload then
+    redis.call('ZREM', KEYS[2], ARGV[1])
+    return 0
+  end
+
+  local task = cjson.decode(payload)
+  local update = cjson.decode(ARGV[2])
+  local mode = ARGV[3]
+  local now = tonumber(ARGV[4])
+  local sendingTimeout = tonumber(ARGV[5])
+  local expectedTries = tonumber(ARGV[6])
+  local leaseSendingAt = tonumber(ARGV[7])
+  if payload ~= ARGV[8] then return -1 end
+
+  if mode == 'claim' then
+    if task.isSent or task.isFailed or task.isCancelled or task.isSettled or tonumber(task.tries or 0) ~= expectedTries then
+      return 0
+    end
+    if task.isSending and tonumber(task.sendingAt or 0) > now - sendingTimeout then
+      return 0
+    end
+  elseif mode == 'lease' then
+    if task.isSent or task.isSettled or task.isCancelled or task.isFailed or not task.isSending
+      or tonumber(task.tries or 0) ~= expectedTries
+      or tonumber(task.sendingAt or 0) ~= leaseSendingAt then
+      return 0
+    end
+  end
+
+  if mode == 'cancel' and (task.isSent or task.isSettled or task.isCancelled
+    or (type(task.recipientResults) == 'table' and task.isFailed)) then
+    return 0
+  end
+  for key, value in pairs(update) do
+    task[key] = value
+  end
+  redis.call('HSET', KEYS[1], ARGV[1], ARGV[9])
+
+  if task.isSent or task.isFailed or task.isCancelled or task.isSettled then
+    redis.call('ZREM', KEYS[2], ARGV[1])
+    if #KEYS > 3 then
+      local concatUuid = redis.call('GET', KEYS[3])
+      if concatUuid == ARGV[1] then
+        redis.call('DEL', KEYS[3])
+        redis.call('ZREM', KEYS[4], KEYS[3])
+      elseif not concatUuid then
+        redis.call('ZREM', KEYS[4], KEYS[3])
+      end
+    end
+  elseif task.isSending then
+    redis.call('ZADD', KEYS[2], tonumber(task.sendingAt or now) + sendingTimeout, ARGV[1])
+  else
+    redis.call('ZADD', KEYS[2], tonumber(task.sendAt), ARGV[1])
+  end
+  return 1
+`;
+
+const APPEND_TAGGED_MAIL_OPTION_SCRIPT = `
+  local payload = redis.call('HGET', KEYS[1], ARGV[1])
+  if not payload then
+    return 0
+  end
+  local task = cjson.decode(payload)
+  if task.isSending or task.isSent or task.isFailed or task.isCancelled or task.isSettled or type(task.recipientResults) == 'table' then
+    return 0
+  end
+  if payload ~= ARGV[3] then return -1 end
+  redis.call('HSET', KEYS[1], ARGV[1], ARGV[4])
+  return 1
+`;
+
+const REMOVE_TAGGED_TASK_SCRIPT = `
+  local payload = redis.call('HGET', KEYS[1], ARGV[1])
+  if not payload then
+    redis.call('ZREM', KEYS[2], ARGV[1])
+    return 0
+  end
+  local task = cjson.decode(payload)
+  if ARGV[2] == 'cancel' and (task.isSent or task.isSettled or task.isCancelled
+    or (type(task.recipientResults) == 'table' and task.isFailed)) then return 0 end
+  if ARGV[2] == 'lease' and (task.isSent or task.isSettled or task.isCancelled or task.isFailed or not task.isSending
+    or tonumber(task.tries or 0) ~= tonumber(ARGV[3])
+    or tonumber(task.sendingAt or 0) ~= tonumber(ARGV[4])) then
+    return 0
+  end
+  redis.call('HDEL', KEYS[1], ARGV[1])
+  redis.call('ZREM', KEYS[2], ARGV[1])
+  if #KEYS > 3 then
+    local concatUuid = redis.call('GET', KEYS[3])
+    if concatUuid == ARGV[1] then
+      redis.call('DEL', KEYS[3])
+      redis.call('ZREM', KEYS[4], KEYS[3])
+    elseif not concatUuid then
+      redis.call('ZREM', KEYS[4], KEYS[3])
+    end
+  end
+  return 1
+`;
+
+const normalizePolicyArrays = (task) => {
+  if (task.recipientResults && !Array.isArray(task.recipientResults) && Object.keys(task.recipientResults).length === 0) task.recipientResults = [];
+  if (Array.isArray(task.recipientResults)) {
+    for (const result of task.recipientResults) {
+      for (const field of ['sources', 'reasons']) {
+        if (result[field] && !Array.isArray(result[field]) && Object.keys(result[field]).length === 0) result[field] = [];
+      }
+    }
+  }
+  return task;
+};
+
+const sha1Hex = (string) => crypto.createHash('sha1').update(string).digest('hex');
+
+const isNoScriptError = (error) => {
+  return !!error && (error.code === 'NOSCRIPT' || (typeof error.message === 'string' && error.message.includes('NOSCRIPT')));
+};
 
 const canReleaseLease = (currentTask, updateObj) => {
   return currentTask
@@ -750,6 +953,8 @@ const canReleaseLease = (currentTask, updateObj) => {
     && currentTask.isSending === true
     && (typeof currentTask.sendingAt === 'number' ? currentTask.sendingAt : 0) === updateObj.leaseSendingAt
     && currentTask.isCancelled !== true
+    && currentTask.isSent !== true
+    && currentTask.isSettled !== true
     && currentTask.isFailed !== true;
 };
 
@@ -757,7 +962,7 @@ const canClaimTask = (currentTask, task, now, sendingTimeout) => {
   if (!currentTask) {
     return false;
   }
-  if (currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true) {
+  if (currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true || currentTask.isSettled === true) {
     return false;
   }
   if (currentTask.tries !== task.tries) {
@@ -776,11 +981,11 @@ const isIterateCandidate = (candidate, now, sendingTimeout, maxTries) => {
   if (!candidate || typeof candidate !== 'object') {
     return false;
   }
-  if (candidate.isSent === true || candidate.isFailed === true || candidate.isCancelled === true) {
+  if (candidate.isSent === true || candidate.isFailed === true || candidate.isCancelled === true || candidate.isSettled === true) {
     return false;
   }
   const tries = typeof candidate.tries === 'number' ? candidate.tries : 0;
-  if (tries >= maxTries) {
+  if (tries >= maxTries && !(Array.isArray(candidate.recipientResults) && candidate.isSending === true)) {
     return false;
   }
   if (candidate.isSending === true) {
@@ -808,6 +1013,7 @@ class RedisQueue {
    */
   constructor (opts) {
     this.name = 'redis-queue';
+    this.supportsRecipientPolicies = true;
     if (!opts || typeof opts !== 'object') {
       throw new TypeError('[mail-time] Configuration object must be passed into RedisQueue constructor');
     }
@@ -816,7 +1022,21 @@ class RedisQueue {
       throw new Error('[mail-time] [RedisQueue] required {client} option is missing, e.g. returned from `redis.createClient()` or `redis.createCluster()` method');
     }
 
+    if (opts.useHashTags !== undefined && typeof opts.useHashTags !== 'boolean') {
+      throw new TypeError(`[mail-time] [RedisQueue] {useHashTags} option must be a boolean (received: ${typeof opts.useHashTags})`);
+    }
+
     this.client = opts.client;
+    this.useHashTags = opts.useHashTags === true;
+    this.__scriptSources = {
+      push: PUSH_TAGGED_TASK_SCRIPT,
+      iterate: ITERATE_TAGGED_TASKS_SCRIPT,
+      update: UPDATE_TAGGED_TASK_SCRIPT,
+      append: APPEND_TAGGED_MAIL_OPTION_SCRIPT,
+      remove: REMOVE_TAGGED_TASK_SCRIPT,
+    };
+    this.__scriptShas = Object.fromEntries(Object.entries(this.__scriptSources).map(([name, source]) => [name, sha1Hex(source)]));
+    this.__loadedShas = new Set();
     if (typeof opts.prefix === 'string') {
       this.__applyPrefix(opts.prefix);
     }
@@ -824,8 +1044,16 @@ class RedisQueue {
 
   /** @internal */
   __applyPrefix(prefix) {
+    if (this.useHashTags && !VALID_PREFIX.test(prefix)) {
+      throw new Error(`[mail-time] [RedisQueue] {prefix} option must match ${VALID_PREFIX} when {useHashTags} is true (received: "${prefix}")`);
+    }
     this.prefix = prefix;
-    this.uniqueName = `mailtime:${prefix}`;
+    this.uniqueName = this.useHashTags ? `mailtime:{${prefix}}` : `mailtime:${prefix}`;
+    if (this.useHashTags) {
+      this.lettersKey = `${this.uniqueName}:letters`;
+      this.scheduleKey = `${this.uniqueName}:schedule`;
+      this.concatKeysKey = `${this.uniqueName}:concatkeys`;
+    }
   }
 
   /** @internal */
@@ -840,6 +1068,60 @@ class RedisQueue {
     debug(this.mailTimeInstance?.debug === true, `[${this.name}]`, ...args);
   }
 
+  /** @internal */
+  async __runScript(scriptKey, options) {
+    const source = this.__scriptSources[scriptKey];
+    const sha = this.__scriptShas[scriptKey];
+    if (!source || !sha) {
+      throw new Error(`[mail-time] [RedisQueue] unknown script "${scriptKey}"`);
+    }
+
+    if (this.useHashTags && typeof this.client.nodeClient === 'function' && typeof this.client.sendCommand === 'function') {
+      const key = options.keys[0];
+      const args = [`${options.keys.length}`, ...options.keys, ...options.arguments];
+      try {
+        return await this.client.sendCommand(key, false, ['EVALSHA', sha, ...args]);
+      } catch (error) {
+        if (!isNoScriptError(error)) throw error;
+      }
+      return await this.client.sendCommand(key, false, ['EVAL', source, ...args]);
+    }
+
+    if (this.__loadedShas.has(sha) && typeof this.client.evalSha === 'function') {
+      try {
+        return await this.client.evalSha(sha, options);
+      } catch (error) {
+        if (!isNoScriptError(error)) {
+          throw error;
+        }
+        this.__loadedShas.delete(sha);
+      }
+    }
+
+    if (typeof this.client.scriptLoad === 'function' && typeof this.client.evalSha === 'function') {
+      try {
+        await this.client.scriptLoad(source);
+        this.__loadedShas.add(sha);
+        return await this.client.evalSha(sha, options);
+      } catch (error) {
+        if (!isNoScriptError(error)) {
+          this.__debug(`[script:${scriptKey}] scriptLoad failed; falling back to EVAL`, error);
+        }
+      }
+    }
+
+    if (typeof this.client.eval !== 'function') {
+      throw new Error('[mail-time] [RedisQueue] Redis Cluster client must support EVAL');
+    }
+    return await this.client.eval(source, options);
+  }
+
+  /** @internal */
+  __getTaggedConcatKey(to) {
+    this.__ensurePrefix();
+    return `${this.uniqueName}:concatletter:${to}`;
+  }
+
   /**
    * @async
    * @memberOf RedisQueue
@@ -872,7 +1154,9 @@ class RedisQueue {
     }
 
     try {
-      const ping = await this.client.ping();
+      const pingClient = typeof this.client.ping === 'function' ? this.client
+        : await this.client.nodeClient(this.client.getRandomNode());
+      const ping = await pingClient.ping();
       if (ping === 'PONG') {
         return {
           status: 'OK',
@@ -917,6 +1201,26 @@ class RedisQueue {
       const maxTries = (this.mailTimeInstance && typeof this.mailTimeInstance.maxTries === 'number')
         ? this.mailTimeInstance.maxTries
         : 60;
+
+      if (this.useHashTags) {
+        this.__ensurePrefix();
+        const dispatchLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : TAGGED_ITERATE_LIMIT;
+        const payload = await this.__runScript('iterate', {
+          keys: [this.lettersKey, this.scheduleKey, this.concatKeysKey],
+          arguments: [`${now}`, `${maxTries}`, `${sendingTimeout}`, `${dispatchLimit}`, `${Math.max(dispatchLimit * 20, 100)}`],
+        });
+        const candidates = payload ? JSON.parse(String(payload)) : [];
+        if (!Array.isArray(candidates)) {
+          return;
+        }
+        for (const value of candidates) {
+          const candidate = normalizePolicyArrays(typeof value === 'string' ? JSON.parse(value) : value);
+          if (isIterateCandidate(candidate, now, sendingTimeout, maxTries)) {
+            await this.mailTimeInstance.___dispatch(candidate);
+          }
+        }
+        return;
+      }
       let dispatched = 0;
 
       const matchPattern = this.__getKey('*', 'sendat');
@@ -973,20 +1277,21 @@ class RedisQueue {
       return null;
     }
 
-    const concatKey = this.__getKey(to, 'concatletter');
+    const concatKey = this.useHashTags ? this.__getTaggedConcatKey(to) : this.__getKey(to, 'concatletter');
     const uuid = await this.client.get(concatKey);
     if (!uuid) {
       return null;
     }
 
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
+    const taskJSON = this.useHashTags
+      ? await this.client.hGet(this.lettersKey, uuid)
+      : await this.client.get(this.__getKey(uuid, 'letter'));
     if (!taskJSON) {
       return null;
     }
 
     const task = JSON.parse(taskJSON);
-    if (!task || task.isSent === true || task.isCancelled === true || task.isFailed === true || task.sendAt > sendAt || task.isSending === true || task.tries >= this.mailTimeInstance.maxTries) {
+    if (!task || task.isSettled === true || task.recipientResults != null || task.isSent === true || task.isCancelled === true || task.isFailed === true || task.sendAt > sendAt || task.isSending === true || task.tries >= this.mailTimeInstance.maxTries) {
       return null;
     }
 
@@ -1011,6 +1316,19 @@ class RedisQueue {
       task.sendAt = +task.sendAt;
     }
 
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+      const keys = [this.lettersKey, this.scheduleKey];
+      const args = [task.uuid, JSON.stringify(task), `${+task.sendAt}`];
+      if (task.to) {
+        keys.push(this.__getTaggedConcatKey(task.to));
+        keys.push(this.concatKeysKey);
+        args.push(`${task.sendAt - 128}`);
+      }
+      await this.__runScript('push', { keys, arguments: args });
+      return;
+    }
+
     const letterKey = this.__getKey(task.uuid, 'letter');
     const sendatKey = this.__getKey(task.uuid, 'sendat');
     const taskJSON = JSON.stringify(task);
@@ -1046,30 +1364,59 @@ class RedisQueue {
    * @returns {Promise<boolean>} returns `true` if cancelled or `false` if not found, was sent, or was cancelled previously
    */
   async cancel(uuid) {
+    return await this.__serialize(() => this.__cancel(uuid));
+  }
+
+  /** @internal */
+  async __serialize(operation) {
+    if (this.useHashTags) return await operation();
+    const previous = clientTransactions.get(this.client) || Promise.resolve();
+    const pending = previous.then(operation);
+    const settled = pending.catch(() => void 0);
+    clientTransactions.set(this.client, settled);
+    try { return await pending; }
+    finally { if (clientTransactions.get(this.client) === settled) clientTransactions.delete(this.client); }
+  }
+
+  /** @internal */
+  async __cancel(uuid) {
     this.__debug('[cancel]', uuid);
     if (typeof uuid !== 'string') {
       return false;
     }
 
-    await this.client.del(this.__getKey(uuid, 'sendat'));
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
-    if (!taskJSON) {
-      return false;
-    }
-
-    const task = JSON.parse(taskJSON);
-    if (!task || task.isSent === true || task.isCancelled === true) {
+    this.__ensurePrefix();
+    const atomic = typeof this.client.watch === 'function' && typeof this.client.multi === 'function';
+    const letterKey = this.__getKey(uuid);
+    try {
+      if (!this.useHashTags && atomic) await this.client.watch(letterKey);
+      const payload = this.useHashTags ? await this.client.hGet(this.lettersKey, uuid) : await this.client.get(letterKey);
+      const task = payload ? JSON.parse(payload) : null;
+      if (!task || task.isSent || task.isCancelled || task.isSettled || (task.recipientResults != null && task.isFailed)) return false;
+      if (this.useHashTags) {
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) keys.push(this.__getTaggedConcatKey(task.to), this.concatKeysKey);
+        const keep = this.mailTimeInstance.keepHistory;
+        const args = keep
+          ? [uuid, JSON.stringify({ isCancelled: true }), 'cancel', `${Date.now()}`, `${this.mailTimeInstance.sendingTimeout || 300000}`, '0', '0', payload, JSON.stringify({ ...task, isCancelled: true })]
+          : [uuid, 'cancel', '0', '0'];
+        return Number(await this.__runScript(keep ? 'update' : 'remove', { keys, arguments: args })) >= 1;
+      }
+      if (!atomic) {
+        if (task.recipientResults != null) return false;
+        return this.mailTimeInstance.keepHistory ? await this.__update(task, { isCancelled: true }) : await this.__remove(task);
+      }
+      const multi = this.client.multi();
+      if (this.mailTimeInstance.keepHistory) multi.set(letterKey, JSON.stringify({ ...task, isCancelled: true }));
+      else multi.del(letterKey);
+      multi.del(this.__getKey(uuid, 'sendat'));
+      return (await multi.exec()) !== null;
+    } catch (error) {
+      logError('[cancel] storage error', error);
       return false;
+    } finally {
+      if (!this.useHashTags && atomic) await this.client.unwatch?.();
     }
-
-    if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(task);
-    }
-
-    return await this.update(task, {
-      isCancelled: true,
-    });
   }
 
   /**
@@ -1082,11 +1429,40 @@ class RedisQueue {
    * @returns {Promise<boolean>} returns `true` if removed or `false` if not found
    */
   async remove(task, opts) {
+    return await this.__serialize(() => this.__remove(task, opts));
+  }
+
+  /** @internal */
+  async __remove(task, opts) {
     this.__debug('[remove]', task?.uuid);
     if (!task || typeof task !== 'object' || typeof task.uuid !== 'string') {
       return false;
     }
 
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+      try {
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) {
+          keys.push(this.__getTaggedConcatKey(task.to));
+          keys.push(this.concatKeysKey);
+        }
+        const result = await this.__runScript('remove', {
+          keys,
+          arguments: [
+            task.uuid,
+            isSendLeaseRemove(opts) ? 'lease' : 'plain',
+            `${opts?.leaseTries || 0}`,
+            `${opts?.leaseSendingAt || 0}`,
+          ],
+        });
+        return Number(result) >= 1;
+      } catch (opError) {
+        logError('[remove] [tagged] [opError]', opError);
+        return false;
+      }
+    }
+
     const letterKey = this.__getKey(task.uuid, 'letter');
     if (isSendLeaseRemove(opts)) {
       if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
@@ -1104,6 +1480,8 @@ class RedisQueue {
           || currentTask.isSending !== true
           || (typeof currentTask.sendingAt === 'number' ? currentTask.sendingAt : 0) !== opts.leaseSendingAt
           || currentTask.isCancelled === true
+          || currentTask.isSent === true
+          || currentTask.isSettled === true
           || currentTask.isFailed === true) {
           await this.client.unwatch?.();
           return false;
@@ -1147,6 +1525,11 @@ class RedisQueue {
    * @returns {Promise<boolean>} returns `true` if updated or `false` if not found or no changes was made
    */
   async update(task, updateObj) {
+    return await this.__serialize(() => this.__update(task, updateObj));
+  }
+
+  /** @internal */
+  async __update(task, updateObj) {
     this.__debug('[update]', task?.uuid);
     if (!task || typeof task !== 'object' || typeof task.uuid !== 'string' || !updateObj || typeof updateObj !== 'object') {
       return false;
@@ -1157,10 +1540,43 @@ class RedisQueue {
     const isClaim = isSendClaimUpdate(updateObj);
     const isAppend = isAppendMailOptionUpdate(updateObj);
     const isLeaseRelease = isSendLeaseGuardedUpdate(updateObj);
+    if ((hasOwnProp(updateObj, 'recipientResults') || hasOwnProp(updateObj, 'isSettled')) && !isClaim && !isLeaseRelease) return false;
     const now = isClaim && typeof updateObj.sendingAt === 'number' ? updateObj.sendingAt : Date.now();
     const sendingTimeout = this.mailTimeInstance?.sendingTimeout || 300000;
 
     try {
+      if (this.useHashTags) {
+        // JS serialization preserves empty arrays and scalar values that Lua cjson changes.
+        // The script compares the exact payload as well as the claim/lease predicates.
+        for (let attempt = 0; attempt < 3; attempt++) {
+          const payload = await this.client.hGet(this.lettersKey, task.uuid);
+          if (!payload) return false;
+          const current = normalizePolicyArrays(JSON.parse(payload));
+          const persist = stripInternalUpdateMeta(updateObj);
+          const next = isAppend
+            ? { ...current, mailOptions: [...(current.mailOptions || []), updateObj.appendMailOption] }
+            : { ...current, ...persist };
+          if (isAppend) {
+            const result = Number(await this.__runScript('append', {
+              keys: [this.lettersKey],
+              arguments: [task.uuid, JSON.stringify(updateObj.appendMailOption), payload, JSON.stringify(next)],
+            }));
+            if (result === -1) continue;
+            return result >= 1;
+          }
+          const keys = [this.lettersKey, this.scheduleKey];
+          if (current.to) keys.push(this.__getTaggedConcatKey(current.to), this.concatKeysKey);
+          const result = Number(await this.__runScript('update', {
+            keys,
+            arguments: [task.uuid, JSON.stringify(persist), isClaim ? 'claim' : (isLeaseRelease ? 'lease' : 'plain'),
+              `${now}`, `${sendingTimeout}`, `${isClaim ? task.tries : (updateObj.leaseTries || 0)}`,
+              `${updateObj.leaseSendingAt || 0}`, payload, JSON.stringify(next)],
+          }));
+          if (result !== -1) return result >= 1;
+        }
+        return false;
+      }
+
       if (isAppend) {
         if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
           if (!RedisQueue.__atomicAppendWarned) {
@@ -1172,7 +1588,7 @@ class RedisQueue {
             return false;
           }
           const currentTask = JSON.parse(taskJSON);
-          if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true) {
+          if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true || currentTask.isSettled === true || Array.isArray(currentTask.recipientResults)) {
             return false;
           }
           currentTask.mailOptions = [...(currentTask.mailOptions || []), updateObj.appendMailOption];
@@ -1187,7 +1603,7 @@ class RedisQueue {
           return false;
         }
         const currentTask = JSON.parse(taskJSON);
-        if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true) {
+        if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true || currentTask.isSettled === true || Array.isArray(currentTask.recipientResults)) {
           await this.client.unwatch?.();
           return false;
         }
@@ -1227,7 +1643,7 @@ class RedisQueue {
         const updatedTask = { ...currentTask, ...stripInternalUpdateMeta(updateObj) };
         const multi = this.client.multi();
         multi.set(letterKey, JSON.stringify(updatedTask));
-        if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true) {
+        if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true || updatedTask.isSettled === true) {
           multi.del(sendatKey);
         } else if (updatedTask.sendAt) {
           multi.set(sendatKey, `${+updatedTask.sendAt}`);
@@ -1246,7 +1662,7 @@ class RedisQueue {
       const updatedTask = { ...currentTask, ...stripInternalUpdateMeta(updateObj) };
       await this.client.set(letterKey, JSON.stringify(updatedTask));
 
-      if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true) {
+      if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true || updatedTask.isSettled === true) {
         await this.client.del(sendatKey);
       } else if (updatedTask.sendAt) {
         await this.client.set(sendatKey, `${+updatedTask.sendAt}`);
@@ -1272,6 +1688,15 @@ class RedisQueue {
       throw new Error(`[mail-time] [RedisQueue] [__getKey] unsupported key "${type}" passed into the second argument`);
     }
     this.__ensurePrefix();
+    if (this.useHashTags) {
+      if (type === 'letter') {
+        return this.lettersKey;
+      }
+      if (type === 'sendat') {
+        return this.scheduleKey;
+      }
+      return this.__getTaggedConcatKey(uuid);
+    }
     return `${this.uniqueName}:${type}:${uuid}`;
   }
 }
@@ -1315,6 +1740,8 @@ const fieldMap = {
   tries: 'tries',
   sendAt: 'send_at',
   isSent: 'is_sent',
+  isSettled: 'is_settled',
+  recipientResults: 'recipient_results',
   isCancelled: 'is_cancelled',
   isFailed: 'is_failed',
   isSending: 'is_sending',
@@ -1344,6 +1771,8 @@ const normalizeRow = (row) => {
     tries: parseInt(row.tries, 10),
     sendAt: parseInt(row.send_at, 10),
     isSent: row.is_sent,
+    isSettled: row.is_settled === true,
+    recipientResults: row.recipient_results == null ? void 0 : parseMailOptions(row.recipient_results),
     isCancelled: row.is_cancelled,
     isFailed: row.is_failed,
     isSending: row.is_sending === true,
@@ -1363,6 +1792,7 @@ class PostgresQueue {
    */
   constructor(opts) {
     this.name = 'postgres-queue';
+    this.supportsRecipientPolicies = true;
     if (!opts || typeof opts !== 'object') {
       throw new TypeError('[mail-time] Configuration object must be passed into PostgresQueue constructor');
     }
@@ -1423,6 +1853,8 @@ class PostgresQueue {
           tries INTEGER NOT NULL DEFAULT 0,
           send_at BIGINT NOT NULL,
           is_sent BOOLEAN NOT NULL DEFAULT false,
+          is_settled BOOLEAN NOT NULL DEFAULT false,
+          recipient_results JSONB,
           is_cancelled BOOLEAN NOT NULL DEFAULT false,
           is_failed BOOLEAN NOT NULL DEFAULT false,
           is_sending BOOLEAN NOT NULL DEFAULT false,
@@ -1434,14 +1866,16 @@ class PostgresQueue {
           created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
           updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
         )`);
+      await this.client.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS is_settled BOOLEAN NOT NULL DEFAULT false');
+      await this.client.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS recipient_results JSONB');
       await this.client.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_mail_time_queue_prefix_uuid
         ON mail_time_queue (prefix, uuid)`);
 
-      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_due
-        ON mail_time_queue (prefix, is_sent, is_failed, is_cancelled, is_sending, sending_at, send_at, tries)`);
+      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_due_v1
+        ON mail_time_queue (prefix, is_settled, is_sent, is_failed, is_cancelled, is_sending, sending_at, send_at, tries)`);
 
-      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_pending_to
-        ON mail_time_queue (prefix, to_address, is_sent, is_failed, is_cancelled, send_at)`);
+      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_pending_to_v1
+        ON mail_time_queue (prefix, to_address, is_settled, is_sent, is_failed, is_cancelled, send_at)`);
     } finally {
       await this.client.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
     }
@@ -1516,14 +1950,15 @@ class PostgresQueue {
 
     try {
       const res = await this.client.query(`SELECT id, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-               is_sending, sending_at, template, transport, concat_subject, mail_options
+               is_sending, sending_at, template, transport, concat_subject, mail_options, is_settled, recipient_results
         FROM mail_time_queue
         WHERE prefix = $1
           AND is_sent = false
           AND is_failed = false
           AND is_cancelled = false
+          AND is_settled = false
           AND send_at <= $2
-          AND tries < $3
+          AND (tries < $3 OR (recipient_results IS NOT NULL AND is_sending = true AND sending_at <= $4))
           AND (is_sending = false OR sending_at <= $4)
         ORDER BY send_at ASC
         LIMIT $5`, [this.prefix, now, this.mailTimeInstance.maxTries, now - sendingTimeout, limit]);
@@ -1554,7 +1989,7 @@ class PostgresQueue {
     await this.ready();
 
     const res = await this.client.query(`SELECT id, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-             is_sending, sending_at, template, transport, concat_subject, mail_options
+             is_sending, sending_at, template, transport, concat_subject, mail_options, is_settled, recipient_results
       FROM mail_time_queue
       WHERE prefix = $1
         AND to_address = $2
@@ -1562,6 +1997,8 @@ class PostgresQueue {
         AND is_failed = false
         AND is_cancelled = false
         AND is_sending = false
+        AND is_settled = false
+        AND recipient_results IS NULL
         AND tries < $4
         AND send_at <= $3
       ORDER BY send_at DESC
@@ -1592,9 +2029,9 @@ class PostgresQueue {
 
     await this.client.query(`INSERT INTO mail_time_queue (
         prefix, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-        is_sending, sending_at, template, transport, concat_subject, mail_options, created_at, updated_at
+        is_sending, sending_at, template, transport, concat_subject, mail_options, is_settled, recipient_results, created_at, updated_at
       )
-      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
       ON CONFLICT (prefix, uuid) DO UPDATE SET
         to_address = EXCLUDED.to_address,
         tries = EXCLUDED.tries,
@@ -1608,6 +2045,8 @@ class PostgresQueue {
         transport = EXCLUDED.transport,
         concat_subject = EXCLUDED.concat_subject,
         mail_options = EXCLUDED.mail_options,
+        is_settled = EXCLUDED.is_settled,
+        recipient_results = EXCLUDED.recipient_results,
         updated_at = CURRENT_TIMESTAMP`, [
       this.prefix,
       task.uuid,
@@ -1623,6 +2062,8 @@ class PostgresQueue {
       task.transport,
       task.concatSubject || null,
       JSON.stringify(task.mailOptions || []),
+      task.isSettled === true,
+      task.recipientResults === void 0 ? null : JSON.stringify(task.recipientResults),
     ]);
   }
 
@@ -1643,23 +2084,20 @@ class PostgresQueue {
     await this.ready();
 
     const task = normalizeRow((await this.client.query(`SELECT id, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-             template, transport, concat_subject, mail_options
+             template, transport, concat_subject, mail_options, is_settled, recipient_results
       FROM mail_time_queue
       WHERE prefix = $1
         AND uuid = $2
       LIMIT 1`, [this.prefix, uuid])).rows?.[0]);
 
-    if (!task || task.isSent === true || task.isCancelled === true) {
-      return false;
-    }
-
-    if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(task);
-    }
-
-    return await this.update(task, {
-      isCancelled: true,
-    });
+    if (!task || task.isSent === true || task.isCancelled === true || task.isSettled === true) return false;
+    const operation = this.mailTimeInstance.keepHistory
+      ? 'UPDATE mail_time_queue SET is_cancelled = true, updated_at = CURRENT_TIMESTAMP'
+      : 'DELETE FROM mail_time_queue';
+    const result = await this.client.query(`${operation}
+      WHERE prefix = $1 AND uuid = $2 AND is_sent = false AND is_cancelled = false
+        AND is_settled = false AND (recipient_results IS NULL OR is_failed = false)`, [this.prefix, uuid]);
+    return (result.rowCount || 0) >= 1;
   }
 
   /**
@@ -1685,7 +2123,7 @@ class PostgresQueue {
     const params = [this.prefix, value];
     if (isSendLeaseRemove(opts)) {
       params.push(opts.leaseTries, opts.leaseSendingAt);
-      leaseWhere = ` AND tries = $3 AND is_sending = true AND sending_at = $4 AND is_cancelled = false AND is_failed = false`;
+      leaseWhere = ` AND tries = $3 AND is_sending = true AND sending_at = $4 AND is_cancelled = false AND is_failed = false AND is_sent = false AND is_settled = false`;
     }
 
     const res = await this.client.query(`DELETE FROM mail_time_queue
@@ -1710,6 +2148,8 @@ class PostgresQueue {
     }
 
     await this.ready();
+    if ((hasOwnProp(updateObj, 'recipientResults') || hasOwnProp(updateObj, 'isSettled'))
+      && !isSendClaimUpdate(updateObj) && !isSendLeaseGuardedUpdate(updateObj)) return false;
 
     if (isAppendMailOptionUpdate(updateObj)) {
       const where = task.id ? 'id = $3' : 'uuid = $3';
@@ -1722,7 +2162,9 @@ class PostgresQueue {
           AND is_sent = false
           AND is_failed = false
           AND is_cancelled = false
-          AND is_sending = false`, [
+          AND is_sending = false
+          AND is_settled = false
+          AND recipient_results IS NULL`, [
         JSON.stringify([updateObj.appendMailOption]),
         this.prefix,
         value,
@@ -1742,7 +2184,7 @@ class PostgresQueue {
       if (key === 'sendAt' && value instanceof Date) {
         value = +value;
       }
-      if (key === 'mailOptions') {
+      if (key === 'mailOptions' || key === 'recipientResults') {
         value = JSON.stringify(value);
       }
 
@@ -1766,6 +2208,7 @@ class PostgresQueue {
         AND is_sent = false
         AND is_failed = false
         AND is_cancelled = false
+        AND is_settled = false
         AND tries = $${triesIndex}
         AND (is_sending = false OR sending_at <= $${staleIndex})
       `;
@@ -1775,6 +2218,8 @@ class PostgresQueue {
       values.push(updateObj.leaseSendingAt);
       const sendingAtIndex = values.length;
       claimWhere = `
+        AND is_sent = false
+        AND is_settled = false
         AND tries = $${triesIndex}
         AND is_sending = true
         AND sending_at = $${sendingAtIndex}
@@ -1990,6 +2435,316 @@ const mailTimePreset = (name, overrides) => {
   return overrides ? deepMerge(cloned, overrides) : cloned;
 };
 
+const policyError = (message) => new Error(`[mail-time] [recipientPolicies] ${message}`);
+const SIMPLE_MAILBOX = /^[^\s<>,;:"()\\\[\]@]+@[^\s<>,;:"()\\\[\]@]+$/u;
+
+const normalizePolicyAddress = (value) => {
+  const input = typeof value === 'string' ? value : (!Array.isArray(value) && value?.address);
+  if (typeof input !== 'string' || /[\r\n]/u.test(input)) {
+    throw policyError('recipient requires a simple address without line breaks');
+  }
+  let address = input.trim();
+  if (address.includes('<') || address.includes('>')) {
+    const match = address.match(/^[^<>,;:"\r\n]*<([^<>]+)>$/u);
+    if (!match) throw policyError('use a simple explicit envelope.to');
+    address = match[1].trim();
+  }
+  if (!SIMPLE_MAILBOX.test(address)) throw policyError('use a simple explicit envelope.to');
+  return address.toLowerCase();
+};
+
+const preparePolicyEnvelope = (compiled, previousResults = []) => {
+  const recipients = new Map();
+  const explicit = compiled.envelope && hasOwnProp(compiled.envelope, 'to');
+  const add = (value, source, authoritative) => {
+    for (const entry of Array.isArray(value) ? value : [value]) {
+      let address;
+      try { address = normalizePolicyAddress(entry); }
+      catch (error) { if (authoritative) throw error; else continue; }
+      if (!recipients.has(address)) {
+        if (!authoritative) continue;
+        recipients.set(address, { address, sources: [] });
+      }
+      const sources = recipients.get(address).sources;
+      if (!sources.includes(source)) sources.push(source);
+    }
+  };
+  if (explicit) add(compiled.envelope.to, 'envelope', true);
+  for (const source of ['to', 'cc', 'bcc']) {
+    if (hasOwnProp(compiled, source) && compiled[source] !== void 0) add(compiled[source], source, !explicit);
+  }
+  if (!recipients.size) throw policyError('envelope must contain at least one recipient');
+  if (previousResults.length && (previousResults.length !== recipients.size || previousResults.some((r) => !recipients.has(r.address)))) {
+    throw policyError('envelope recipient set changed between attempts');
+  }
+  const envelope = { to: [...recipients.keys()] };
+  if (compiled.envelope && hasOwnProp(compiled.envelope, 'from')) {
+    envelope.from = compiled.envelope.from === '' ? '' : normalizePolicyAddress(compiled.envelope.from);
+  } else {
+    const from = compiled.from || compiled.sender || compiled.replyTo;
+    if (from) envelope.from = normalizePolicyAddress(from);
+  }
+  return { envelope, recipients: [...recipients.values()] };
+};
+
+const validateRecipientPolicies = (value, queue) => {
+  if (value === void 0) return null;
+  if (!Array.isArray(value) || !value.length) throw policyError('recipientPolicies must be a nonempty array');
+  if (queue.supportsRecipientPolicies !== true) throw policyError('queue must declare recipient policy support');
+  const names = new Set();
+  return value.map((provider) => {
+    if (!isPlainObject(provider)) throw policyError('each provider must be a plain object');
+    const name = typeof provider.name === 'string' ? provider.name.trim() : '';
+    if (!name || name.length > 128 || names.has(name)) throw policyError('provider names must be unique and contain 1-128 characters');
+    names.add(name);
+    const failureMode = provider.failureMode === void 0 ? 'retry' : provider.failureMode;
+    if (failureMode !== 'retry' && failureMode !== 'continue') throw policyError('failureMode must be retry or continue');
+    const normalized = { name, failureMode };
+    let count = 0;
+    for (const hook of ['beforeSend', 'classifyRejections', 'observeAttempt']) {
+      if (hasOwnProp(provider, hook)) {
+        if (typeof provider[hook] !== 'function') throw policyError(`${hook} must be a function`);
+        normalized[hook] = provider[hook].bind(provider);
+        count++;
+      }
+    }
+    if (!count) throw policyError('provider requires at least one supported hook');
+    return normalized;
+  });
+};
+
+const validatePolicyResult = (raw, hook, context) => {
+  if (raw === void 0) return [];
+  if (!isPlainObject(raw)) throw policyError('hook must return a result object or nothing');
+  if (raw.decisions === void 0) return [];
+  if (!Array.isArray(raw.decisions)) throw policyError('decisions must be an array');
+  const batch = new Set(context.recipients.map((r) => r.address));
+  const attributable = new Set((context.rejections || []).map((r) => r.address).filter(Boolean));
+  const decisions = new Map();
+  for (const item of raw.decisions) {
+    if (!isPlainObject(item)) throw policyError('decision must be an object');
+    const address = normalizePolicyAddress(item.address);
+    if (!batch.has(address)) throw policyError('decision address is outside the input batch');
+    const allowed = hook === 'beforeSend' ? item.status === 'suppressed' : (item.status === 'retry' || item.status === 'rejected');
+    if (!allowed) throw policyError('invalid decision status for this phase');
+    if (item.status === 'rejected' && !attributable.has(address)) throw policyError('permanent rejection requires an attributable record');
+    if (typeof item.reason !== 'string' || !item.reason.trim() || item.reason.length > 512) throw policyError('reason must contain 1-512 characters');
+    const previous = decisions.get(address);
+    if (previous && (previous.status !== item.status || previous.reason !== item.reason)) throw policyError('conflicting duplicate decisions');
+    decisions.set(address, { address, status: item.status, reason: item.reason });
+  }
+  return [...decisions.values()];
+};
+
+const evaluatePolicyPhase = async (providers, hook, context, report) => {
+  const decisions = [];
+  let retryFailure = false;
+  for (const provider of providers) {
+    if (typeof provider[hook] !== 'function') continue;
+    try {
+      const validated = validatePolicyResult(await provider[hook](context), hook, context);
+      for (const decision of validated) decisions.push({ ...decision, provider: provider.name });
+    } catch (error) {
+      report(error, provider.name, hook);
+      if (provider.failureMode !== 'continue') retryFailure = true;
+    }
+  }
+  return { retryFailure, decisions };
+};
+
+const mergePolicyResults = (previous, recipients, evaluated, details) => {
+  const results = new Map(previous.map((r) => [r.address, r]));
+  const accepted = new Set(details.accepted || []);
+  const decisions = new Map();
+  for (const decision of evaluated.decisions) {
+    if (!decisions.has(decision.address)) decisions.set(decision.address, []);
+    decisions.get(decision.address).push(decision);
+  }
+  const diagnostics = new Map();
+  for (const record of details.rejections || []) {
+    if (record.address && !diagnostics.has(record.address)) diagnostics.set(record.address, record);
+  }
+  for (const recipient of recipients) {
+    const prior = results.get(recipient.address);
+    if (prior && prior.status !== 'error') continue;
+    const candidates = decisions.get(recipient.address) || [];
+    const terminal = details.phase === 'beforeSend' ? 'suppressed' : 'rejected';
+    let status = 'error';
+    if (accepted.has(recipient.address)) status = 'sent';
+    else if (!evaluated.retryFailure && candidates.some((d) => d.status === terminal)) status = terminal;
+    const reasons = [];
+    if (!evaluated.retryFailure && status !== 'sent') {
+      for (const candidate of candidates) {
+        if (candidate.status === (status === 'error' ? 'retry' : status)) reasons.push({ provider: candidate.provider, reason: candidate.reason });
+      }
+    }
+    const result = { address: recipient.address, status, sources: [...recipient.sources], reasons, attempt: details.attempt, transportIndex: details.transportIndex };
+    if (typeof details.transportName === 'string') result.transportName = details.transportName.slice(0, 128);
+    const record = diagnostics.get(recipient.address);
+    if (record) {
+      for (const key of ['command', 'response', 'message']) {
+        if (typeof record[key] === 'string') result[key] = record[key].slice(0, 2048);
+      }
+      if (Number.isFinite(record.responseCode)) result.responseCode = record.responseCode;
+    }
+    results.set(recipient.address, result);
+  }
+  return [...results.values()];
+};
+
+const summarizePolicyTask = (task, isSettled) => {
+  const recipients = { sent: [], error: [], suppressed: [], rejected: [] };
+  for (const result of task.recipientResults || []) recipients[result.status].push(result);
+  return { uuid: task.uuid, tries: task.tries, isSettled, recipients };
+};
+
+const diagnosticFields = (record) => {
+  const result = {};
+  for (const key of ['command', 'response', 'message']) {
+    if (typeof record?.[key] === 'string') result[key] = record[key].slice(0, 2048);
+  }
+  if (Number.isFinite(record?.responseCode)) result.responseCode = record.responseCode;
+  return result;
+};
+
+const normalizeRejections = (error, info, transport) => {
+  const records = [];
+  const ancestors = new WeakSet();
+  const addressOf = (value) => {
+    try { return normalizePolicyAddress(value); }
+    catch { return null; }
+  };
+  const append = (node, address) => {
+    const record = { address, ...diagnosticFields(node), transportIndex: transport.index };
+    if (typeof transport.name === 'string') record.transportName = transport.name.slice(0, 128);
+    if (typeof node === 'string') record.message = node.slice(0, 2048);
+    records.push(record);
+  };
+  const visit = (node, positional = null, root = false, errorRoot = false) => {
+    if (node === null || node === void 0) {
+      if (!root) append(node, positional);
+      return;
+    }
+    if (typeof node !== 'object') {
+      append(node, positional);
+      return;
+    }
+    if (ancestors.has(node)) return;
+    ancestors.add(node);
+    const start = records.length;
+    const rejected = Array.isArray(node.rejected) ? node.rejected.map(addressOf) : [];
+    for (const key of ['errors', 'rejectedErrors']) {
+      if (Array.isArray(node[key])) {
+        for (let i = 0; i < node[key].length; i++) visit(node[key][i], rejected[i] || null);
+      }
+    }
+    if (records.length === start) {
+      let address = positional;
+      for (const key of ['recipient', 'address', 'to']) {
+        if (hasOwnProp(node, key)) { address = addressOf(node[key]); break; }
+      }
+      if (!root || errorRoot || address || Object.keys(diagnosticFields(node)).length) append(node, address);
+    }
+    const attributed = new Set(records.slice(start).map((r) => r.address));
+    for (const address of rejected) {
+      if (address && !attributed.has(address)) append({ message: 'Recipient rejected by transport' }, address);
+    }
+    ancestors.delete(node);
+  };
+  visit(error, null, true, true);
+  visit(info, null, true);
+  return records;
+};
+
+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;
+  }
+}
+
 const noop = () => {};
 const queueMethods = ['ping', 'iterate', 'getPendingTo', 'push', 'remove', 'update', 'cancel'];
 
@@ -2191,11 +2946,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
  */
 
 /**
@@ -2203,7 +2979,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
  */
 
 /**
@@ -2211,7 +2987,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
  */
 
 /**
@@ -2223,10 +2999,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
@@ -2241,6 +3023,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--) {
@@ -2280,6 +3063,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';
@@ -2492,8 +3277,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) {
@@ -2501,14 +3286,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`
@@ -2629,7 +3429,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');
     }
 
@@ -2789,6 +3590,7 @@ class MailTime {
       uuid: crypto.randomUUID(),
       tries: 0,
       isSent: false,
+      isSettled: false,
       sendAt: opts.sendAt,
       isFailed: false,
       isSending: false,
@@ -2922,7 +3724,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);
@@ -3135,7 +3937,7 @@ class MailTime {
     };
 
     const renew = async () => {
-      if (stopped || this.__isDestroyed || this.__abortInFlight) {
+      if (stopped || this.__abortInFlight) {
         halt();
         return;
       }
@@ -3188,6 +3990,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
@@ -3231,6 +4231,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) {