mail-time 5.1.0 → 5.2.1

package/README.md

@@ -1,6 +1,3 @@
-
-# MailTime
-
 [![npm version][badge-npm-v]][npm-url]
 [![npm downloads][badge-npm-dm]][npm-url]
 [![CI][badge-ci]][ci-url]
@@ -14,6 +11,11 @@
 [![dependencies][badge-deps]][deps-url]
 [![Sponsor][badge-sponsor]][sponsor-url]
 [![Donate][badge-donate]][donate-url]
+<a href="https://bridge-cdn.com/?ref=github-mail-time-repo-top"><img src="https://bridge-cdn.com/favicon.svg" height="20"></a>
+<a href="https://ostr.io/info/built-by-developers-for-developers?ref=github-mail-time-repo-top"><img src="https://ostr.io/apple-touch-icon-60x60.png" height="20"></a>
+<a href="https://meteor-files.com/?ref=github-mail-time-repo-top"><img src="https://meteor-files.com/apple-touch-icon-60x60.png" height="20"></a>
+
+# MailTime
 
 Bulletproof email queue for [horizontally scaled](#sending-emails-from-a-cluster) Node.js & Bun apps. Built on top of [`nodemailer`](https://github.com/nodemailer/nodemailer) and [`josk`](https://github.com/veliovgroup/josk). Single runtime dependency, ESM + CJS, full TypeScript declarations.
 
@@ -267,15 +269,16 @@ export const mailQueue = new MailTime({
 
 ```js
 process.on('SIGTERM', async () => {
-  await mailQueue.destroy({ drain: true }); // stop scheduler, then wait for in-flight SMTPs
+  const finished = await mailQueue.destroy({ drain: true, schedulerTimeout: 30_000 });
+  if (!finished) console.error('Queue scan did not finish before scheduler timeout');
 });
 ```
 
-`destroy()` without `{ drain: true }` stops immediately: in-flight completions make no storage writes and their claims recover after `sendingTimeout`. Use it for forced teardown, not graceful shutdown.
+Graceful destroy waits for JoSk's running queue scan, then in-flight SMTP; claim renewal keeps running while sends drain. Sends still waiting for a `concurrency` slot are dropped at once and their rows stay unclaimed for the next scan, so in-flight SMTP does not count against `schedulerTimeout`. `schedulerTimeout` defaults to 10 seconds for JoSk's running-handler wait; it does not bound JoSk's own storage scan, SMTP, or policy hooks. A timed-out handler or a failed JoSk shutdown (logged) returns `false`; the Promise never rejects. `destroy()` without `{ drain: true }` stops immediately: in-flight completions make no storage writes and their claims recover after `sendingTimeout`. See [JoSk 6.4 recovery and shutdown](https://github.com/veliovgroup/mail-time/blob/master/docs/tuning.md#josk-64-restarts-and-shutdown).
 
 #### Pause / resume a server (backpressure)
 
-`pause()` stops this **server** instance from competing for the queue-drain lease without tearing it down (unlike `destroy()`). In-flight SMTP sends finish; other `server` instances keep draining. `resume()` resumes and triggers an immediate scan.
+`pause()` stops this **server** instance from competing for the queue-drain lease without tearing it down (unlike `destroy()`). In-flight SMTP sends finish; sends still waiting for a `concurrency` slot are dropped and their rows stay queued; other `server` instances keep draining. `resume()` resumes and triggers an immediate scan.
 
 ```js
 mailQueue.pause();              // stop draining on this pod
@@ -377,7 +380,7 @@ Defaults fit moderate traffic in a single region. Reach for a [preset](#settings
 | `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.** Iterate releases the JoSk lease as soon as scanning ends — only a stalled storage scan can blow this.         |
+| `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                                                                                                |
@@ -400,6 +403,30 @@ new MailTime({
 
 Transports may also set `error.mayFailOver = false`. Retry timing stays unchanged. Edge cases: [v4.1 → v5 migration guide](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md#shouldfailovererror-info-email).
 
+## Recipient policies
+
+Opt in with `recipientPolicies` to suppress recipients before SMTP or classify attributable transport rejections. Omitting it preserves existing delivery and callback behavior. Supply your own suppression store:
+
+```js
+const suppressed = new Set(['unsubscribed@example.com']);
+
+new MailTime({
+  queue, transports, josk,
+  recipientPolicies: [{
+    name: 'unsubscribe',
+    beforeSend({ recipients }) {
+      return { decisions: recipients.filter(({ address }) => suppressed.has(address))
+        .map(({ address }) => ({ address, status: 'suppressed', reason: 'unsubscribed' })) };
+    },
+  }],
+  onSuppressed(task, recipients) {
+    console.log(task.uuid, recipients.map(({ address }) => address));
+  },
+});
+```
+
+Only the SMTP envelope is filtered. Headers remain unchanged; some transports retain BCC in generated MIME. If suppressed addresses must not appear in message content, remove them from headers before enqueueing. See [recipient policy hooks, outcomes, recovery, and rollout](https://github.com/veliovgroup/mail-time/blob/master/docs/recipient-policies.md).
+
 ## Queue payload trust
 
 `raw` is always refused. Use `strictPayload` when queue writers should not control attachments, URLs, envelope, DKIM, or other nodemailer capabilities:
@@ -478,7 +505,7 @@ await mailQueue.sendMail({
 | `failsToNext`                 | `number`                                            | `4`                        | (`backup`) failures-in-a-row before rotating.                                                                                                                                               |
 | `retries`                     | `number`                                            | `59`                       | Re-send attempts after first failure. Total attempts = `retries + 1` (defaults to 60). Legacy alias `maxTries` is honored when `retries` is absent: `new MailTime({ maxTries: N })` sets total attempts to `N`.                |
 | `retryDelay`                  | `number` (ms)                                       | `60000`                    | Wait between attempts.                                                                                                                                                                      |
-| `keepHistory`                 | `boolean`                                           | `false`                    | Keep sent/failed/cancelled rows.                                                                                                                                                            |
+| `keepHistory`                 | `boolean`                                           | `false`                    | Keep terminal rows, including settled policy outcomes.                                                                                                                                                            |
 | `concatEmails`                | `boolean \| { subject?: string }`                   | `false`                    | Fold same-`to` letters into one. Pass `{ subject: 'X' }` to set the folded-letter subject inline; the string supports the `{{count}}` placeholder and overrides `concatSubject`.            |
 | `concatSubject`               | `string`                                            | `'Multiple notifications'` | Subject when folded. Supports `{{count}}` for the folded letter count.                                                                                                                      |
 | `concatDelimiter`             | `string`                                            | `'<hr>'`                   | Separator between folded bodies.                                                                                                                                                            |
@@ -497,8 +524,11 @@ await mailQueue.sendMail({
 | `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`                                          | —                          | Called once the task is fully delivered. `email.mailOptions[i].accepted` lists every address that got through (across all attempts).                                                        |
-| `onError(error, email, info)` | `function`                                          | —                          | Called once the retry budget is exhausted with at least one un-accepted recipient. `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' }`. |
+| `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, info)` | `function`                                          | —                          | 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' }`. |
+| `recipientPolicies` | `MailTimeRecipientPolicy[]` | — | Optional nonempty provider list. 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. |
 
 ### JoSk options
 
@@ -509,7 +539,7 @@ await mailQueue.sendMail({
 | `adapter`                 | —                 | Either a constructed adapter or a config object: `{ type: 'redis' \| 'mongo' \| 'postgres', client \| db, prefix?, resetOnInit?, useHashTags? }`. MailTime constructs the adapter from the config object. Set `useHashTags: true` on Redis/KeyDB Cluster. |
 | `minRevolvingDelay`       | `512`             | Lower bound of poll window.                                                                                    |
 | `maxRevolvingDelay`       | `2048`            | Upper bound.                                                                                                   |
-| `zombieTime`              | `60000`           | Re-claim if `queue.iterate()` runs longer than this. **Do not drop below 60s.**                                |
+| `zombieTime`              | `60000`           | Recovery after an unfinished scan or unclean worker death. **Do not drop below 60s.**                        |
 | `lockLeaseTime`           | `30000`           | JoSk scheduler lease TTL. JoSk floors it at `2 * maxRevolvingDelay + 1000`; increase for slow storage claim batches. Separate from `zombieTime`, which controls task recovery. |
 | `execute`                 | `'batch'`         | JoSk scheduler batching; low impact for MailTime (one interval task per instance).                             |
 | `concurrency`             | `Infinity`        | Cap overlapping JoSk handler runs on **this** process (`1` if ticks pile up).                                  |
@@ -528,7 +558,7 @@ For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup
 - `cancel(uuid)` — alias of `cancelMail`.
 - `ping()` → `Promise<{status, code, statusCode, paused?, error?}>`. Pings scheduler then queue; `paused` reflects `isPaused`.
 - `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects with `.cause` on storage failure.
-- `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Stops scheduler. Idempotent. Use `await destroy({ drain: true })` for graceful shutdown; plain `destroy()` aborts completion writes.
+- `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<void>`. Resolves once every in-flight SMTP attempt finishes. Useful in tests and graceful-shutdown paths.
 - `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`.
@@ -545,7 +575,7 @@ For custom adapters see [docs/queue-api.md](https://github.com/veliovgroup/mail-
 
 ### Redis Cluster
 
-Set `useHashTags: true` on both `RedisQueue` and its JoSk Redis adapter. Queue state then uses `mailtime:{prefix}:letters` plus a tagged sorted-set schedule, so node-redis `createCluster()` can route every Lua operation to one slot. One prefix is one slot; shard high-volume traffic across prefixes. Tagged `iterate` returns at most 100 due rows per tick. Existing standalone keys are not read in this mode. Follow [Redis Cluster migration](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5-v5.1.md) before cutover.
+Set `useHashTags: true` on both `RedisQueue` and its JoSk Redis adapter. Queue state then uses `mailtime:{prefix}:letters` plus a tagged sorted-set schedule, so node-redis `createCluster()` can route Lua operations to one slot with Redis client 4 or 5. JoSk 6.4 rejects Cluster clients without the setting. One prefix is one slot; shard high-volume traffic across prefixes. Tagged `iterate` returns at most 100 due rows per tick. Existing standalone keys are not read in this mode. Follow [Redis Cluster migration](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5-v5.1.md) before cutover.
 
 ### Module functions
 
@@ -608,12 +638,13 @@ Mixed clusters (some Node, some Bun) share one schedule under the same `prefix`
 
 ## Support this project
 
+- Try [🌉 Bridge CDN](https://bridge-cdn.com/?ref=github-mail-time-repo-footer) - A SEO-focused Cloudflare alternative. CDN, DNS, IndexNow, Prerender, SEO, Edge Computing.
+- Try [☄️ meteor-files.com](https://meteor-files.com/?ref=github-mail-time-repo-footer).
+- Try [▲ ostr.io](https://ostr.io?ref=github-mail-time-repo-footer) for server monitoring, web analytics, web-CRON, and SEO pre-rendering.
 - Star on [GitHub](https://github.com/veliovgroup/mail-time) and [NPM](https://www.npmjs.com/package/mail-time).
 - [Sponsor maintainer on GitHub](https://github.com/sponsors/dr-dimitru).
 - [Sponsor veliovgroup on GitHub](https://github.com/sponsors/veliovgroup).
 - [PayPal](https://paypal.me/veliovgroup).
-- Try [☄️ meteor-files.com](https://meteor-files.com/?ref=github-mail-time-repo-footer).
-- Try [▲ ostr.io](https://ostr.io?ref=github-mail-time-repo-footer) for server monitoring, web analytics, web-CRON, and SEO pre-rendering.
 
 [npm-url]: https://www.npmjs.com/package/mail-time
 [badge-npm-v]: https://img.shields.io/npm/v/mail-time.svg

package/adapters/mongo.d.ts

@@ -34,6 +34,7 @@ export class MongoQueue {
      */
     constructor(opts: MongoQueueOption);
     name: string;
+    supportsRecipientPolicies: boolean;
     db: Db;
     prefix: any;
     collection: MongoCollection | undefined;

package/adapters/mongo.js

@@ -1,6 +1,7 @@
 import {
   debug,
   logError,
+  hasOwnProp,
   isSendClaimUpdate,
   isSendLeaseGuardedUpdate,
   isAppendMailOptionUpdate,
@@ -80,6 +81,7 @@ class MongoQueue {
    */
   constructor (opts) {
     this.name = 'mongo-queue';
+    this.supportsRecipientPolicies = true;
     if (!opts || typeof opts !== 'object') {
       throw new TypeError('[mail-time] Configuration object must be passed into MongoQueue constructor');
     }
@@ -100,8 +102,8 @@ class MongoQueue {
     this.collection = this.db.collection(`__mailTimeQueue__${prefix}`);
     this.__readyPromise = Promise.all([
       ensureIndex(this.collection, { uuid: 1 }, { background: false }),
-      ensureIndex(this.collection, { isSent: 1, isFailed: 1, isCancelled: 1, to: 1, sendAt: 1 }, { background: false }),
-      ensureIndex(this.collection, { isSent: 1, isFailed: 1, isCancelled: 1, isSending: 1, sendingAt: 1, sendAt: 1, tries: 1 }, { background: false }),
+      ensureIndex(this.collection, { isSettled: 1, isSent: 1, isFailed: 1, isCancelled: 1, to: 1, sendAt: 1 }, { name: 'mailtime_policy_pending_to_v1', background: false }),
+      ensureIndex(this.collection, { isSettled: 1, isSent: 1, isFailed: 1, isCancelled: 1, isSending: 1, sendingAt: 1, sendAt: 1, tries: 1 }, { name: 'mailtime_policy_due_v1', background: false }),
     ]).then(() => void 0);
   }
 
@@ -200,12 +202,13 @@ class MongoQueue {
         sendAt: {
           $lte: now,
         },
-        tries: {
-          $lt: this.mailTimeInstance.maxTries,
-        },
-        $or: [
-          { isSending: { $ne: true } },
-          { sendingAt: { $lte: now - sendingTimeout } },
+        isSettled: { $ne: true },
+        $and: [
+          { $or: [{ isSending: { $ne: true } }, { sendingAt: { $lte: now - sendingTimeout } }] },
+          { $or: [
+            { tries: { $lt: this.mailTimeInstance.maxTries } },
+            { recipientResults: { $type: 'array' }, isSending: true, sendingAt: { $lte: now - sendingTimeout } },
+          ] },
         ],
       }, {
         projection: {
@@ -221,6 +224,8 @@ class MongoQueue {
           sendingAt: 1,
           mailOptions: 1,
           concatSubject: 1,
+          isSettled: 1,
+          recipientResults: 1,
         },
       });
 
@@ -229,7 +234,7 @@ class MongoQueue {
       }
 
       try {
-        while (await cursor.hasNext()) {
+        while (!this.mailTimeInstance.___isStopped && await cursor.hasNext()) {
           await this.mailTimeInstance.___dispatch(await cursor.next());
         }
       } finally {
@@ -262,6 +267,8 @@ class MongoQueue {
       isFailed: false,
       isCancelled: false,
       isSending: { $ne: true },
+      isSettled: { $ne: true },
+      recipientResults: { $exists: false },
       tries: { $lt: this.mailTimeInstance.maxTries },
       sendAt: {
         $lte: sendAt,
@@ -275,6 +282,8 @@ class MongoQueue {
         isSent: 1,
         isFailed: 1,
         isCancelled: 1,
+        isSettled: 1,
+        recipientResults: 1,
         mailOptions: 1,
       },
     });
@@ -322,20 +331,20 @@ class MongoQueue {
         uuid: 1,
         isSent: 1,
         isCancelled: 1,
+        isSettled: 1,
       },
     });
 
-    if (!task || task.isSent === true || task.isCancelled === true) {
+    if (!task || task.isSent === true || task.isCancelled === true || task.isSettled === true) {
       return false;
     }
-
+    const query = { _id: task._id, isSent: false, isCancelled: false, isSettled: { $ne: true },
+      $or: [{ recipientResults: { $exists: false } }, { isFailed: false }] };
     if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(task);
+      return ((await this.collection.deleteOne(query))?.deletedCount || 0) >= 1;
     }
-
-    return await this.update(task, {
-      isCancelled: true,
-    });
+    const result = await this.collection.updateOne(query, { $set: { isCancelled: true } });
+    return (result?.matchedCount || result?.modifiedCount || 0) >= 1;
   }
 
   /**
@@ -356,6 +365,8 @@ class MongoQueue {
 
     const query = { _id: task._id };
     if (isSendLeaseRemove(opts)) {
+      query.isSent = false;
+      query.isSettled = { $ne: true };
       query.tries = opts.leaseTries;
       query.isSending = true;
       query.sendingAt = opts.leaseSendingAt;
@@ -382,6 +393,8 @@ class MongoQueue {
       return false;
     }
     this.__ensurePrefix();
+    if ((hasOwnProp(updateObj, 'recipientResults') || hasOwnProp(updateObj, 'isSettled'))
+      && !isSendClaimUpdate(updateObj) && !isSendLeaseGuardedUpdate(updateObj)) return false;
 
     if (isAppendMailOptionUpdate(updateObj)) {
       const res = await this.collection.updateOne({
@@ -390,6 +403,8 @@ class MongoQueue {
         isFailed: false,
         isCancelled: false,
         isSending: { $ne: true },
+        isSettled: { $ne: true },
+        recipientResults: { $exists: false },
       }, {
         $push: {
           mailOptions: updateObj.appendMailOption,
@@ -408,12 +423,15 @@ class MongoQueue {
       query.isSent = false;
       query.isFailed = false;
       query.isCancelled = false;
+      query.isSettled = { $ne: true };
       query.tries = task.tries;
       query.$or = [
         { isSending: { $ne: true } },
         { sendingAt: { $lte: now - sendingTimeout } },
       ];
     } else if (isSendLeaseGuardedUpdate(updateObj)) {
+      query.isSent = false;
+      query.isSettled = { $ne: true };
       query.tries = updateObj.leaseTries;
       query.isSending = true;
       query.sendingAt = updateObj.leaseSendingAt;
@@ -424,7 +442,7 @@ class MongoQueue {
     const res = await this.collection.updateOne(query, {
       $set: stripInternalUpdateMeta(updateObj),
     });
-    if (isSendClaimUpdate(updateObj)) {
+    if (isSendClaimUpdate(updateObj) || isSendLeaseGuardedUpdate(updateObj)) {
       return (res?.modifiedCount || res?.matchedCount || 0) >= 1;
     }
     return (res?.modifiedCount || 0) >= 1;

package/adapters/postgres.d.ts

@@ -17,6 +17,7 @@ export class PostgresQueue {
      */
     constructor(opts: PostgresQueueOption);
     name: string;
+    supportsRecipientPolicies: boolean;
     client: PostgresClient;
     prefix: any;
     /**

package/adapters/postgres.js

@@ -2,6 +2,7 @@ import { createHash } from 'crypto';
 import {
   debug,
   logError,
+  hasOwnProp,
   isSendClaimUpdate,
   isSendLeaseGuardedUpdate,
   isAppendMailOptionUpdate,
@@ -48,6 +49,8 @@ const fieldMap = {
   tries: 'tries',
   sendAt: 'send_at',
   isSent: 'is_sent',
+  isSettled: 'is_settled',
+  recipientResults: 'recipient_results',
   isCancelled: 'is_cancelled',
   isFailed: 'is_failed',
   isSending: 'is_sending',
@@ -77,6 +80,8 @@ const normalizeRow = (row) => {
     tries: parseInt(row.tries, 10),
     sendAt: parseInt(row.send_at, 10),
     isSent: row.is_sent,
+    isSettled: row.is_settled === true,
+    recipientResults: row.recipient_results == null ? void 0 : parseMailOptions(row.recipient_results),
     isCancelled: row.is_cancelled,
     isFailed: row.is_failed,
     isSending: row.is_sending === true,
@@ -96,6 +101,7 @@ class PostgresQueue {
    */
   constructor(opts) {
     this.name = 'postgres-queue';
+    this.supportsRecipientPolicies = true;
     if (!opts || typeof opts !== 'object') {
       throw new TypeError('[mail-time] Configuration object must be passed into PostgresQueue constructor');
     }
@@ -156,6 +162,8 @@ class PostgresQueue {
           tries INTEGER NOT NULL DEFAULT 0,
           send_at BIGINT NOT NULL,
           is_sent BOOLEAN NOT NULL DEFAULT false,
+          is_settled BOOLEAN NOT NULL DEFAULT false,
+          recipient_results JSONB,
           is_cancelled BOOLEAN NOT NULL DEFAULT false,
           is_failed BOOLEAN NOT NULL DEFAULT false,
           is_sending BOOLEAN NOT NULL DEFAULT false,
@@ -167,14 +175,16 @@ class PostgresQueue {
           created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
           updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
         )`);
+      await this.client.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS is_settled BOOLEAN NOT NULL DEFAULT false');
+      await this.client.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS recipient_results JSONB');
       await this.client.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_mail_time_queue_prefix_uuid
         ON mail_time_queue (prefix, uuid)`);
 
-      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_due
-        ON mail_time_queue (prefix, is_sent, is_failed, is_cancelled, is_sending, sending_at, send_at, tries)`);
+      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_due_v1
+        ON mail_time_queue (prefix, is_settled, is_sent, is_failed, is_cancelled, is_sending, sending_at, send_at, tries)`);
 
-      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_pending_to
-        ON mail_time_queue (prefix, to_address, is_sent, is_failed, is_cancelled, send_at)`);
+      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_pending_to_v1
+        ON mail_time_queue (prefix, to_address, is_settled, is_sent, is_failed, is_cancelled, send_at)`);
     } finally {
       await this.client.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
     }
@@ -249,19 +259,23 @@ class PostgresQueue {
 
     try {
       const res = await this.client.query(`SELECT id, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-               is_sending, sending_at, template, transport, concat_subject, mail_options
+               is_sending, sending_at, template, transport, concat_subject, mail_options, is_settled, recipient_results
         FROM mail_time_queue
         WHERE prefix = $1
           AND is_sent = false
           AND is_failed = false
           AND is_cancelled = false
+          AND is_settled = false
           AND send_at <= $2
-          AND tries < $3
+          AND (tries < $3 OR (recipient_results IS NOT NULL AND is_sending = true AND sending_at <= $4))
           AND (is_sending = false OR sending_at <= $4)
         ORDER BY send_at ASC
         LIMIT $5`, [this.prefix, now, this.mailTimeInstance.maxTries, now - sendingTimeout, limit]);
 
       for (const row of res.rows || []) {
+        if (this.mailTimeInstance.___isStopped) {
+          break;
+        }
         await this.mailTimeInstance.___dispatch(normalizeRow(row));
       }
     } catch (iterateError) {
@@ -287,7 +301,7 @@ class PostgresQueue {
     await this.ready();
 
     const res = await this.client.query(`SELECT id, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-             is_sending, sending_at, template, transport, concat_subject, mail_options
+             is_sending, sending_at, template, transport, concat_subject, mail_options, is_settled, recipient_results
       FROM mail_time_queue
       WHERE prefix = $1
         AND to_address = $2
@@ -295,6 +309,8 @@ class PostgresQueue {
         AND is_failed = false
         AND is_cancelled = false
         AND is_sending = false
+        AND is_settled = false
+        AND recipient_results IS NULL
         AND tries < $4
         AND send_at <= $3
       ORDER BY send_at DESC
@@ -325,9 +341,9 @@ class PostgresQueue {
 
     await this.client.query(`INSERT INTO mail_time_queue (
         prefix, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-        is_sending, sending_at, template, transport, concat_subject, mail_options, created_at, updated_at
+        is_sending, sending_at, template, transport, concat_subject, mail_options, is_settled, recipient_results, created_at, updated_at
       )
-      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
       ON CONFLICT (prefix, uuid) DO UPDATE SET
         to_address = EXCLUDED.to_address,
         tries = EXCLUDED.tries,
@@ -341,6 +357,8 @@ class PostgresQueue {
         transport = EXCLUDED.transport,
         concat_subject = EXCLUDED.concat_subject,
         mail_options = EXCLUDED.mail_options,
+        is_settled = EXCLUDED.is_settled,
+        recipient_results = EXCLUDED.recipient_results,
         updated_at = CURRENT_TIMESTAMP`, [
       this.prefix,
       task.uuid,
@@ -356,6 +374,8 @@ class PostgresQueue {
       task.transport,
       task.concatSubject || null,
       JSON.stringify(task.mailOptions || []),
+      task.isSettled === true,
+      task.recipientResults === void 0 ? null : JSON.stringify(task.recipientResults),
     ]);
   }
 
@@ -376,23 +396,20 @@ class PostgresQueue {
     await this.ready();
 
     const task = normalizeRow((await this.client.query(`SELECT id, uuid, to_address, tries, send_at, is_sent, is_cancelled, is_failed,
-             template, transport, concat_subject, mail_options
+             template, transport, concat_subject, mail_options, is_settled, recipient_results
       FROM mail_time_queue
       WHERE prefix = $1
         AND uuid = $2
       LIMIT 1`, [this.prefix, uuid])).rows?.[0]);
 
-    if (!task || task.isSent === true || task.isCancelled === true) {
-      return false;
-    }
-
-    if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(task);
-    }
-
-    return await this.update(task, {
-      isCancelled: true,
-    });
+    if (!task || task.isSent === true || task.isCancelled === true || task.isSettled === true) return false;
+    const operation = this.mailTimeInstance.keepHistory
+      ? 'UPDATE mail_time_queue SET is_cancelled = true, updated_at = CURRENT_TIMESTAMP'
+      : 'DELETE FROM mail_time_queue';
+    const result = await this.client.query(`${operation}
+      WHERE prefix = $1 AND uuid = $2 AND is_sent = false AND is_cancelled = false
+        AND is_settled = false AND (recipient_results IS NULL OR is_failed = false)`, [this.prefix, uuid]);
+    return (result.rowCount || 0) >= 1;
   }
 
   /**
@@ -418,7 +435,7 @@ class PostgresQueue {
     const params = [this.prefix, value];
     if (isSendLeaseRemove(opts)) {
       params.push(opts.leaseTries, opts.leaseSendingAt);
-      leaseWhere = ` AND tries = $3 AND is_sending = true AND sending_at = $4 AND is_cancelled = false AND is_failed = false`;
+      leaseWhere = ` AND tries = $3 AND is_sending = true AND sending_at = $4 AND is_cancelled = false AND is_failed = false AND is_sent = false AND is_settled = false`;
     }
 
     const res = await this.client.query(`DELETE FROM mail_time_queue
@@ -443,6 +460,8 @@ class PostgresQueue {
     }
 
     await this.ready();
+    if ((hasOwnProp(updateObj, 'recipientResults') || hasOwnProp(updateObj, 'isSettled'))
+      && !isSendClaimUpdate(updateObj) && !isSendLeaseGuardedUpdate(updateObj)) return false;
 
     if (isAppendMailOptionUpdate(updateObj)) {
       const where = task.id ? 'id = $3' : 'uuid = $3';
@@ -455,7 +474,9 @@ class PostgresQueue {
           AND is_sent = false
           AND is_failed = false
           AND is_cancelled = false
-          AND is_sending = false`, [
+          AND is_sending = false
+          AND is_settled = false
+          AND recipient_results IS NULL`, [
         JSON.stringify([updateObj.appendMailOption]),
         this.prefix,
         value,
@@ -475,7 +496,7 @@ class PostgresQueue {
       if (key === 'sendAt' && value instanceof Date) {
         value = +value;
       }
-      if (key === 'mailOptions') {
+      if (key === 'mailOptions' || key === 'recipientResults') {
         value = JSON.stringify(value);
       }
 
@@ -499,6 +520,7 @@ class PostgresQueue {
         AND is_sent = false
         AND is_failed = false
         AND is_cancelled = false
+        AND is_settled = false
         AND tries = $${triesIndex}
         AND (is_sending = false OR sending_at <= $${staleIndex})
       `;
@@ -508,6 +530,8 @@ class PostgresQueue {
       values.push(updateObj.leaseSendingAt);
       const sendingAtIndex = values.length;
       claimWhere = `
+        AND is_sent = false
+        AND is_settled = false
         AND tries = $${triesIndex}
         AND is_sending = true
         AND sending_at = $${sendingAtIndex}

package/adapters/redis.d.ts

@@ -3,9 +3,12 @@ export type RedisClient = {
     get: (key: string) => Promise<string | null>;
     set: (key: string, value: string, options?: object) => Promise<unknown>;
     del: (key: string | string[]) => Promise<number>;
-    ping: () => Promise<string>;
+    ping?: (() => Promise<string>) | undefined;
+    getRandomNode?: (() => unknown) | undefined;
+    nodeClient?: ((...args: any[]) => any) | undefined;
+    sendCommand?: ((firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>) | undefined;
     scanIterator?: ((options: object) => AsyncIterable<string | string[]>) | undefined;
-    hGet?: ((key: string, field: string) => Promise<string | null>) | undefined;
+    hGet?: ((key: string, field: string) => Promise<string | null | undefined>) | undefined;
     eval?: ((script: string, options: {
         keys: string[];
         arguments: string[];
@@ -35,6 +38,7 @@ export class RedisQueue {
      */
     constructor(opts: RedisQueueOption);
     name: string;
+    supportsRecipientPolicies: boolean;
     client: RedisClient;
     useHashTags: boolean;
     prefix: any;