mail-time 5.3.0 → 5.3.1

package/README.md

@@ -176,7 +176,7 @@ Three things every MailTime needs: a connected storage **client**, one or more *
 // ESM
 import { MailTime, MongoQueue, PostgresQueue, RedisQueue, mailTimePreset } from 'mail-time';
 
-// CommonJS
+// CommonJS (subpaths such as require('mail-time/presets') resolve too, 5.3.1+)
 const { MailTime, MongoQueue, PostgresQueue, RedisQueue, mailTimePreset } = require('mail-time');
 ```
 
@@ -374,13 +374,13 @@ Defaults fit moderate traffic in a single region. Reach for a [preset](#settings
 | `mode`                                         | `'batch'`        | `'one'` to claim a single row per tick (fairness over throughput across cluster nodes)                                             |
 | `concurrency`                                  | `1`              | Raise to send N emails in parallel per instance. CAS blocks concurrent claims; SMTP rate limits still apply.                     |
 | `sendingTimeout`                               | `300000` (5 min) | Stale-lock recovery window. Must exceed worst-case SMTP roundtrip; MailTime logs a warning below `120000`. |
-| `renewClaim`                                   | `sendingTimeout / 3` | Set `false` to go back to a single stamp at claim time. Lower it if your storage round-trip is slow relative to `sendingTimeout`. |
+| `renewClaim`                                   | `sendingTimeout / 3` (min 1000 ms) | Set `false` to go back to a single stamp at claim time. Lower it if your storage round-trip is slow relative to `sendingTimeout`. |
 | `maxRenewals`                                  | `10`             | Renewal-attempt ceiling. Recovery begins `sendingTimeout` after last successful stamp; with responsive storage this is roughly `sendingTimeout + maxRenewals × renewClaim`. |
 | `shouldFailOver`                               | —                | Set when your transport can tell "never delivered" from "may have been delivered" — see [Transport fail-over](#transport-fail-over). |
 | `strictPayload`                                | `false`          | Turn on when anything other than your own app can write to the queue storage. |
 | `revolvingInterval`                            | `1536` ms        | Lower → faster pickup; higher → less scheduler I/O                                                                                 |
 | `josk.minRevolvingDelay` / `maxRevolvingDelay` | `512` / `2048`   | Lower both → snappier polls, more storage load                                                                                     |
-| `josk.zombieTime`                              | `60000`          | **Never below 60s.** After an unclean stop during a claimed scan, JoSk 6.4 preserves the claim until `zombieTime`; use graceful destroy on redeploy. |
+| `josk.zombieTime`                              | `60000`          | **Never below 60s.** After an unclean stop during a claimed scan, JoSk 6.4+ preserves the claim until `zombieTime`; use graceful destroy on redeploy. |
 | `josk.concurrency`                             | `Infinity`       | Set `1` if scheduler ticks overlap while `iterate` still runs                                                                      |
 | `josk.execute`                                 | `'batch'`        | Usually leave default; MailTime only registers one JoSk task per instance                                                          |
 | `josk.lockOwnerId`                             | random           | Set in production for observability                                                                                                |
@@ -514,19 +514,19 @@ await mailQueue.sendMail({
 | `mode`                        | `'one' \| 'batch'`                                  | `'batch'`                  | `'batch'` claims every due row per tick; `'one'` claims a single row per tick.                                                                                                              |
 | `concurrency`                 | `number`                                            | `1`                        | Parallel SMTPs per instance. CAS blocks concurrent claims for one row.                                                                                                                      |
 | `sendingTimeout`              | `number` (ms)                                       | `300000`                   | Window after which a stuck `isSending=true` row becomes eligible again. Must exceed worst-case SMTP roundtrip; values below `120000` log a warning.                                          |
-| `renewClaim`                  | `boolean \| number` (ms)                            | `sendingTimeout / 3`       | Re-stamp `sendingAt` on the claimed row while its SMTP roundtrip runs, so a slow-but-healthy send never loses its lock to a recovery worker. `false` restores the v4 single-stamp behaviour. |
+| `renewClaim`                  | `boolean \| number` (ms)                            | `sendingTimeout / 3` (min 1000 ms) | Re-stamp `sendingAt` on the claimed row while its SMTP roundtrip runs, so a slow-but-healthy send never loses its lock to a recovery worker. `false` restores the v4 single-stamp behaviour. |
 | `maxRenewals`                 | `number`                                            | `10`                       | Renewal-attempt budget per send. Recovery begins `sendingTimeout` after last successful stamp; slow renewal writes can extend elapsed time beyond the nominal interval calculation.          |
 | `shouldFailOver`              | `(error, info, email) => boolean`                   | —                          | Veto rotating to the next transport for this failure. Default: rotate unless the error carries `mayFailOver === false`. See [Transport fail-over](#transport-fail-over).                     |
 | `strictPayload`               | `boolean`                                           | `false`                    | Narrow every queued letter to `allowedMailFields` and force nodemailer's `disableFileAccess` / `disableUrlAccess`. See [Queue payload trust](#queue-payload-trust).                          |
 | `allowedMailFields`           | `string[]`                                          | —                          | Extra field names permitted under `strictPayload` (added to the built-in allowlist).                                                                                                        |
-| `verifyTransports`            | `boolean`                                           | `true`                     | Probe each transport via `transport.verify()` once at `ready()`. Failing transports are quarantined (skipped during rotation/fallback) and surfaced through `onError(error, null, { transportIndex, phase: 'verify' })`. Throws from `ready()` if **every** transport fails. Transports without a `verify()` method are treated as healthy. MailTime always calls `verify(callback)` with a `(error, success) => void` callback. The first of the callback, a returned thenable, a synchronous throw, or a synchronous `true`/`false` return decides. A `false` from Nodemailer (transport without `verify`) means healthy, and a callback `success` of `false` is ignored. Any other synchronous return value is ignored. A quarantined transport is re-probed in the background once its backoff elapses (60 s, doubling to 15 min, no option). A successful probe returns it to rotation. Sends never wait for a probe. Probes are single-flight: a probe that times out stays in flight until its verdict arrives, so at most one `verify()` is outstanding per transport. No probes with `verifyTransports: false`, on `type: 'client'`, or after `destroy()`. |
-| `verifyTimeout`               | `number`                                            | `30000`                    | Milliseconds `ready()` waits for each `transport.verify()`. Positive numbers, including `Infinity`, are clamped to `2147483647`. Anything else (non-number, `0`, negative, `NaN`) uses `30000`. On timeout `ready()` stops waiting, logs one warning, and the transport keeps its health (usable if it was usable, quarantined if it was quarantined). No `onError`. A verdict that arrives later still applies: success clears a quarantine, failure quarantines the transport and calls `onError` once. A `verify()` that neither calls back nor returns a Promise delays `ready()` by this value and stays usable. |
+| `verifyTransports`            | `boolean`                                           | `true`                     | Probe each transport with `transport.verify()` at `ready()`. A failing transport is quarantined (skipped in rotation and fallback) and reported once through `onError(error, null, { transportIndex, phase: 'verify' })`; `ready()` throws only if every transport fails. Quarantined transports are re-probed in the background (60 s, doubling to 15 min) and return to rotation on success. Verdict rules, timeouts and recovery: [transport verification](https://github.com/veliovgroup/mail-time/blob/master/docs/transport-verification.md). |
+| `verifyTimeout`               | `number`                                            | `30000`                    | Milliseconds `ready()` waits per `transport.verify()`; also the budget of each background re-probe. On timeout `ready()` stops waiting and the transport keeps its current health; a late verdict still applies. Values above `2147483647` (including `Infinity`) are clamped; anything else invalid uses `30000`. |
 | `template`                    | `string`                                            | `'{{{html}}}'`             | Default envelope.                                                                                                                                                                           |
 | `prefix`                      | `string`                                            | `''`                       | Queue namespace. **Same** on every `client` and `server` for one logical queue; **different** per email class. Inherited by the queue adapter; JoSk scheduler uses `mailTimeQueue<prefix>`. |
 | `from`                        | `string \| (transport, details) => string`          | —                          | Strongly recommended for spam-passing `From:` formatting. `details` is `{ index, from }` — see [Resolving the sender](#resolving-the-sender).                                                |
 | `debug`                       | `boolean`                                           | `false`                    | Verbose logs.                                                                                                                                                                               |
 | `onSent(email, info)`         | `function`                                          | —                          | Without policies, called once the task is fully delivered. Policy mode adds grouped `recipients, summary` arguments. `email.mailOptions[i].accepted` lists every address that got through (across all attempts).                                                        |
-| `onError(error, email, details)` | `function`                                       | —                          | `details` is typed `MailTimeErrorDetails`: `{ phase?, transportIndex?, attempt? }` plus the SMTP `info` keys of a failed attempt. Without policies, called once the retry budget is exhausted with at least one un-accepted recipient. Policy mode adds grouped `recipients, summary` arguments. `email.mailOptions[i].rejected` lists each un-delivered address with its last error. Also fires once per transport that fails `verify()` at startup with `email === null` and `info = { transportIndex, phase: 'verify' }`. Also fires once when a storage write that records a send outcome throws, with `details.phase` of `'complete'` (final or retry-release write) or `'checkpoint'` (policy mode, recipient results after SMTP). |
+| `onError(error, email, details)` | `function`                                       | —                          | `details` is typed `MailTimeErrorDetails`: `{ phase?, transportIndex?, attempt? }` plus the SMTP `info` keys of a failed attempt. Without policies, called once the retry budget is exhausted with at least one un-accepted recipient. Policy mode adds grouped `recipients, summary` arguments. `email.mailOptions[i].rejected` lists each un-delivered address with its last error. Also fires once per transport that fails `verify()` at startup with `email === null` and `details = { transportIndex, phase: 'verify' }`. Also fires once when a storage write that records a send outcome throws, with `details.phase` of `'complete'` (final or retry-release write) or `'checkpoint'` (policy mode, recipient results after SMTP). |
 | `recipientPolicies` | `MailTimeRecipientPolicy[]` | — | Optional nonempty provider list. When set, `sendMail()` rejects an unparseable address (`MAIL_TIME_INVALID_ADDRESS`, `error.field` such as `to[1]`) before enqueue, and a `server` constructor throws for an unparseable string `from` or transport `from` (`transports[i].from`). See [Recipient policies](#recipient-policies). |
 | `onSuppressed(task, recipients, summary)` | `function` | — | Terminal suppressed group in policy mode. |
 | `onRejected(task, recipients, summary)` | `function` | — | Terminal permanently rejected group in policy mode. |
@@ -560,7 +560,7 @@ For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup
 - `ping()` → `Promise<{status, code, statusCode, paused?, error?}>`. Pings scheduler then queue; `paused` reflects `isPaused`.
 - `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects on storage failure with the original error in `.cause` (`Error` `cause` is ignored below Node 16.9).
 - `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Graceful shutdown waits for JoSk's scan and the SMTP pool; sends not yet started are dropped and stay queued; `schedulerTimeout` defaults to 10000 ms; a timed-out scan or failed JoSk shutdown resolves `false` (never rejects). Plain `destroy()` aborts completion writes.
-- `drain()` → `Promise<{ failedWrites }>`. Resolves once every in-flight SMTP attempt finishes. `failedWrites` counts, since instance creation, storage writes that threw while recording an outcome, plus outcome writes lost after a claim-renewal error. Such a lost write is retried once with the renewal's stamp, except when the claim was already stale at renewal time; the reported message is `outcome write lost (renewal outcome uncertain or lease taken over)`. Each is also reported through `onError` with `details.phase` (`'complete'` or `'checkpoint'`), except after a plain `destroy()`, which still counts but does not call `onError`. Such a row can stay `sending` and be re-sent after `sendingTimeout`. Read it after `destroy({ drain: true })` with `await mailQueue.drain()` to learn whether shutdown was clean. Useful in tests and graceful-shutdown paths.
+- `drain()` → `Promise<{ failedWrites }>`. Resolves once every in-flight SMTP attempt finishes. `failedWrites` counts outcome writes that failed since instance creation; each is also reported through `onError` with `details.phase` `'complete'` or `'checkpoint'`. A non-zero value after `destroy({ drain: true })` means a row may stay `sending` and be re-sent after `sendingTimeout`. Details: [completion writes and drain](https://github.com/veliovgroup/mail-time/blob/master/docs/tuning.md#completion-writes-and-drain).
 - `pause()` / `resume()` → `boolean`. Server-only reversible backpressure; no-ops on `client` or after `destroy()`. See [Shutdown](#6-shutdown).
 - `isPaused` → `boolean`. Read-only; always `false` on `client`.
 
@@ -599,6 +599,7 @@ Upgrade checklists, adapter contract changes, and rollout notes live in the docs
 | 4.0  | 4.1 | [v4.0 → v4.1](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4-v4.1.md) |
 | 4.1  | 5.0 | [v4.1 → v5](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md) |
 | 5.0  | 5.1 | [v5 → v5.1 Redis Cluster](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5-v5.1.md) |
+| 5.1  | 5.2 | [v5.1 → v5.2 recipient policies rollout](https://github.com/veliovgroup/mail-time/blob/master/docs/recipient-policies.md#recovery-and-rollout) |
 | 5.2  | 5.3 | [v5.2 → v5.3](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5.2-v5.3.md) |
 
 New in v4 (opt-in): `mailTimePreset`, `concurrency`/`mode`, `sendingTimeout`, `drain()`/`pause()`/`resume()`, per-recipient handling, AI skills bundle.

package/adapters/mongo.d.ts

@@ -1,24 +1,25 @@
 export type MongoCollection = {
     collectionName?: string | undefined;
-    createIndex: (keys: object, opts?: object) => Promise<unknown>;
+    createIndex: (keys: any, opts?: any) => Promise<unknown>;
     indexes: () => Promise<{
-        name: string;
+        name?: string;
         key: Record<string, unknown>;
     }[]>;
     dropIndex: (name: string) => Promise<unknown>;
-    find: (query: object, opts?: object) => unknown;
-    findOne: (query: object, opts?: object) => Promise<object | null>;
-    insertOne: (doc: object) => Promise<unknown>;
-    deleteOne: (query: object) => Promise<{
+    find: (query: any, opts?: any) => unknown;
+    findOne: (query: any, opts?: any) => Promise<object | null>;
+    insertOne: (doc: any) => Promise<unknown>;
+    deleteOne: (query: any) => Promise<{
         deletedCount?: number;
     }>;
-    updateOne: (query: object, update: object) => Promise<{
+    updateOne: (query: any, update: any) => Promise<{
         modifiedCount?: number;
+        matchedCount?: number;
     }>;
 };
 export type Db = {
     collection: (name: string) => MongoCollection;
-    command: (cmd: object) => Promise<{
+    command: (cmd: any) => Promise<{
         ok?: number;
     }>;
 };

package/adapters/mongo.js

@@ -14,20 +14,20 @@ const DEFAULT_PREFIX = '';
 /**
  * @typedef {object} MongoCollection
  * @property {string} [collectionName]
- * @property {(keys: object, opts?: object) => Promise<unknown>} createIndex
- * @property {() => Promise<{ name: string, key: Record<string, unknown> }[]>} indexes
+ * @property {(keys: any, opts?: any) => Promise<unknown>} createIndex
+ * @property {() => Promise<{ name?: string, key: Record<string, unknown> }[]>} indexes
  * @property {(name: string) => Promise<unknown>} dropIndex
- * @property {(query: object, opts?: object) => unknown} find
- * @property {(query: object, opts?: object) => Promise<object|null>} findOne
- * @property {(doc: object) => Promise<unknown>} insertOne
- * @property {(query: object) => Promise<{ deletedCount?: number }>} deleteOne
- * @property {(query: object, update: object) => Promise<{ modifiedCount?: number }>} updateOne
+ * @property {(query: any, opts?: any) => unknown} find
+ * @property {(query: any, opts?: any) => Promise<object|null>} findOne
+ * @property {(doc: any) => Promise<unknown>} insertOne
+ * @property {(query: any) => Promise<{ deletedCount?: number }>} deleteOne
+ * @property {(query: any, update: any) => Promise<{ modifiedCount?: number, matchedCount?: number }>} updateOne
  */
 
 /**
  * @typedef {object} Db
  * @property {(name: string) => MongoCollection} collection
- * @property {(cmd: object) => Promise<{ ok?: number }>} command
+ * @property {(cmd: any) => Promise<{ ok?: number }>} command
  */
 
 /**

package/adapters/postgres.d.ts

@@ -4,6 +4,11 @@ export type PostgresQueryResult = {
 };
 export type PostgresClient = {
     query: (queryText: string, values?: unknown[]) => Promise<PostgresQueryResult>;
+    /**
+     * - a client whose constructor name ends in `Pool` or that has a numeric `totalCount` (`pg.Pool`) is treated as a pool; setup checks out one connection
+     */
+    connect?: ((...args: any[]) => any) | undefined;
+    totalCount?: number | undefined;
 };
 export type PostgresQueueOption = {
     client: PostgresClient;

package/adapters/postgres.js

@@ -19,6 +19,8 @@ import {
 /**
  * @typedef {object} PostgresClient
  * @property {(queryText: string, values?: unknown[]) => Promise<PostgresQueryResult>} query
+ * @property {(...args: any[]) => any} [connect] - a client whose constructor name ends in `Pool` or that has a numeric `totalCount` (`pg.Pool`) is treated as a pool; setup checks out one connection
+ * @property {number} [totalCount]
  */
 
 /**
@@ -119,8 +121,18 @@ class PostgresQueue {
   /** @internal */
   __applyPrefix(prefix) {
     this.prefix = prefix;
-    this.__readyPromise = this.__setup();
-    this.__readyPromise.catch(() => void 0);
+    this.__startSetup();
+  }
+
+  /** @internal */
+  __startSetup() {
+    const setup = this.__setup();
+    this.__readyPromise = setup;
+    // A failed setup (database still booting) must not poison every later call; the next
+    // ready() retries it. The awaiting caller still sees this attempt's rejection.
+    setup.catch(() => {
+      if (this.__readyPromise === setup) this.__readyPromise = null;
+    });
   }
 
   /** @internal */
@@ -145,16 +157,25 @@ class PostgresQueue {
   async ready() {
     this.__ensurePrefix();
     this.__debug('[ready]');
+    if (!this.__readyPromise) this.__startSetup();
     await this.__readyPromise;
   }
 
   /** @internal */
   async __setup() {
     const advisoryLockKey = advisoryLockKeyFor(this.prefix);
-    await this.client.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+    // `pg_advisory_lock` is session-scoped. Through a `pg.Pool` each `query()` may use a
+    // different connection, so lock, DDL and unlock must share one checked-out client;
+    // otherwise the lock stays on an idle pooled connection and blocks peer startups.
+    const pooled = typeof this.client.connect === 'function'
+      && (typeof this.client.totalCount === 'number' || /Pool$/.test(this.client.constructor?.name || ''));
+    const conn = pooled ? await this.client.connect() : this.client;
+    let locked = false;
 
     try {
-      await this.client.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
+      await conn.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      locked = true;
+      await conn.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
           id BIGSERIAL PRIMARY KEY,
           prefix TEXT NOT NULL DEFAULT 'default',
           uuid TEXT NOT NULL,
@@ -175,18 +196,22 @@ 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
+      await conn.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS is_settled BOOLEAN NOT NULL DEFAULT false');
+      await conn.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS recipient_results JSONB');
+      await conn.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_policy_due_v1
+      await conn.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_policy_pending_to_v1
+      await conn.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]);
+      try {
+        if (locked) await conn.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      } finally {
+        if (pooled) conn.release();
+      }
     }
   }
 

package/adapters/redis.d.ts

@@ -6,7 +6,7 @@ export type RedisClient = {
     ping?: (() => Promise<string>) | undefined;
     getRandomNode?: (() => unknown) | undefined;
     nodeClient?: ((...args: any[]) => any) | undefined;
-    sendCommand?: ((firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>) | undefined;
+    sendCommand?: ((...args: any[]) => Promise<unknown>) | undefined;
     scanIterator?: ((options: object) => AsyncIterable<string | string[]>) | undefined;
     hGet?: ((key: string, field: string) => Promise<string | null | undefined>) | undefined;
     eval?: ((script: string, options: {

package/adapters/redis.js

@@ -19,7 +19,7 @@ import { createHash } from 'crypto';
  * @property {() => Promise<string>} [ping]
  * @property {() => unknown} [getRandomNode]
  * @property {(...args: any[]) => any} [nodeClient]
- * @property {(firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>} [sendCommand]
+ * @property {(...args: any[]) => 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]
@@ -218,6 +218,12 @@ const isNoScriptError = (error) => {
   return !!error && (error.code === 'NOSCRIPT' || (typeof error.message === 'string' && error.message.includes('NOSCRIPT')));
 };
 
+// node-redis 4/5 throw `WatchError` from `exec()` when a watched key changed; that is the
+// expected outcome of a lost CAS race, not a storage failure.
+const isWatchError = (error) => {
+  return !!error && (error.name === 'WatchError' || error.constructor?.name === 'WatchError');
+};
+
 const canReleaseLease = (currentTask, updateObj) => {
   return currentTask
     && currentTask.tries === updateObj.leaseTries
@@ -611,15 +617,19 @@ class RedisQueue {
     const taskJSON = JSON.stringify(task);
 
     if (typeof this.client.multi === 'function') {
-      const multi = this.client.multi();
-      multi.set(letterKey, taskJSON);
-      multi.set(sendatKey, `${task.sendAt}`);
-      if (task.to) {
-        multi.set(this.__getKey(task.to, 'concatletter'), task.uuid, {
-          PXAT: task.sendAt - 128,
-        });
-      }
-      await multi.exec();
+      // EXEC discards every WATCH on the connection, so an unserialized push would turn a
+      // concurrent claim's guarded MULTI into an unconditional write (duplicate send).
+      await this.__serialize(async () => {
+        const multi = this.client.multi();
+        multi.set(letterKey, taskJSON);
+        multi.set(sendatKey, `${task.sendAt}`);
+        if (task.to) {
+          multi.set(this.__getKey(task.to, 'concatletter'), task.uuid, {
+            PXAT: task.sendAt - 128,
+          });
+        }
+        await multi.exec();
+      });
       return;
     }
 
@@ -656,7 +666,7 @@ class RedisQueue {
   }
 
   /** @internal */
-  async __cancel(uuid) {
+  async __cancel(uuid, attempt = 0) {
     this.__debug('[cancel]', uuid);
     if (typeof uuid !== 'string') {
       return false;
@@ -677,7 +687,10 @@ class RedisQueue {
         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;
+        const result = Number(await this.__runScript(keep ? 'update' : 'remove', { keys, arguments: args }));
+        // -1: the payload changed between hGet and the script (a claim renewal, for example); retry on a fresh snapshot
+        if (result === -1 && attempt < 2) return await this.__cancel(uuid, attempt + 1);
+        return result >= 1;
       }
       if (!atomic) {
         if (task.recipientResults != null) return false;
@@ -689,7 +702,7 @@ class RedisQueue {
       multi.del(this.__getKey(uuid, 'sendat'));
       return (await multi.exec()) !== null;
     } catch (error) {
-      logError('[cancel] storage error', error);
+      if (!isWatchError(error)) logError('[cancel] storage error', error);
       return false;
     } finally {
       if (!this.useHashTags && atomic) await this.client.unwatch?.();
@@ -746,7 +759,9 @@ class RedisQueue {
         return false;
       }
       try {
+        const concatKey = task.to ? this.__getKey(task.to, 'concatletter') : null;
         await this.client.watch(letterKey);
+        if (concatKey) await this.client.watch(concatKey);
         const taskJSON = await this.client.get(letterKey);
         if (!taskJSON) {
           await this.client.unwatch?.();
@@ -764,8 +779,9 @@ class RedisQueue {
           return false;
         }
         const keysToDelete = [letterKey, this.__getKey(task.uuid, 'sendat')];
-        if (task.to) {
-          keysToDelete.push(this.__getKey(task.to, 'concatletter'));
+        // The pointer may already name a newer letter folded for the same recipient.
+        if (concatKey && (await this.client.get(concatKey)) === task.uuid) {
+          keysToDelete.push(concatKey);
         }
         const multi = this.client.multi();
         for (const key of keysToDelete) {
@@ -774,7 +790,7 @@ class RedisQueue {
         const result = await multi.exec();
         return result !== null;
       } catch (opError) {
-        logError('[remove] [lease] [opError]', opError);
+        if (!isWatchError(opError)) logError('[remove] [lease] [opError]', opError);
         return false;
       }
     }
@@ -786,7 +802,10 @@ class RedisQueue {
 
     const keysToDelete = [letterKey, this.__getKey(task.uuid, 'sendat')];
     if (task.to) {
-      keysToDelete.push(this.__getKey(task.to, 'concatletter'));
+      const concatKey = this.__getKey(task.to, 'concatletter');
+      if ((await this.client.get(concatKey)) === task.uuid) {
+        keysToDelete.push(concatKey);
+      }
     }
     await this.client.del(keysToDelete);
     return true;
@@ -946,7 +965,7 @@ class RedisQueue {
       }
       return true;
     } catch (opError) {
-      logError('[update] [try/catch] [opError]', opError);
+      if (!isWatchError(opError)) logError('[update] [try/catch] [opError]', opError);
       return false;
     }
   }

package/index.cjs

@@ -304,20 +304,20 @@ const DEFAULT_PREFIX$2 = '';
 /**
  * @typedef {object} MongoCollection
  * @property {string} [collectionName]
- * @property {(keys: object, opts?: object) => Promise<unknown>} createIndex
- * @property {() => Promise<{ name: string, key: Record<string, unknown> }[]>} indexes
+ * @property {(keys: any, opts?: any) => Promise<unknown>} createIndex
+ * @property {() => Promise<{ name?: string, key: Record<string, unknown> }[]>} indexes
  * @property {(name: string) => Promise<unknown>} dropIndex
- * @property {(query: object, opts?: object) => unknown} find
- * @property {(query: object, opts?: object) => Promise<object|null>} findOne
- * @property {(doc: object) => Promise<unknown>} insertOne
- * @property {(query: object) => Promise<{ deletedCount?: number }>} deleteOne
- * @property {(query: object, update: object) => Promise<{ modifiedCount?: number }>} updateOne
+ * @property {(query: any, opts?: any) => unknown} find
+ * @property {(query: any, opts?: any) => Promise<object|null>} findOne
+ * @property {(doc: any) => Promise<unknown>} insertOne
+ * @property {(query: any) => Promise<{ deletedCount?: number }>} deleteOne
+ * @property {(query: any, update: any) => Promise<{ modifiedCount?: number, matchedCount?: number }>} updateOne
  */
 
 /**
  * @typedef {object} Db
  * @property {(name: string) => MongoCollection} collection
- * @property {(cmd: object) => Promise<{ ok?: number }>} command
+ * @property {(cmd: any) => Promise<{ ok?: number }>} command
  */
 
 /**
@@ -748,7 +748,7 @@ class MongoQueue {
  * @property {() => Promise<string>} [ping]
  * @property {() => unknown} [getRandomNode]
  * @property {(...args: any[]) => any} [nodeClient]
- * @property {(firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>} [sendCommand]
+ * @property {(...args: any[]) => 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]
@@ -947,6 +947,12 @@ const isNoScriptError = (error) => {
   return !!error && (error.code === 'NOSCRIPT' || (typeof error.message === 'string' && error.message.includes('NOSCRIPT')));
 };
 
+// node-redis 4/5 throw `WatchError` from `exec()` when a watched key changed; that is the
+// expected outcome of a lost CAS race, not a storage failure.
+const isWatchError = (error) => {
+  return !!error && (error.name === 'WatchError' || error.constructor?.name === 'WatchError');
+};
+
 const canReleaseLease = (currentTask, updateObj) => {
   return currentTask
     && currentTask.tries === updateObj.leaseTries
@@ -1340,15 +1346,19 @@ class RedisQueue {
     const taskJSON = JSON.stringify(task);
 
     if (typeof this.client.multi === 'function') {
-      const multi = this.client.multi();
-      multi.set(letterKey, taskJSON);
-      multi.set(sendatKey, `${task.sendAt}`);
-      if (task.to) {
-        multi.set(this.__getKey(task.to, 'concatletter'), task.uuid, {
-          PXAT: task.sendAt - 128,
-        });
-      }
-      await multi.exec();
+      // EXEC discards every WATCH on the connection, so an unserialized push would turn a
+      // concurrent claim's guarded MULTI into an unconditional write (duplicate send).
+      await this.__serialize(async () => {
+        const multi = this.client.multi();
+        multi.set(letterKey, taskJSON);
+        multi.set(sendatKey, `${task.sendAt}`);
+        if (task.to) {
+          multi.set(this.__getKey(task.to, 'concatletter'), task.uuid, {
+            PXAT: task.sendAt - 128,
+          });
+        }
+        await multi.exec();
+      });
       return;
     }
 
@@ -1385,7 +1395,7 @@ class RedisQueue {
   }
 
   /** @internal */
-  async __cancel(uuid) {
+  async __cancel(uuid, attempt = 0) {
     this.__debug('[cancel]', uuid);
     if (typeof uuid !== 'string') {
       return false;
@@ -1406,7 +1416,10 @@ class RedisQueue {
         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;
+        const result = Number(await this.__runScript(keep ? 'update' : 'remove', { keys, arguments: args }));
+        // -1: the payload changed between hGet and the script (a claim renewal, for example); retry on a fresh snapshot
+        if (result === -1 && attempt < 2) return await this.__cancel(uuid, attempt + 1);
+        return result >= 1;
       }
       if (!atomic) {
         if (task.recipientResults != null) return false;
@@ -1418,7 +1431,7 @@ class RedisQueue {
       multi.del(this.__getKey(uuid, 'sendat'));
       return (await multi.exec()) !== null;
     } catch (error) {
-      logError('[cancel] storage error', error);
+      if (!isWatchError(error)) logError('[cancel] storage error', error);
       return false;
     } finally {
       if (!this.useHashTags && atomic) await this.client.unwatch?.();
@@ -1475,7 +1488,9 @@ class RedisQueue {
         return false;
       }
       try {
+        const concatKey = task.to ? this.__getKey(task.to, 'concatletter') : null;
         await this.client.watch(letterKey);
+        if (concatKey) await this.client.watch(concatKey);
         const taskJSON = await this.client.get(letterKey);
         if (!taskJSON) {
           await this.client.unwatch?.();
@@ -1493,8 +1508,9 @@ class RedisQueue {
           return false;
         }
         const keysToDelete = [letterKey, this.__getKey(task.uuid, 'sendat')];
-        if (task.to) {
-          keysToDelete.push(this.__getKey(task.to, 'concatletter'));
+        // The pointer may already name a newer letter folded for the same recipient.
+        if (concatKey && (await this.client.get(concatKey)) === task.uuid) {
+          keysToDelete.push(concatKey);
         }
         const multi = this.client.multi();
         for (const key of keysToDelete) {
@@ -1503,7 +1519,7 @@ class RedisQueue {
         const result = await multi.exec();
         return result !== null;
       } catch (opError) {
-        logError('[remove] [lease] [opError]', opError);
+        if (!isWatchError(opError)) logError('[remove] [lease] [opError]', opError);
         return false;
       }
     }
@@ -1515,7 +1531,10 @@ class RedisQueue {
 
     const keysToDelete = [letterKey, this.__getKey(task.uuid, 'sendat')];
     if (task.to) {
-      keysToDelete.push(this.__getKey(task.to, 'concatletter'));
+      const concatKey = this.__getKey(task.to, 'concatletter');
+      if ((await this.client.get(concatKey)) === task.uuid) {
+        keysToDelete.push(concatKey);
+      }
     }
     await this.client.del(keysToDelete);
     return true;
@@ -1675,7 +1694,7 @@ class RedisQueue {
       }
       return true;
     } catch (opError) {
-      logError('[update] [try/catch] [opError]', opError);
+      if (!isWatchError(opError)) logError('[update] [try/catch] [opError]', opError);
       return false;
     }
   }
@@ -1716,6 +1735,8 @@ class RedisQueue {
 /**
  * @typedef {object} PostgresClient
  * @property {(queryText: string, values?: unknown[]) => Promise<PostgresQueryResult>} query
+ * @property {(...args: any[]) => any} [connect] - a client whose constructor name ends in `Pool` or that has a numeric `totalCount` (`pg.Pool`) is treated as a pool; setup checks out one connection
+ * @property {number} [totalCount]
  */
 
 /**
@@ -1816,8 +1837,18 @@ class PostgresQueue {
   /** @internal */
   __applyPrefix(prefix) {
     this.prefix = prefix;
-    this.__readyPromise = this.__setup();
-    this.__readyPromise.catch(() => void 0);
+    this.__startSetup();
+  }
+
+  /** @internal */
+  __startSetup() {
+    const setup = this.__setup();
+    this.__readyPromise = setup;
+    // A failed setup (database still booting) must not poison every later call; the next
+    // ready() retries it. The awaiting caller still sees this attempt's rejection.
+    setup.catch(() => {
+      if (this.__readyPromise === setup) this.__readyPromise = null;
+    });
   }
 
   /** @internal */
@@ -1842,16 +1873,25 @@ class PostgresQueue {
   async ready() {
     this.__ensurePrefix();
     this.__debug('[ready]');
+    if (!this.__readyPromise) this.__startSetup();
     await this.__readyPromise;
   }
 
   /** @internal */
   async __setup() {
     const advisoryLockKey = advisoryLockKeyFor(this.prefix);
-    await this.client.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+    // `pg_advisory_lock` is session-scoped. Through a `pg.Pool` each `query()` may use a
+    // different connection, so lock, DDL and unlock must share one checked-out client;
+    // otherwise the lock stays on an idle pooled connection and blocks peer startups.
+    const pooled = typeof this.client.connect === 'function'
+      && (typeof this.client.totalCount === 'number' || /Pool$/.test(this.client.constructor?.name || ''));
+    const conn = pooled ? await this.client.connect() : this.client;
+    let locked = false;
 
     try {
-      await this.client.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
+      await conn.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      locked = true;
+      await conn.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
           id BIGSERIAL PRIMARY KEY,
           prefix TEXT NOT NULL DEFAULT 'default',
           uuid TEXT NOT NULL,
@@ -1872,18 +1912,22 @@ 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
+      await conn.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS is_settled BOOLEAN NOT NULL DEFAULT false');
+      await conn.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS recipient_results JSONB');
+      await conn.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_policy_due_v1
+      await conn.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_policy_pending_to_v1
+      await conn.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]);
+      try {
+        if (locked) await conn.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      } finally {
+        if (pooled) conn.release();
+      }
     }
   }
 
@@ -2620,7 +2664,11 @@ const validatePolicyMailOptions = (mailOptions) => {
     if (Array.isArray(value)) value.forEach((entry, i) => normalizePolicyAddress(entry, `${label}[${i}]`));
     else normalizePolicyAddress(value, label);
   };
-  for (const key of ['from', 'sender', 'replyTo', 'to', 'cc', 'bcc']) check(mailOptions[key], key);
+  const explicit = isPlainObject(mailOptions.envelope) && hasOwnProp(mailOptions.envelope, 'to');
+  // With an explicit `envelope.to`, `preparePolicyEnvelope` treats header recipients as
+  // non-authoritative (group syntax stays legal), so do not reject them here either.
+  const keys = explicit ? ['from', 'sender', 'replyTo'] : ['from', 'sender', 'replyTo', 'to', 'cc', 'bcc'];
+  for (const key of keys) check(mailOptions[key], key);
   if (isPlainObject(mailOptions.envelope)) {
     check(mailOptions.envelope.to, 'envelope.to');
     if (mailOptions.envelope.from !== '') check(mailOptions.envelope.from, 'envelope.from');
@@ -3334,6 +3382,11 @@ class MailTime {
       this.transports.forEach((transport, i) => {
         const from = MailTime.transportFrom(transport);
         if (from !== void 0) normalizePolicyAddress(from, `transports[${i}].from`);
+        // `___compileMailOpts` merges these ahead of `this.from`, so they are sent as-is.
+        for (const key of ['_options', 'options']) {
+          const mailFrom = transport?.[key]?.mailOptions?.from;
+          if (mailFrom !== void 0) normalizePolicyAddress(mailFrom, `transports[${i}].${key}.mailOptions.from`);
+        }
       });
     }
 
@@ -3644,7 +3697,7 @@ class MailTime {
    * @description add email to the queue or append to existing letter if {concatEmails: true}
    * @param {MailTimeMailOptions} opts - email options
    * @returns {Promise<string>} uuid of the email
-   * @throws {Error}
+   * @throws {Error} missing `html`/`text`, a `raw` field, or an invalid `to`; with `recipientPolicies`, an unparseable address rejects with `error.code === 'MAIL_TIME_INVALID_ADDRESS'` and `error.field` naming the field (header recipients are skipped when `envelope.to` is explicit)
    */
   async sendMail(opts) {
     opts = (opts && typeof opts === 'object') ? opts : {};
@@ -4730,6 +4783,9 @@ class MailTime {
     if (this.__isDestroyed || this.__isPaused) {
       return;
     }
+    // Under `strategy: 'backup'` a quarantined primary is never selected for a send, so the
+    // send path alone would never re-probe it. Sweep here so recovery does not depend on row flow.
+    for (const index of this.__unhealthyTransports) this.___maybeReprobe(index);
     const limit = this.mode === 'one' ? 1 : Infinity;
     this.__schedulerScans++;
     try {
@@ -4878,12 +4934,8 @@ class MailTime {
     }
     if (quarantined) {
       const st = this.__reprobe.get(index);
-      if (st) {
-        st.inFlight = false;
-        st.count++;
-        st.nextProbeAt = Date.now() + Math.min(REPROBE_BASE_MS * Math.pow(2, st.count), REPROBE_MAX_MS);
-        this.__debug(`[private reprobe] transport #${index} failed, next probe at ${new Date(st.nextProbeAt)}`);
-      }
+      // A slot already released by the timeout path keeps its backoff; do not double it twice.
+      if (st && st.inFlight) this.___backoffReprobe(index, st, 'failed');
       return;
     }
     this.__unhealthyTransports.add(index);
@@ -4899,7 +4951,7 @@ class MailTime {
    * @internal
    * @memberOf MailTime
    * @name ___maybeReprobe
-   * @description Start one background `verify()` probe for a quarantined transport when its backoff has elapsed and no probe is in flight. Never awaited by the send path. Backoff starts at 60 s, doubles per failed probe and caps at 15 min. A probe that times out stays in flight until its verdict arrives, so at most one `verify()` is outstanding per transport. Failures only reach `__debug`. No probes for `type: 'client'`, `verifyTransports: false`, or after `destroy()`.
+   * @description Start one background `verify()` probe for a quarantined transport when its backoff has elapsed and no probe is in flight. Never awaited by the send path. Backoff starts at 60 s, doubles per failed or timed-out probe and caps at 15 min. A probe that reaches `verifyTimeout` without a verdict releases the slot (one `verify()` may then overlap with the hung one); its late verdict still applies unless a newer probe has started. Failures only reach `__debug`. No probes for `type: 'client'`, `verifyTransports: false`, or after `destroy()`.
    * @param {number} index
    * @returns {void}
    */
@@ -4914,9 +4966,33 @@ class MailTime {
     }
     st.inFlight = true;
     this.__debug(`[private reprobe] transport #${index}, attempt after ${st.count} failure(s)`);
-    // The verdict, not the timeout, releases `inFlight` (see ___applyVerdict), so a hung
-    // verify() never overlaps with a new probe on the same transport.
-    this.___verifyOne(transport, index);
+    // A verdict releases `inFlight` (see ___applyVerdict). A probe that reaches `verifyTimeout`
+    // without one counts as a failed attempt so a verify() that never settles cannot pin the
+    // transport in quarantine; its late verdict still applies unless a newer probe has started.
+    this.___verifyOne(transport, index).then((outcome) => {
+      // A live verdict always clears `inFlight` in ___applyVerdict. If it is still set, the probe
+      // timed out or its verdict was ignored (superseded generation); either way free the slot.
+      if (st.inFlight && this.__reprobe.get(index) === st) {
+        this.___backoffReprobe(index, st, outcome === 'timeout' ? 'timed out' : 'superseded');
+      }
+    });
+  }
+
+  /**
+   * @internal
+   * @memberOf MailTime
+   * @name ___backoffReprobe
+   * @description Release a re-probe slot after a failed or timed-out probe and double its backoff (cap 15 min).
+   * @param {number} index
+   * @param {{ count: number, nextProbeAt: number, inFlight: boolean }} st
+   * @param {string} why
+   * @returns {void}
+   */
+  ___backoffReprobe(index, st, why) {
+    st.inFlight = false;
+    st.count++;
+    st.nextProbeAt = Date.now() + Math.min(REPROBE_BASE_MS * Math.pow(2, st.count), REPROBE_MAX_MS);
+    this.__debug(`[private reprobe] transport #${index} ${why}, next probe at ${new Date(st.nextProbeAt)}`);
   }
 
   /**

package/index.d.cts

@@ -400,7 +400,7 @@ export class MailTime {
      * @description add email to the queue or append to existing letter if {concatEmails: true}
      * @param {MailTimeMailOptions} opts - email options
      * @returns {Promise<string>} uuid of the email
-     * @throws {Error}
+     * @throws {Error} missing `html`/`text`, a `raw` field, or an invalid `to`; with `recipientPolicies`, an unparseable address rejects with `error.code === 'MAIL_TIME_INVALID_ADDRESS'` and `error.field` naming the field (header recipients are skipped when `envelope.to` is explicit)
      */
     sendMail(opts: MailTimeMailOptions): Promise<string>;
     /**

package/index.d.ts

@@ -400,7 +400,7 @@ export class MailTime {
      * @description add email to the queue or append to existing letter if {concatEmails: true}
      * @param {MailTimeMailOptions} opts - email options
      * @returns {Promise<string>} uuid of the email
-     * @throws {Error}
+     * @throws {Error} missing `html`/`text`, a `raw` field, or an invalid `to`; with `recipientPolicies`, an unparseable address rejects with `error.code === 'MAIL_TIME_INVALID_ADDRESS'` and `error.field` naming the field (header recipients are skipped when `envelope.to` is explicit)
      */
     sendMail(opts: MailTimeMailOptions): Promise<string>;
     /**

package/index.js

@@ -428,6 +428,11 @@ class MailTime {
       this.transports.forEach((transport, i) => {
         const from = MailTime.transportFrom(transport);
         if (from !== void 0) normalizePolicyAddress(from, `transports[${i}].from`);
+        // `___compileMailOpts` merges these ahead of `this.from`, so they are sent as-is.
+        for (const key of ['_options', 'options']) {
+          const mailFrom = transport?.[key]?.mailOptions?.from;
+          if (mailFrom !== void 0) normalizePolicyAddress(mailFrom, `transports[${i}].${key}.mailOptions.from`);
+        }
       });
     }
 
@@ -738,7 +743,7 @@ class MailTime {
    * @description add email to the queue or append to existing letter if {concatEmails: true}
    * @param {MailTimeMailOptions} opts - email options
    * @returns {Promise<string>} uuid of the email
-   * @throws {Error}
+   * @throws {Error} missing `html`/`text`, a `raw` field, or an invalid `to`; with `recipientPolicies`, an unparseable address rejects with `error.code === 'MAIL_TIME_INVALID_ADDRESS'` and `error.field` naming the field (header recipients are skipped when `envelope.to` is explicit)
    */
   async sendMail(opts) {
     opts = (opts && typeof opts === 'object') ? opts : {};
@@ -1824,6 +1829,9 @@ class MailTime {
     if (this.__isDestroyed || this.__isPaused) {
       return;
     }
+    // Under `strategy: 'backup'` a quarantined primary is never selected for a send, so the
+    // send path alone would never re-probe it. Sweep here so recovery does not depend on row flow.
+    for (const index of this.__unhealthyTransports) this.___maybeReprobe(index);
     const limit = this.mode === 'one' ? 1 : Infinity;
     this.__schedulerScans++;
     try {
@@ -1972,12 +1980,8 @@ class MailTime {
     }
     if (quarantined) {
       const st = this.__reprobe.get(index);
-      if (st) {
-        st.inFlight = false;
-        st.count++;
-        st.nextProbeAt = Date.now() + Math.min(REPROBE_BASE_MS * Math.pow(2, st.count), REPROBE_MAX_MS);
-        this.__debug(`[private reprobe] transport #${index} failed, next probe at ${new Date(st.nextProbeAt)}`);
-      }
+      // A slot already released by the timeout path keeps its backoff; do not double it twice.
+      if (st && st.inFlight) this.___backoffReprobe(index, st, 'failed');
       return;
     }
     this.__unhealthyTransports.add(index);
@@ -1993,7 +1997,7 @@ class MailTime {
    * @internal
    * @memberOf MailTime
    * @name ___maybeReprobe
-   * @description Start one background `verify()` probe for a quarantined transport when its backoff has elapsed and no probe is in flight. Never awaited by the send path. Backoff starts at 60 s, doubles per failed probe and caps at 15 min. A probe that times out stays in flight until its verdict arrives, so at most one `verify()` is outstanding per transport. Failures only reach `__debug`. No probes for `type: 'client'`, `verifyTransports: false`, or after `destroy()`.
+   * @description Start one background `verify()` probe for a quarantined transport when its backoff has elapsed and no probe is in flight. Never awaited by the send path. Backoff starts at 60 s, doubles per failed or timed-out probe and caps at 15 min. A probe that reaches `verifyTimeout` without a verdict releases the slot (one `verify()` may then overlap with the hung one); its late verdict still applies unless a newer probe has started. Failures only reach `__debug`. No probes for `type: 'client'`, `verifyTransports: false`, or after `destroy()`.
    * @param {number} index
    * @returns {void}
    */
@@ -2008,9 +2012,33 @@ class MailTime {
     }
     st.inFlight = true;
     this.__debug(`[private reprobe] transport #${index}, attempt after ${st.count} failure(s)`);
-    // The verdict, not the timeout, releases `inFlight` (see ___applyVerdict), so a hung
-    // verify() never overlaps with a new probe on the same transport.
-    this.___verifyOne(transport, index);
+    // A verdict releases `inFlight` (see ___applyVerdict). A probe that reaches `verifyTimeout`
+    // without one counts as a failed attempt so a verify() that never settles cannot pin the
+    // transport in quarantine; its late verdict still applies unless a newer probe has started.
+    this.___verifyOne(transport, index).then((outcome) => {
+      // A live verdict always clears `inFlight` in ___applyVerdict. If it is still set, the probe
+      // timed out or its verdict was ignored (superseded generation); either way free the slot.
+      if (st.inFlight && this.__reprobe.get(index) === st) {
+        this.___backoffReprobe(index, st, outcome === 'timeout' ? 'timed out' : 'superseded');
+      }
+    });
+  }
+
+  /**
+   * @internal
+   * @memberOf MailTime
+   * @name ___backoffReprobe
+   * @description Release a re-probe slot after a failed or timed-out probe and double its backoff (cap 15 min).
+   * @param {number} index
+   * @param {{ count: number, nextProbeAt: number, inFlight: boolean }} st
+   * @param {string} why
+   * @returns {void}
+   */
+  ___backoffReprobe(index, st, why) {
+    st.inFlight = false;
+    st.count++;
+    st.nextProbeAt = Date.now() + Math.min(REPROBE_BASE_MS * Math.pow(2, st.count), REPROBE_MAX_MS);
+    this.__debug(`[private reprobe] transport #${index} ${why}, next probe at ${new Date(st.nextProbeAt)}`);
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-time",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "description": "📮 Email queue extending nodemailer with multi-SMTP transports and horizontally scaled apps support",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -39,24 +39,40 @@
       "import": {
         "types": "./presets.d.ts",
         "default": "./presets.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
       }
     },
     "./adapters/mongo": {
       "import": {
         "types": "./adapters/mongo.d.ts",
         "default": "./adapters/mongo.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
       }
     },
     "./adapters/redis": {
       "import": {
         "types": "./adapters/redis.d.ts",
         "default": "./adapters/redis.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
       }
     },
     "./adapters/postgres": {
       "import": {
         "types": "./adapters/postgres.d.ts",
         "default": "./adapters/postgres.js"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.cjs"
       }
     },
     "./package.json": "./package.json"
@@ -75,7 +91,9 @@
     "test:redis": "mocha ./test/npm-redis-redis.js",
     "test:mongo": "mocha ./test/npm-mongo-mongo.js",
     "test:postgres": "mocha ./test/npm-postgres.js",
-    "test:bun": "bun test ./test/jest"
+    "test:bun": "bun test ./test/jest",
+    "test:pack": "node ./scripts/check-package.mjs",
+    "test:mocha:local": "REDIS_URL=redis://127.0.0.1:6379 MONGO_URL=mongodb://127.0.0.1:27017/npm-mail-time-test PG_URL=postgres://postgres:postgres@127.0.0.1:5432/postgres npm run test:mocha"
   },
   "keywords": [
     "backup",
@@ -154,6 +172,7 @@
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@types/node": "^25.9.0",
+    "@types/pg": "^8.23.1",
     "acorn": "^8.18.0",
     "chai": "^6.2.2",
     "jest": "^30.4.2",

package/recipient-policy.js

@@ -176,7 +176,11 @@ const validatePolicyMailOptions = (mailOptions) => {
     if (Array.isArray(value)) value.forEach((entry, i) => normalizePolicyAddress(entry, `${label}[${i}]`));
     else normalizePolicyAddress(value, label);
   };
-  for (const key of ['from', 'sender', 'replyTo', 'to', 'cc', 'bcc']) check(mailOptions[key], key);
+  const explicit = isPlainObject(mailOptions.envelope) && hasOwnProp(mailOptions.envelope, 'to');
+  // With an explicit `envelope.to`, `preparePolicyEnvelope` treats header recipients as
+  // non-authoritative (group syntax stays legal), so do not reject them here either.
+  const keys = explicit ? ['from', 'sender', 'replyTo'] : ['from', 'sender', 'replyTo', 'to', 'cc', 'bcc'];
+  for (const key of keys) check(mailOptions[key], key);
   if (isPlainObject(mailOptions.envelope)) {
     check(mailOptions.envelope.to, 'envelope.to');
     if (mailOptions.envelope.from !== '') check(mailOptions.envelope.from, 'envelope.from');