mail-time 4.1.0 → 5.1.0

package/index.cjs

@@ -225,6 +225,24 @@ const filterAddressField = (field, acceptedSet) => {
   return field;
 };
 
+const HTML_ESCAPES = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+/**
+ * @name escapeHtml - Escape the five HTML-significant characters.
+ * @function
+ * @param {string} value
+ * @returns {string} `value` safe to interpolate into HTML text or an attribute value.
+ */
+const escapeHtml = (value) => {
+  return `${value}`.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]);
+};
+
 /**
  * @name isSendClaimUpdate - Detect an atomic send-claim update (`{ isSending: true, tries: N }`).
  * @function
@@ -711,7 +729,11 @@ class MongoQueue {
  * @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 {(options: object) => AsyncIterable<string|string[]>} [scanIterator]
+ * @property {(key: string, field: string) => Promise<string|null>} [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]
@@ -721,10 +743,168 @@ 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 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 tonumber(task.tries or 0) >= maxTries 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, task)
+        end
+      elseif tonumber(task.sendAt or 0) <= now then
+        table.insert(tasks, task)
+      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 mode == 'claim' then
+    if task.isSent or task.isFailed or task.isCancelled 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.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
+
+  for key, value in pairs(update) do
+    task[key] = value
+  end
+  redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(task))
+
+  if task.isSent or task.isFailed or task.isCancelled 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 then
+    return 0
+  end
+  task.mailOptions = task.mailOptions or {}
+  table.insert(task.mailOptions, cjson.decode(ARGV[2]))
+  redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(task))
+  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] == 'lease' and (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 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
@@ -798,7 +978,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);
     }
@@ -806,8 +1000,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 */
@@ -822,6 +1024,49 @@ 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.__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
@@ -899,6 +1144,25 @@ 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 candidate of candidates) {
+          if (isIterateCandidate(candidate, now, sendingTimeout, maxTries)) {
+            await this.mailTimeInstance.___dispatch(candidate);
+          }
+        }
+        return;
+      }
       let dispatched = 0;
 
       const matchPattern = this.__getKey('*', 'sendat');
@@ -955,14 +1219,15 @@ 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;
     }
@@ -993,6 +1258,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);
@@ -1033,9 +1311,14 @@ class RedisQueue {
       return false;
     }
 
-    await this.client.del(this.__getKey(uuid, 'sendat'));
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+    } else {
+      await this.client.del(this.__getKey(uuid, 'sendat'));
+    }
+    const taskJSON = this.useHashTags
+      ? await this.client.hGet(this.lettersKey, uuid)
+      : await this.client.get(this.__getKey(uuid, 'letter'));
     if (!taskJSON) {
       return false;
     }
@@ -1069,6 +1352,30 @@ class RedisQueue {
       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') {
@@ -1143,6 +1450,36 @@ class RedisQueue {
     const sendingTimeout = this.mailTimeInstance?.sendingTimeout || 300000;
 
     try {
+      if (this.useHashTags) {
+        if (isAppend) {
+          const result = await this.__runScript('append', {
+            keys: [this.lettersKey],
+            arguments: [task.uuid, JSON.stringify(updateObj.appendMailOption)],
+          });
+          return Number(result) >= 1;
+        }
+
+        const mode = isClaim ? 'claim' : (isLeaseRelease ? 'lease' : 'plain');
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) {
+          keys.push(this.__getTaggedConcatKey(task.to));
+          keys.push(this.concatKeysKey);
+        }
+        const result = await this.__runScript('update', {
+          keys,
+          arguments: [
+            task.uuid,
+            JSON.stringify(stripInternalUpdateMeta(updateObj)),
+            mode,
+            `${now}`,
+            `${sendingTimeout}`,
+            `${isClaim ? task.tries : (updateObj.leaseTries || 0)}`,
+            `${updateObj.leaseSendingAt || 0}`,
+          ],
+        });
+        return Number(result) >= 1;
+      }
+
       if (isAppend) {
         if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
           if (!RedisQueue.__atomicAppendWarned) {
@@ -1254,6 +1591,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}`;
   }
 }
@@ -1855,7 +2201,7 @@ const PRESETS = Object.freeze({
     retries: 5,
     retryDelay: 2000,
     revolvingInterval: 1024,
-    sendingTimeout: 60_000,
+    sendingTimeout: 120_000,
     mode: 'batch',
     concurrency: 4,
     onError: defaultPresetOnError,
@@ -1908,7 +2254,7 @@ const PRESETS = Object.freeze({
     retries: 20,
     retryDelay: 5000,
     revolvingInterval: 1024,
-    sendingTimeout: 60_000,
+    sendingTimeout: 120_000,
     mode: 'batch',
     concurrency: 2,
     onError: defaultPresetOnError,
@@ -1975,6 +2321,51 @@ const mailTimePreset = (name, overrides) => {
 const noop = () => {};
 const queueMethods = ['ping', 'iterate', 'getPendingTo', 'push', 'remove', 'update', 'cancel'];
 
+const callHook = (name, callback, ...args) => {
+  try {
+    const result = callback(...args);
+    if (result && typeof result.then === 'function') {
+      Promise.resolve(result).catch((hookError) => {
+        logError(`[${name}] callback failed`, hookError);
+      });
+    }
+  } catch (hookError) {
+    logError(`[${name}] callback failed`, hookError);
+  }
+};
+
+/**
+ * Floor below which `sendingTimeout` is likely shorter than a real SMTP roundtrip
+ * (connect + greeting + STARTTLS + envelope + DATA, times MX rollover). A claim that
+ * expires mid-send is re-claimed by a peer, which delivers the same letter twice.
+ */
+const MIN_SAFE_SENDING_TIMEOUT = 120000;
+const DEFAULT_MAX_RENEWALS = 10;
+
+/**
+ * Fields a queued task may set under `{strictPayload: true}`. Everything else —
+ * `attachments`, `envelope`, `dkim`, `raw`, `icalEvent`, … — is dropped, because a
+ * process with queue-write access would otherwise inherit nodemailer's whole
+ * capability surface (local file read, URL fetch, sender/DKIM override).
+ */
+const STRICT_MAIL_FIELDS = [
+  'to',
+  'cc',
+  'bcc',
+  'replyTo',
+  'subject',
+  'text',
+  'html',
+  'headers',
+  'list',
+  'priority',
+  'encoding',
+  'textEncoding',
+  'inReplyTo',
+  'references',
+  'date',
+];
+
 const __withLease = (task, updateObj) => {
   if (task?.isSending === true && typeof task.tries === 'number' && typeof task.sendingAt === 'number') {
     return { ...updateObj, leaseTries: task.tries, leaseSendingAt: task.sendingAt };
@@ -2093,7 +2484,7 @@ const buildRejectionErrorMap = (info) => {
   return map;
 };
 
-let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml><meta content="text/html; charset=utf-8"http-equiv=Content-Type><meta content="width=device-width,initial-scale=1"name=viewport><title>{{subject}}</title><style>body{-webkit-font-smoothing:antialiased;-webkit-text-size-adjust:none;font-family:Tiempos,Georgia,Times,serif;font-weight:400;width:100%;height:100%;background:#fff;font-size:15px;color:#000;line-height:1.5}a{text-decoration:underline;border:0;color:#000;outline:0;color:inherit}a:hover{text-decoration:none}a[href^=sms],a[href^=tel]{text-decoration:none;color:#000;cursor:default}a img{border:none;text-decoration:none}td{font-family:Tiempos,Georgia,Times,serif;font-weight:400}hr{height:1px;border:none;width:100%;margin:0;margin-top:25px;margin-bottom:25px;background-color:#ECECEC}h1,h2,h3,h4,h5,h6{font-family:HelveticaNeue,"Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300;line-height:normal;margin-top:35px;margin-bottom:4px;margin-left:0;margin-right:0}h1{margin:23px 15px;font-size:25px}h2{margin-top:15px;font-size:21px}h3{font-weight:400;font-size:19px;border-bottom:1px solid #ECECEC}h4{font-weight:400;font-size:18px}h5{font-weight:400;font-size:17px}h6{font-weight:600;font-size:16px}h1 a,h2 a,h3 a,h4 a,h5 a,h6 a{text-decoration:none}pre{font-family:Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,sans-serif;display:block;font-size:13px;padding:9.5px;margin:0 0 10px;line-height:1.42;color:#333;word-break:break-all;word-wrap:break-word;background-color:#f5f5f5;border:1px solid #ccc;border-radius:4px;text-align:left!important;max-width:100%;white-space:pre-wrap;width:auto;overflow:auto}code{font-size:13px;font-family:font-family: Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,sans-serif;border:1px solid rgba(0,0,0,.223);border-radius:2px;padding:1px 2px;word-break:break-all;word-wrap:break-word}pre code{padding:0;font-size:inherit;color:inherit;white-space:pre-wrap;background-color:transparent;border:none;border-radius:0;word-break:break-all;word-wrap:break-word}td{text-align:center}table{border-collapse:collapse!important}.force-full-width{width:100%!important}</style><style media=screen>@media screen{h1,h2,h3,h4,h5,h6{font-family:\'Helvetica Neue\',Arial,sans-serif!important}td{font-family:Tiempos,Georgia,Times,serif!important}code,pre{font-family:Consolas,Menlo,Monaco,\'Lucida Console\',\'Liberation Mono\',\'DejaVu Sans Mono\',\'Bitstream Vera Sans Mono\',\'Courier New\',monospace,sans-serif!important}}</style><style media="only screen and (max-width:480px)">@media only screen and (max-width:480px){table[class=w320]{width:100%!important}}</style><body bgcolor=#FFFFFF class=body style=padding:0;margin:0;display:block;background:#fff;-webkit-text-size-adjust:none><table cellpadding=0 cellspacing=0 width=100% align=center><tr><td align=center valign=top bgcolor=#FFFFFF width=100%><center><table cellpadding=0 cellspacing=0 width=600 style="margin:0 auto"class=w320><tr><td align=center valign=top><table cellpadding=0 cellspacing=0 width=100% style="margin:0 auto;border-bottom:1px solid #ddd"bgcolor=#ECECEC><tr><td><h1>{{{subject}}}</h1></table><table cellpadding=0 cellspacing=0 width=100% style="margin:0 auto"bgcolor=#F2F2F2><tr><td><center><table cellpadding=0 cellspacing=0 width=100% style="margin:0 auto"><tr><td align=left style="text-align:left;padding:30px 25px">{{{html}}}</table></center></table></table></center></table>';
+let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml><meta content="text/html; charset=utf-8"http-equiv=Content-Type><meta content="width=device-width,initial-scale=1"name=viewport><title>{{subject}}</title><style>body{-webkit-font-smoothing:antialiased;-webkit-text-size-adjust:none;font-family:Tiempos,Georgia,Times,serif;font-weight:400;width:100%;height:100%;background:#fff;font-size:15px;color:#000;line-height:1.5}a{text-decoration:underline;border:0;color:#000;outline:0;color:inherit}a:hover{text-decoration:none}a[href^=sms],a[href^=tel]{text-decoration:none;color:#000;cursor:default}a img{border:none;text-decoration:none}td{font-family:Tiempos,Georgia,Times,serif;font-weight:400}hr{height:1px;border:none;width:100%;margin:0;margin-top:25px;margin-bottom:25px;background-color:#ECECEC}h1,h2,h3,h4,h5,h6{font-family:HelveticaNeue,"Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300;line-height:normal;margin-top:35px;margin-bottom:4px;margin-left:0;margin-right:0}h1{margin:23px 15px;font-size:25px}h2{margin-top:15px;font-size:21px}h3{font-weight:400;font-size:19px;border-bottom:1px solid #ECECEC}h4{font-weight:400;font-size:18px}h5{font-weight:400;font-size:17px}h6{font-weight:600;font-size:16px}h1 a,h2 a,h3 a,h4 a,h5 a,h6 a{text-decoration:none}pre{font-family:Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,sans-serif;display:block;font-size:13px;padding:9.5px;margin:0 0 10px;line-height:1.42;color:#333;word-break:break-all;word-wrap:break-word;background-color:#f5f5f5;border:1px solid #ccc;border-radius:4px;text-align:left!important;max-width:100%;white-space:pre-wrap;width:auto;overflow:auto}code{font-size:13px;font-family:font-family: Consolas,Menlo,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New,monospace,sans-serif;border:1px solid rgba(0,0,0,.223);border-radius:2px;padding:1px 2px;word-break:break-all;word-wrap:break-word}pre code{padding:0;font-size:inherit;color:inherit;white-space:pre-wrap;background-color:transparent;border:none;border-radius:0;word-break:break-all;word-wrap:break-word}td{text-align:center}table{border-collapse:collapse!important}.force-full-width{width:100%!important}</style><style media=screen>@media screen{h1,h2,h3,h4,h5,h6{font-family:\'Helvetica Neue\',Arial,sans-serif!important}td{font-family:Tiempos,Georgia,Times,serif!important}code,pre{font-family:Consolas,Menlo,Monaco,\'Lucida Console\',\'Liberation Mono\',\'DejaVu Sans Mono\',\'Bitstream Vera Sans Mono\',\'Courier New\',monospace,sans-serif!important}}</style><style media="only screen and (max-width:480px)">@media only screen and (max-width:480px){table[class=w320]{width:100%!important}}</style><body bgcolor=#FFFFFF class=body style=padding:0;margin:0;display:block;background:#fff;-webkit-text-size-adjust:none><table cellpadding=0 cellspacing=0 width=100% align=center><tr><td align=center valign=top bgcolor=#FFFFFF width=100%><center><table cellpadding=0 cellspacing=0 width=600 style="margin:0 auto"class=w320><tr><td align=center valign=top><table cellpadding=0 cellspacing=0 width=100% style="margin:0 auto;border-bottom:1px solid #ddd"bgcolor=#ECECEC><tr><td><h1>{{subject}}</h1></table><table cellpadding=0 cellspacing=0 width=100% style="margin:0 auto"bgcolor=#F2F2F2><tr><td><center><table cellpadding=0 cellspacing=0 width=100% style="margin:0 auto"><tr><td align=left style="text-align:left;padding:30px 25px">{{{html}}}</table></center></table></table></center></table>';
 
 /**
  * @typedef {import('./presets.js').MailTimePresetName} MailTimePresetName
@@ -2124,7 +2515,11 @@ let DEFAULT_TEMPLATE = '<!DOCTYPE html><html xmlns=http://www.w3.org/1999/xhtml>
  */
 
 /**
- * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
+ * @typedef {{ [key: string]: any, adapter: MailTimeJoSkAdapterOptions | object, debug?: boolean, autoClear?: boolean, zombieTime?: number, lockLeaseTime?: number, minRevolvingDelay?: number, maxRevolvingDelay?: number, execute?: 'batch' | 'one', concurrency?: number, lockOwnerId?: string, resetOnInit?: boolean, onError?: (title: string, details: object) => void, onExecuted?: (uid: string, details: object) => void }} MailTimeJoSkOptions
+ */
+
+/**
+ * @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
  */
 
 /**
@@ -2152,7 +2547,11 @@ 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) => string), transports?: MailTimeTransport[], strategy?: 'backup' | 'balancer', failsToNext?: number, 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, 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 {{ index: number, from: string | undefined }} MailTimeFromDetails
+ */
+
+/**
+ * @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
  */
 
 /** Class of MailTime */
@@ -2213,7 +2612,34 @@ class MailTime {
     this.revolvingInterval = (typeof opts.revolvingInterval === 'number' && opts.revolvingInterval > 0) ? opts.revolvingInterval : 1536;
     this.mode = (opts.mode === 'one' || opts.mode === 'batch') ? opts.mode : 'batch';
     this.concurrency = (typeof opts.concurrency === 'number' && opts.concurrency > 0 && Number.isFinite(opts.concurrency)) ? Math.floor(opts.concurrency) : 1;
-    this.sendingTimeout = (typeof opts.sendingTimeout === 'number' && opts.sendingTimeout > 0) ? opts.sendingTimeout : 300000;
+    this.sendingTimeout = (typeof opts.sendingTimeout === 'number' && Number.isFinite(opts.sendingTimeout) && opts.sendingTimeout > 0) ? opts.sendingTimeout : 300000;
+    if (this.sendingTimeout < MIN_SAFE_SENDING_TIMEOUT) {
+      logError(`{sendingTimeout: ${this.sendingTimeout}} is below the ${MIN_SAFE_SENDING_TIMEOUT}ms safe floor — a claim that expires while SMTP is still in flight is re-claimed by a peer and the letter is delivered twice. Raise {sendingTimeout} above the worst-case SMTP roundtrip.`);
+    }
+
+    // Claim renewal: MailTime has no way to know how long a transport will take, so a
+    // long-but-healthy send used to lose its lock to a "recovery" worker. While a send
+    // is in flight the claim is re-stamped every {renewClaim} ms — bounded by
+    // {maxRenewals} so a genuinely wedged send is still recovered, just later.
+    if (opts.renewClaim === false || opts.renewClaim === 0) {
+      this.renewClaim = 0;
+    } else if (typeof opts.renewClaim === 'number' && Number.isFinite(opts.renewClaim) && opts.renewClaim > 0) {
+      this.renewClaim = Math.floor(opts.renewClaim);
+    } else {
+      this.renewClaim = Math.max(1000, Math.floor(this.sendingTimeout / 3));
+    }
+    this.maxRenewals = (typeof opts.maxRenewals === 'number' && Number.isFinite(opts.maxRenewals) && opts.maxRenewals >= 0) ? Math.floor(opts.maxRenewals) : DEFAULT_MAX_RENEWALS;
+
+    // Transport fail-over policy. Rotating on *any* error can resubmit a letter the
+    // MX already accepted; a transport that knows better says so.
+    this.shouldFailOver = (typeof opts.shouldFailOver === 'function') ? opts.shouldFailOver.bind(this) : null;
+
+    this.strictPayload = opts.strictPayload === true;
+    this.allowedMailFields = new Set([
+      ...STRICT_MAIL_FIELDS,
+      ...(Array.isArray(opts.allowedMailFields) ? opts.allowedMailFields.filter((field) => typeof field === 'string') : []),
+    ]);
+
     this.__isDestroyed = false;
     this.__abortInFlight = false;
     this.__isPaused = false;
@@ -2272,6 +2698,8 @@ class MailTime {
     this.__debug(`INITIALIZING [mode: ${this.mode}]`);
     this.__debug(`INITIALIZING [concurrency: ${this.concurrency}]`);
     this.__debug(`INITIALIZING [sendingTimeout: ${this.sendingTimeout}]`);
+    this.__debug(`INITIALIZING [renewClaim: ${this.renewClaim}]`);
+    this.__debug(`INITIALIZING [strictPayload: ${this.strictPayload}]`);
 
     /** SERVER-SPECIFIC CHECKS AND CONFIG */
     if (this.type === 'server') {
@@ -2336,6 +2764,7 @@ class MailTime {
         };
       }
 
+      /** @type {MailTimeScheduler | undefined} */
       this.scheduler = new josk.JoSk({
         debug: this.debug,
         ...this.josk,
@@ -2501,12 +2930,17 @@ class MailTime {
    * @returns {Promise<string>} uuid of the email
    * @throws {Error}
    */
-  async sendMail(opts = {}) {
+  async sendMail(opts) {
+    opts = (opts && typeof opts === 'object') ? opts : {};
     this.__debug('[sendMail]', opts);
     if (!opts.html && !opts.text) {
       throw new Error('[mail-time] [sendMail] `html` nor `text` field is present, at least one of those fields is required');
     }
 
+    if (opts.raw !== void 0) {
+      throw new Error('[mail-time] [sendMail] `raw` is not supported: it bypasses composition, so `template`, `concatEmails`, and the `from()` callback would silently stop applying — and nodemailer historically let a message-level `raw` bypass `disableFileAccess`/`disableUrlAccess`. Pass `html` / `text` instead.');
+    }
+
     let sendAt = opts.sendAt;
     if (sendAt instanceof Date) {
       sendAt = +sendAt;
@@ -2635,13 +3069,16 @@ class MailTime {
       task.isSending = false;
 
       this.__debug(`[private handleError] Giving up trying send email after ${task.tries} attempts to: `, task.mailOptions[0].to, error);
-      this.onError(error, task, info);
+      callHook('onError', this.onError, error, task, info);
       return;
     }
 
     let transportIndex = task.transport;
 
-    if (this.strategy === 'backup' && this.transports.length > 1 && (task.tries % this.failsToNext) === 0) {
+    if (this.strategy === 'backup'
+      && this.transports.length > 1
+      && (task.tries % this.failsToNext) === 0
+      && this.___mayFailOver(error, info, task)) {
       transportIndex = this.___nextHealthyTransport(transportIndex);
     }
 
@@ -2703,12 +3140,18 @@ class MailTime {
    * @internal
    * @memberOf MailTime
    * @name ___render
-   * @description Render Mustache-like placeholders
+   * @description Render Mustache-like placeholders. `{{{key}}}` is always verbatim.
+   * `{{key}}` is HTML-escaped in HTML contexts (`html`, `template`, `concatDelimiter`) —
+   * that is what double-brace means everywhere else, and the previous strip-tags pass was
+   * not a safety net: it needs a closing `>`, so an unterminated `<a href="…` survived
+   * into the rendered body. Text bodies and subject headers are not HTML, so `{{key}}`
+   * substitutes verbatim there.
    * @param {string} _string - Template with Mustache-like placeholders
    * @param {Record<string, any>} replacements - Blaze/Mustache-like helpers Object
+   * @param {boolean} [isHtml=true] - `false` for text/plain bodies and header values
    * @returns {string}
    */
-  ___render(_string, replacements) {
+  ___render(_string, replacements, isHtml = true) {
     let string = _string;
     const matchHTML = string.match(/\{{3}\s?([a-zA-Z0-9\-_]+)\s?\}{3}/g);
     if (matchHTML) {
@@ -2725,7 +3168,8 @@ class MailTime {
       for (let i = 0; i < matchStr.length; i++) {
         const key = matchStr[i].slice(2, -2).trim();
         if (hasOwnProp(replacements, key) && replacements[key] !== null && replacements[key] !== void 0) {
-          string = string.replace(matchStr[i], `${replacements[key]}`.replace(/<(?:.|\n)*?>/gm, ''));
+          const value = `${replacements[key]}`;
+          string = string.replace(matchStr[i], isHtml ? escapeHtml(value) : value);
         }
       }
     }
@@ -2764,7 +3208,7 @@ class MailTime {
     const isMulti = mailOptionsList.length > 1;
 
     for (let i = 0; i < mailOptionsList.length; i++) {
-      const mailOption = { ...mailOptionsList[i] };
+      const mailOption = this.___applyPayloadPolicy({ ...mailOptionsList[i] });
 
       if (mailOption.html) {
         const rendered = this.___render(mailOption.html, mailOption);
@@ -2777,7 +3221,7 @@ class MailTime {
       }
 
       if (mailOption.text) {
-        const rendered = this.___render(mailOption.text, mailOption);
+        const rendered = this.___render(mailOption.text, mailOption, false);
         if (isMulti) {
           compiledOpts.text += '\r\n' + rendered;
         } else {
@@ -2795,11 +3239,14 @@ class MailTime {
 
     if (isMulti) {
       const rawSubject = task.concatSubject || this.concatSubject || compiledOpts.subject;
-      compiledOpts.subject = this.___render(rawSubject, { count: mailOptionsList.length });
+      compiledOpts.subject = this.___render(rawSubject, { count: mailOptionsList.length }, false);
     }
 
     if (!compiledOpts.from && this.from) {
-      compiledOpts.from = this.from(transport);
+      compiledOpts.from = this.from(transport, {
+        index: this.transports.indexOf(transport),
+        from: MailTime.transportFrom(transport),
+      });
     }
 
     const acceptedSet = collectAcceptedSet(task);
@@ -2809,9 +3256,84 @@ class MailTime {
       compiledOpts.bcc = filterAddressField(compiledOpts.bcc, acceptedSet);
     }
 
+    if (this.strictPayload) {
+      compiledOpts.disableFileAccess = true;
+      compiledOpts.disableUrlAccess = true;
+    }
+
     return compiledOpts;
   }
 
+  /**
+   * @internal
+   * @memberOf MailTime
+   * @name ___applyPayloadPolicy
+   * @description Narrow one queued mail option to what a task is allowed to set. `raw` is
+   * always dropped: it bypasses composition (so `template`, `concatEmails` and the
+   * `from()` callback silently stop applying) and historically bypassed nodemailer's
+   * `disableFileAccess`/`disableUrlAccess` with it. Under `{strictPayload: true}` only
+   * `allowedMailFields` survive.
+   * @param {MailTimeMailOptions} mailOption - a single queued mail option object
+   * @returns {MailTimeMailOptions}
+   */
+  ___applyPayloadPolicy(mailOption) {
+    if (mailOption.raw !== void 0) {
+      delete mailOption.raw;
+      logError('[___compileMailOpts] dropped {raw} from a queued task — `raw` bypasses composition and is never sent by MailTime');
+    }
+
+    if (!this.strictPayload) {
+      return mailOption;
+    }
+
+    const allowed = {};
+    for (const key of Object.keys(mailOption)) {
+      if (this.allowedMailFields.has(key)) {
+        allowed[key] = mailOption[key];
+      } else {
+        this.__debug('[___applyPayloadPolicy] dropped non-allowlisted field', key);
+      }
+    }
+    return allowed;
+  }
+
+  /**
+   * @static
+   * @memberOf MailTime
+   * @name transportFrom
+   * @description Best-effort sender address for a transport. `nodemailer.createTransport()`
+   * only exposes `.options` for *plain-object* configs — for a class-instance transporter
+   * (anything with its own `.send()`) nodemailer's internal `Mail.options` is always `{}`,
+   * so `transport.options.from` silently reads `undefined`. This walks the places the
+   * address can actually live.
+   * @param {MailTimeTransport} transport
+   * @returns {string | undefined}
+   */
+  static transportFrom(transport) {
+    const candidates = [
+      transport?.options?.from,
+      transport?.transporter?.options?.from,
+      transport?._defaults?.from,
+      transport?._options?.from,
+    ];
+
+    for (const candidate of candidates) {
+      // nodemailer accepts `from` as a string or as `{ name, address }`. Resolve the
+      // first candidate that yields a usable address — not the first truthy slot, so a
+      // malformed `{ name }` object cannot mask a real address further down the chain.
+      const address = (typeof candidate === 'string')
+        ? candidate
+        : (candidate && typeof candidate === 'object' && typeof candidate.address === 'string')
+          ? candidate.address
+          : '';
+      if (address.trim()) {
+        return address;
+      }
+    }
+
+    return void 0;
+  }
+
   /**
    * @internal
    * @memberOf MailTime
@@ -2876,6 +3398,124 @@ class MailTime {
     }
   }
 
+  /**
+   * @internal
+   * @memberOf MailTime
+   * @name ___mayFailOver
+   * @description Whether this failure may be retried on the *next* transport. Rotating on
+   * any error can resubmit a letter the receiving MTA already accepted (or may have
+   * accepted — a socket that died during `DATA` is indistinguishable from one that died
+   * before it). A transport signals "do not fail over" with `error.mayFailOver = false`;
+   * the `shouldFailOver(error, info, task)` option overrides both.
+   * @param {unknown} error - error returned by the transport
+   * @param {object|undefined} info - info object returned by the transport
+   * @param {MailTimeTask} task - email's task object from Storage
+   * @returns {boolean}
+   */
+  ___mayFailOver(error, info, task) {
+    if (this.shouldFailOver) {
+      try {
+        return this.shouldFailOver(error, info, task) !== false;
+      } catch (policyError) {
+        logError('[shouldFailOver] callback failed; keeping the current transport', policyError);
+        return false;
+      }
+    }
+    return !(error && typeof error === 'object' && error.mayFailOver === false);
+  }
+
+  /**
+   * @internal
+   * @memberOf MailTime
+   * @name ___startClaimRenewal
+   * @description Hold a claim alive while its SMTP roundtrip runs. MailTime 4.x stamped
+   * `sendingAt` once at claim time, so any send slower than `sendingTimeout` lost its lock
+   * to a "recovery" worker and the letter went out twice. The renewal is a lease-guarded
+   * update — it succeeds only while *this* worker still owns the row — and is bounded by
+   * `maxRenewals` so a genuinely wedged send is still recovered.
+   * @param {MailTimeTask} task - claimed task, with `isSending`/`sendingAt`/`tries` set
+   * @returns {{ stop: () => Promise<void> }}
+   */
+  ___startClaimRenewal(task) {
+    if (!this.renewClaim || !this.maxRenewals || this.type !== 'server') {
+      return { stop: async () => {} };
+    }
+
+    let stopped = false;
+    let renewals = 0;
+    let timer = null;
+    let activeRenewal = null;
+    const halt = () => {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    };
+    const stop = async () => {
+      halt();
+      if (activeRenewal) {
+        await activeRenewal;
+      }
+    };
+
+    const renew = async () => {
+      if (stopped || this.__isDestroyed || this.__abortInFlight) {
+        halt();
+        return;
+      }
+
+      if (renewals >= this.maxRenewals) {
+        this.__debug('[private renewClaim] renewal budget exhausted; letting the claim go stale', task.uuid);
+        halt();
+        return;
+      }
+      renewals += 1;
+
+      // Strictly greater than the current stamp: storages that report "modified" only on
+      // an actual value change would otherwise read a same-millisecond renewal as a no-op.
+      const renewedAt = Math.max(Date.now(), (typeof task.sendingAt === 'number' ? task.sendingAt : 0) + 1);
+      let renewed = false;
+      try {
+        renewed = await this.queue.update(task, __withLease(task, {
+          isSending: true,
+          sendingAt: renewedAt,
+        }));
+      } catch (renewError) {
+        logError('[private renewClaim] storage error during claim renewal', renewError);
+        halt();
+        return;
+      }
+
+      if (!renewed) {
+        this.__debug('[private renewClaim] lease lost; stopping renewal', task.uuid);
+        halt();
+        return;
+      }
+
+      task.sendingAt = renewedAt;
+      this.__debug(`[private renewClaim] renewed ${renewals}/${this.maxRenewals}`, task.uuid);
+    };
+
+    timer = setInterval(() => {
+      if (activeRenewal) {
+        return;
+      }
+      activeRenewal = renew().finally(() => {
+        activeRenewal = null;
+      });
+    }, this.renewClaim);
+
+    if (typeof timer.unref === 'function') {
+      timer.unref();
+    }
+
+    return { stop };
+  }
+
   /**
    * @async
    * @internal
@@ -2956,131 +3596,142 @@ class MailTime {
       const transport = this.transports[transportIndex];
 
       const compiledOpts = this.___compileMailOpts(transport, task);
+      const renewal = this.___startClaimRenewal(task);
 
-      await new Promise((resolve) => {
-        transport.sendMail(compiledOpts, async (error, info) => {
-          if (this.__abortInFlight) {
-            this.__debug('[private send] instance destroyed mid-send; leaving claim for stale-lock recovery', task.uuid);
-            resolve();
-            return;
-          }
-          this.__debug('[private send] [sending]', { error, info });
-          try {
-            if (error) {
-              await this.___handleError(task, error, info);
+      try {
+        await new Promise((resolve) => {
+          transport.sendMail(compiledOpts, async (error, info) => {
+            // The roundtrip has settled — stop extending the lease before any completion
+            // write, so the guard below sees the last `sendingAt` this worker persisted.
+            await renewal.stop();
+            if (this.__abortInFlight) {
+              this.__debug('[private send] instance destroyed mid-send; leaving claim for stale-lock recovery', task.uuid);
+              resolve();
               return;
             }
+            this.__debug('[private send] [sending]', { error, info });
+            try {
+              if (error) {
+                await this.___handleError(task, error, info);
+                return;
+              }
 
-            const acceptedAddrs = Array.isArray(info?.accepted)
-              ? info.accepted.map(extractEmail).filter((addr) => typeof addr === 'string')
-              : [];
+              const acceptedAddrs = Array.isArray(info?.accepted)
+                ? info.accepted.map(extractEmail).filter((addr) => typeof addr === 'string')
+                : [];
 
-            if (acceptedAddrs.length === 0) {
-              await this.___handleError(task, new Error('Message not accepted or Greeting never received'), info);
-              return;
-            }
+              if (acceptedAddrs.length === 0) {
+                await this.___handleError(task, new Error('Message not accepted or Greeting never received'), info);
+                return;
+              }
 
-            this.___trackAcceptedRecipients(task, acceptedAddrs);
+              this.___trackAcceptedRecipients(task, acceptedAddrs);
 
-            const allRecipients = collectAllRecipients(task);
-            const allAccepted = collectAcceptedSet(task);
-            let isFullyDelivered = true;
-            for (const addr of allRecipients) {
-              if (!allAccepted.has(addr)) {
-                isFullyDelivered = false;
-                break;
+              const allRecipients = collectAllRecipients(task);
+              const allAccepted = collectAcceptedSet(task);
+              let isFullyDelivered = true;
+              for (const addr of allRecipients) {
+                if (!allAccepted.has(addr)) {
+                  isFullyDelivered = false;
+                  break;
+                }
               }
-            }
-
-            if (isFullyDelivered) {
-              this.__debug(`email successfully sent, attempts: #${task.tries}, transport #${transportIndex} to: `, compiledOpts.to);
 
-              const leaseRemove = __leaseRemoveOpts(task);
-              const leaseUpdate = __withLease(task, {
-                isSent: true,
-                isSending: false,
-                sendingAt: 0,
-                mailOptions: task.mailOptions,
-              });
+              if (isFullyDelivered) {
+                this.__debug(`email successfully sent, attempts: #${task.tries}, transport #${transportIndex} to: `, compiledOpts.to);
+
+                const leaseRemove = __leaseRemoveOpts(task);
+                const leaseUpdate = __withLease(task, {
+                  isSent: true,
+                  isSending: false,
+                  sendingAt: 0,
+                  mailOptions: task.mailOptions,
+                });
+
+                let completed = false;
+                if (!this.keepHistory) {
+                  completed = await this.queue.remove(task, leaseRemove);
+                } else {
+                  completed = await this.queue.update(task, leaseUpdate);
+                }
 
-              let completed = false;
-              if (!this.keepHistory) {
-                completed = await this.queue.remove(task, leaseRemove);
-              } else {
-                completed = await this.queue.update(task, leaseUpdate);
-              }
+                if (!completed) {
+                  this.__debug('[private send] lease lost before success completion, skipping onSent', task.uuid);
+                  return;
+                }
 
-              if (!completed) {
-                this.__debug('[private send] lease lost before success completion, skipping onSent', task.uuid);
+                // Persist first, then mirror to in-memory task — a superseded worker must not lie to onSent.
+                task.isSent = true;
+                task.isSending = false;
+                task.sendingAt = 0;
+                callHook('onSent', this.onSent, task, info);
                 return;
               }
 
-              // Persist first, then mirror to in-memory task — a superseded worker must not lie to onSent.
-              task.isSent = true;
-              task.isSending = false;
-              task.sendingAt = 0;
-              this.onSent(task, info);
-              return;
-            }
-
-            if (task.tries >= this.maxTries) {
-              this.___finalizeRejected(task, info);
+              if (task.tries >= this.maxTries) {
+                this.___finalizeRejected(task, info);
+
+                const leaseRemove = __leaseRemoveOpts(task);
+                const leaseUpdate = __withLease(task, {
+                  isSent: false,
+                  isFailed: true,
+                  isSending: false,
+                  sendingAt: 0,
+                  mailOptions: task.mailOptions,
+                });
+
+                let finalized = false;
+                if (!this.keepHistory) {
+                  finalized = await this.queue.remove(task, leaseRemove);
+                } else {
+                  finalized = await this.queue.update(task, leaseUpdate);
+                }
 
-              const leaseRemove = __leaseRemoveOpts(task);
-              const leaseUpdate = __withLease(task, {
-                isSent: false,
-                isFailed: true,
-                isSending: false,
-                sendingAt: 0,
-                mailOptions: task.mailOptions,
-              });
+                if (!finalized) {
+                  this.__debug('[private send] lease lost before partial-failure completion, skipping onError', task.uuid);
+                  return;
+                }
 
-              let finalized = false;
-              if (!this.keepHistory) {
-                finalized = await this.queue.remove(task, leaseRemove);
-              } else {
-                finalized = await this.queue.update(task, leaseUpdate);
-              }
+                // Persist first, then mirror to in-memory task — a superseded worker must not lie to onError.
+                task.isSent = false;
+                task.isFailed = true;
+                task.isSending = false;
 
-              if (!finalized) {
-                this.__debug('[private send] lease lost before partial-failure completion, skipping onError', task.uuid);
+                const rejectedAddrs = [];
+                for (const mo of task.mailOptions) {
+                  for (const r of (mo.rejected || [])) {
+                    rejectedAddrs.push(r.address);
+                  }
+                }
+                const partialError = new Error(`Recipients rejected after ${task.tries} attempts: ${rejectedAddrs.join(', ')}`);
+                this.__debug('[private send] Partial delivery exhausted retries; rejected: ', rejectedAddrs);
+                callHook('onError', this.onError, partialError, task, info);
                 return;
               }
 
-              // Persist first, then mirror to in-memory task — a superseded worker must not lie to onError.
-              task.isSent = false;
-              task.isFailed = true;
-              task.isSending = false;
-
-              const rejectedAddrs = [];
-              for (const mo of task.mailOptions) {
-                for (const r of (mo.rejected || [])) {
-                  rejectedAddrs.push(r.address);
-                }
+              const nextSendAt = Date.now() + this.retryDelay;
+              const released = await this.queue.update(task, __withLease(task, {
+                isSending: false,
+                sendingAt: 0,
+                sendAt: nextSendAt,
+                mailOptions: task.mailOptions,
+              }));
+              if (!released) {
+                this.__debug('[private send] lease lost before partial retry release', task.uuid);
+                return;
               }
-              const partialError = new Error(`Recipients rejected after ${task.tries} attempts: ${rejectedAddrs.join(', ')}`);
-              this.__debug('[private send] Partial delivery exhausted retries; rejected: ', rejectedAddrs);
-              this.onError(partialError, task, info);
-              return;
+              this.__debug(`[private send] Partial delivery, next attempt at ${new Date(nextSendAt)}: #${task.tries}/${this.maxTries} for remaining recipients`);
+            } catch (completionError) {
+              logError('[private send] completion error after transport callback', completionError);
+            } finally {
+              resolve();
             }
-
-            const nextSendAt = Date.now() + this.retryDelay;
-            const released = await this.queue.update(task, __withLease(task, {
-              isSending: false,
-              sendingAt: 0,
-              sendAt: nextSendAt,
-              mailOptions: task.mailOptions,
-            }));
-            if (!released) {
-              this.__debug('[private send] lease lost before partial retry release', task.uuid);
-              return;
-            }
-            this.__debug(`[private send] Partial delivery, next attempt at ${new Date(nextSendAt)}: #${task.tries}/${this.maxTries} for remaining recipients`);
-          } finally {
-            resolve();
-          }
+          });
         });
-      });
+      } finally {
+        // A transport that throws synchronously never reaches the callback above.
+        await renewal.stop();
+      }
     } catch (e) {
       if (this.__abortInFlight) {
         this.__debug('[private send] instance destroyed mid-send; suppressing runtime exception', e);
@@ -3167,7 +3818,7 @@ class MailTime {
       }
       this.__unhealthyTransports.add(r.index);
       logError(`[mail-time] [verifyTransports] transport #${r.index} failed verification`, r.error);
-      this.onError(r.error, null, { transportIndex: r.index, phase: 'verify' });
+      callHook('onError', this.onError, r.error, null, { transportIndex: r.index, phase: 'verify' });
     }
 
     if (this.__unhealthyTransports.size === this.transports.length) {