@softure-ai/mailing 0.1.6 → 0.1.7

package/src/next/pages.tsx

@@ -2,11 +2,13 @@
 // `export { UnsubscribePage as default } from "@softure-ai/mailing/next"`.
 // A server component without client JavaScript: the button is a plain form posting a server
 // action, so it works in any browser a mail client opens. Opening the page changes nothing (mail
-// scanners open links too) and does not check the signature: the submit does.
+// scanners open links too) and does not check the signature: the submit does. It takes the
+// module's signed links and, with `mailing({ legacyUnsubscribe })`, the app's older ones: mount it
+// at the old links' path too.
 import { getSoftureConfig } from "@softure-ai/core/next";
 import { Button, Card, FormError } from "@softure-ai/ui";
 import type { ReactNode } from "react";
-import { RECIPIENT_PARAM, SIGNATURE_PARAM } from "../server/unsubscribe-link.js";
+import { getUnsubscribeLinkParams, readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { unsubscribeAction } from "./actions.js";
 import { getMailingMessages } from "./messages.js";
 import { UNSUBSCRIBE_STATUS_PARAM } from "./params.js";
@@ -47,16 +49,17 @@ export async function UnsubscribePage({ searchParams }: UnsubscribePageProps) {
   const status = readParam(params, UNSUBSCRIBE_STATUS_PARAM);
   if (status === "done") return <UnsubscribeLayout title={messages.doneTitle} lead={messages.doneBody} />;
 
-  const recipientKey = readParam(params, RECIPIENT_PARAM) ?? "";
-  const signature = readParam(params, SIGNATURE_PARAM) ?? "";
-  if (status === "invalid" || recipientKey === "" || signature === "") {
+  const link = readUnsubscribeLink({ get: (name) => readParam(params, name) ?? null }, config);
+  const linkParams = link === null ? {} : getUnsubscribeLinkParams(link);
+  if (status === "invalid" || link === null || Object.values(linkParams).some((value) => value === "")) {
     return <UnsubscribeLayout title={messages.invalidTitle} lead={messages.invalidBody} />;
   }
   return (
     <UnsubscribeLayout title={messages.title} lead={messages.lead}>
       <form action={unsubscribeAction} className={FORM_CLASS}>
-        <input type="hidden" name={RECIPIENT_PARAM} value={recipientKey} />
-        <input type="hidden" name={SIGNATURE_PARAM} value={signature} />
+        {Object.entries(linkParams).map(([name, value]) => (
+          <input key={name} type="hidden" name={name} value={value} />
+        ))}
         <FormError message={status === "failed" ? messages.failed : undefined} />
         <div>
           <Button type="submit" variant="primary">

package/src/next/route.ts

@@ -12,7 +12,7 @@ import { errorLogLabel } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
 import { getMailingRoutes } from "../server/options.js";
 import { unsubscribe } from "../server/suppressions.js";
-import { readUnsubscribeToken } from "../server/unsubscribe-link.js";
+import { readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { getMailingContext } from "./context.js";
 
 const NO_STORE = { "cache-control": "no-store" };
@@ -21,12 +21,14 @@ const NO_STORE = { "cache-control": "no-store" };
  * Records the opt-out of the link in the URL. The body (`List-Unsubscribe=One-Click`) is not read:
  * anyone can send it, the signature is the proof. 200 once recorded (also again), 400 for a link
  * that does not verify, 500 when the database fails: the client may retry, and 200 would claim an
- * opt-out that did not happen.
+ * opt-out that did not happen. A legacy link (`mailing({ legacyUnsubscribe })`) is handled the same
+ * way; mount this route at the old link's path too.
  */
 export async function postUnsubscribeRoute(request: Request): Promise<Response> {
-  const token = readUnsubscribeToken(new URL(request.url).searchParams);
   try {
-    const result = await unsubscribe(await getMailingContext(), token, "one-click");
+    const ctx = await getMailingContext();
+    const link = readUnsubscribeLink(new URL(request.url).searchParams, ctx.config);
+    const result = await unsubscribe(ctx, link, "one-click");
     return new Response(null, { status: result.ok ? 200 : 400, headers: NO_STORE });
   } catch (error) {
     console.error(`@softure-ai/mailing: one-click unsubscribe failed: ${errorLogLabel(error)}`);

package/src/options.ts

@@ -1,9 +1,32 @@
 // The options an app passes to `mailing({ ... })` in softure.config.ts, parsed at startup.
 import { z } from "zod";
 import { isMailbox, isSingleAddress } from "./address.js";
-import type { MailProvider, OnUnsubscribedHook } from "./contract.js";
+import type { CampaignRecipientFilter, LegacyUnsubscribe, MailProvider, OnUnsubscribedHook } from "./contract.js";
 
 export const DEFAULT_TIMEOUT_MS = 10_000;
+/** How long a delivery claim may stay open before another sender may take it over (and send again, same key). */
+export const DEFAULT_STALE_CLAIM_MS = 15 * 60_000;
+/**
+ * How old a claim may get before it is "uncertain" and never taken over by itself: its send may have gone out, and
+ * the provider may have forgotten the idempotency key (Resend keeps one for 24 hours), so a retake could mail twice.
+ */
+export const DEFAULT_UNCERTAIN_CLAIM_MS = 23 * 60 * 60_000;
+
+/** Query names the signed link and the page use; a legacy link cannot claim them. */
+const RESERVED_LINK_PARAMS: ReadonlySet<string> = new Set(["r", "status"]);
+const LINK_PARAM = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+
+const legacyUnsubscribeSchema = z.strictObject({
+  params: z
+    .array(z.string().regex(LINK_PARAM, "must be a query name: a letter, then letters, digits, _ or -, at most 32 characters"))
+    .min(1)
+    .max(8)
+    .refine((params) => new Set(params).size === params.length, "must not repeat a name")
+    .refine((params) => params.every((param) => !RESERVED_LINK_PARAMS.has(param)), "must not use r or status: the signed link and the page own them"),
+  verify: z.custom<LegacyUnsubscribe["verify"]>((value) => typeof value === "function", "must be a function"),
+});
+
+const HOUR_MS = 60 * 60_000;
 
 function isMailProvider(value: unknown): value is MailProvider {
   if (typeof value !== "object" || value === null) return false;
@@ -28,7 +51,18 @@ export const mailingOptionsSchema = z.strictObject({
    * `@softure-ai/waitlist/server`, which records the withdrawal in privacy's consent ledger.
    */
   onUnsubscribed: z.custom<OnUnsubscribedHook>((value) => typeof value === "function", "must be a function").optional(),
-});
+  /** Verifies unsubscribe links the app sent before it adopted the module (see `LegacyUnsubscribe`). */
+  legacyUnsubscribe: legacyUnsubscribeSchema.optional(),
+  /** Decides per recipient whether a campaign goes to them, e.g. by consent scope (see `CampaignRecipientFilter`). */
+  filterCampaignRecipient: z.custom<CampaignRecipientFilter>((value) => typeof value === "function", "must be a function").optional(),
+  /** How long a delivery claim may stay open before another sender takes it over. 1 minute to 23 hours. */
+  staleClaimMs: z.number().int().min(60_000).max(23 * HOUR_MS).default(DEFAULT_STALE_CLAIM_MS),
+  /**
+   * How old a claim may get before it is never taken over by itself (`uncertain`); keep it under the provider's
+   * idempotency window. More than `staleClaimMs`, at most 30 days.
+   */
+  uncertainClaimMs: z.number().int().min(60_000).max(30 * 24 * HOUR_MS).default(DEFAULT_UNCERTAIN_CLAIM_MS),
+}).refine((options) => options.uncertainClaimMs > options.staleClaimMs, { message: "must be more than staleClaimMs", path: ["uncertainClaimMs"] });
 
 export type MailingOptionsInput = z.input<typeof mailingOptionsSchema>;
 export type MailingOptions = z.output<typeof mailingOptionsSchema>;

package/src/providers/resend.ts

@@ -21,8 +21,11 @@ export interface ResendOptions {
 /** Resend's name for an idempotency key that another request is still using: retry later. */
 const CONCURRENT_IDEMPOTENT_REQUESTS = "concurrent_idempotent_requests";
 
-/** Statuses below 500 that mean "try again later", not "this mail is refused". */
-const RETRYABLE_CLIENT_STATUSES: ReadonlySet<number> = new Set([408, 429]);
+/** Resend's name for a 429 that is a per-second rate limit; any other 429 is a spent daily or monthly quota. */
+const RATE_LIMIT_EXCEEDED = "rate_limit_exceeded";
+
+/** Statuses that refuse the sender (missing, invalid or restricted key, account not allowed to send). */
+const REFUSED_STATUSES: ReadonlySet<number> = new Set([401, 403]);
 
 /** Sends through Resend's HTTP API. */
 export function resend(options: ResendOptions = {}): MailProvider {
@@ -72,11 +75,12 @@ async function readOutcome(response: Response): Promise<ProviderOutcome> {
     return id === null ? { status: "unavailable", httpStatus: response.status } : { status: "sent", id };
   }
   // Only the error's `name` (an enum) is read: its `message` can echo the address back.
-  const isRetryable =
-    response.status >= 500 ||
-    RETRYABLE_CLIENT_STATUSES.has(response.status) ||
-    (response.status === 409 && readString(payload, "name") === CONCURRENT_IDEMPOTENT_REQUESTS);
-  return { status: isRetryable ? "unavailable" : "rejected", httpStatus: response.status };
+  const name = readString(payload, "name");
+  const httpStatus = response.status;
+  if (REFUSED_STATUSES.has(httpStatus)) return { status: "refused", httpStatus };
+  if (httpStatus === 429) return { status: name === RATE_LIMIT_EXCEEDED ? "unavailable" : "quota_exceeded", httpStatus };
+  const isRetryable = httpStatus >= 500 || httpStatus === 408 || (httpStatus === 409 && name === CONCURRENT_IDEMPOTENT_REQUESTS);
+  return { status: isRetryable ? "unavailable" : "rejected", httpStatus };
 }
 
 function readString(payload: unknown, key: string): string | null {

package/src/schema.ts

@@ -31,6 +31,8 @@ export const deliveries = mailingSchema.table(
     finishedAt: timestamp("finished_at", { withTimezone: true }),
     providerMessageId: text("provider_message_id"),
     reason: text("reason"),
+    /** The provider's HTTP status of the last answer that failed or was released; null when there was none. */
+    providerStatus: integer("provider_status"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
   },
   (table) => [primaryKey({ columns: [table.scope, table.recipientKey] })],

package/src/server/campaigns.ts

@@ -1,19 +1,27 @@
 // Campaigns: one list mail to many recipients through the delivery ledger. The campaign row pins
 // the content (a hash of kind, subject and bodies), so a re-run with the same id sends the rest of
-// the same mail and nothing twice; other content under that id is refused.
+// the same mail and nothing twice; other content under that id is refused. A run stops at the first
+// failure about the sending account (refused key, spent quota), leaving the rest for the next run.
 import { createHash } from "node:crypto";
 import { err, ok, type Result } from "@softure-ai/core";
 import { and, eq, inArray } from "drizzle-orm";
-import type { MailingErrorCode } from "../contract.js";
+import type { CampaignRecipient, MailingErrorCode } from "../contract.js";
 import { campaigns, deliveries } from "../schema.js";
 import { getCampaignProblems, type CampaignContent } from "./campaign-file.js";
-import { deliverOnce, type DeliverOptions, type DeliveryContext, type DeliveryOutcome } from "./deliveries.js";
+import { deliverOnce, type DeliverOptions, type DeliveryContext, type DeliveryOutcome, type HaltingErrorCode } from "./deliveries.js";
+import { getMailingOptions } from "./options.js";
 import { isSuppressed } from "./suppressions.js";
 import { getRecipientKey } from "./unsubscribe-link.js";
 
 /** Rejections the provider answered (the others never left the process). */
 const PROVIDER_REASONS: ReadonlySet<MailingErrorCode> = new Set(["mailing.rejected", "mailing.unavailable"]);
 
+/** Why a run stopped before the end of the list. */
+export interface CampaignHalt {
+  readonly reason: HaltingErrorCode;
+  readonly httpStatus?: number;
+}
+
 /** The campaign id is taken by other content. Give the new content a new id. */
 export type CampaignErrorCode = "mailing.campaign_changed";
 
@@ -29,6 +37,15 @@ export interface CampaignSummary {
   readonly inFlight: number;
   /** The provider was unavailable; the next run tries them again. */
   readonly retryLater: number;
+  /** Skipped by `filterCampaignRecipient`; nothing stored, so a later run sends to them once they qualify. */
+  readonly filtered: number;
+  /** Claimed more than `uncertainClaimMs` ago and never closed: their mail may have gone out. */
+  readonly uncertain: number;
+  /**
+   * Set when the run stopped at a failure about the sending account. The recipient it happened to and every one
+   * after it were left as they were; run again once the account can send.
+   */
+  readonly halted: CampaignHalt | null;
 }
 
 export interface SendCampaignOptions extends DeliverOptions {
@@ -61,7 +78,9 @@ export async function registerCampaign(ctx: DeliveryContext, content: CampaignCo
 
 /**
  * Sends `campaign` to every recipient that has no outcome yet, one at a time. Recipients who
- * unsubscribed are rejected (`mailing.suppressed`) and never retried. Throws on a database failure.
+ * unsubscribed are rejected (`mailing.suppressed`) and never retried; recipients the module's
+ * `filterCampaignRecipient` refuses are skipped. Stops at the first `halted` delivery. Throws on a
+ * database failure and when the filter throws.
  */
 export async function sendCampaign(
   ctx: DeliveryContext,
@@ -73,13 +92,18 @@ export async function sendCampaign(
   const registered = await registerCampaign(ctx, campaign);
   if (!registered.ok) return registered;
 
-  const counts = { sent: 0, done: 0, inFlight: 0, retryLater: 0, rejected: emptyRejections() };
+  const counts: Counts = { sent: 0, done: 0, inFlight: 0, retryLater: 0, filtered: 0, uncertain: 0, rejected: emptyRejections() };
   const seen = new Set<string>();
   const scope = `campaign:${campaign.id}`;
+  const isWanted = createRecipientFilter(ctx, campaign);
   for await (const address of input.recipients) {
     const recipientKey = getRecipientKey(address);
     if (seen.has(recipientKey)) continue;
     seen.add(recipientKey);
+    if (!(await isWanted(address, recipientKey))) {
+      counts.filtered += 1;
+      continue;
+    }
 
     const html = campaign.html === null ? {} : { html: campaign.html };
     const outcome = await deliverOnce(
@@ -89,10 +113,26 @@ export async function sendCampaign(
     );
     countOutcome(counts, outcome);
     onDelivery?.(outcome);
+    if (outcome.status === "halted") {
+      // The rest of the list is not even counted as seen: the summary covers what this run reached.
+      const httpStatus = outcome.httpStatus === undefined ? {} : { httpStatus: outcome.httpStatus };
+      return ok({ recipients: seen.size, ...counts, halted: { reason: outcome.reason, ...httpStatus } });
+    }
     const reachedProvider = outcome.status === "sent" || outcome.status === "retry-later" || (outcome.status === "rejected" && PROVIDER_REASONS.has(outcome.reason));
     if (reachedProvider && pauseMs > 0) await sleep(pauseMs);
   }
-  return ok({ recipients: seen.size, ...counts });
+  return ok({ recipients: seen.size, ...counts, halted: null });
+}
+
+/** `filterCampaignRecipient` bound to the campaign, or "everyone" when the app set none. */
+function createRecipientFilter(ctx: DeliveryContext, campaign: CampaignContent): (address: string, recipientKey: string) => Promise<boolean> {
+  const filter = getMailingOptions(ctx.config).filterCampaignRecipient;
+  if (filter === undefined) return () => Promise.resolve(true);
+  const target = { id: campaign.id, kind: campaign.kind };
+  return (address, recipientKey) => {
+    const recipient: CampaignRecipient = { address, recipientKey, campaign: target };
+    return filter(recipient, ctx);
+  };
 }
 
 export interface CampaignPlan {
@@ -101,16 +141,27 @@ export interface CampaignPlan {
   readonly done: number;
   /** Not closed yet, but unsubscribed: they will be rejected without a send. */
   readonly suppressed: number;
+  /** Not closed yet, but `filterCampaignRecipient` refuses them: they will be skipped. */
+  readonly filtered: number;
+  /**
+   * Claimed more than `uncertainClaimMs` ago and never closed: skipped unless the run retakes uncertain claims
+   * (then they are sent again and counted in `toSend` too).
+   */
+  readonly uncertain: number;
   /** Would be sent now. */
   readonly toSend: number;
   /** The campaign id is stored with other content: a real run would be refused. */
   readonly contentChanged: boolean;
 }
 
-/** What `sendCampaign` would do, without writing or sending anything. Throws on a database failure. */
+/**
+ * What `sendCampaign` would do, without writing or sending anything (the filter runs, and must not write). Throws
+ * on a database failure. `toSend` counts uncertain recipients only with `retakeUncertain`.
+ */
 export async function planCampaign(
   ctx: DeliveryContext,
   input: { readonly campaign: CampaignContent; readonly recipients: Iterable<string> | AsyncIterable<string> },
+  options: Pick<DeliverOptions, "uncertainClaimMs" | "retakeUncertain"> = {},
 ): Promise<CampaignPlan> {
   const { campaign } = input;
   assertCampaign(campaign);
@@ -122,20 +173,35 @@ export async function planCampaign(
     const key = getRecipientKey(address);
     if (!addresses.has(key)) addresses.set(key, address);
   }
+  const uncertainBefore = ctx.clock.now().getTime() - (options.uncertainClaimMs ?? getMailingOptions(ctx.config).uncertainClaimMs);
   const closed = new Set<string>();
+  const uncertainKeys = new Set<string>();
   const keys = [...addresses.keys()];
   for (let start = 0; start < keys.length; start += 1_000) {
     const rows = await ctx.db
-      .select({ recipientKey: deliveries.recipientKey })
+      .select({ recipientKey: deliveries.recipientKey, status: deliveries.status, claimedAt: deliveries.claimedAt })
       .from(deliveries)
-      .where(and(eq(deliveries.scope, `campaign:${campaign.id}`), inArray(deliveries.status, ["sent", "rejected"]), inArray(deliveries.recipientKey, keys.slice(start, start + 1_000))));
-    rows.forEach((row) => closed.add(row.recipientKey));
+      .where(and(eq(deliveries.scope, `campaign:${campaign.id}`), inArray(deliveries.status, ["sent", "rejected", "claimed"]), inArray(deliveries.recipientKey, keys.slice(start, start + 1_000))));
+    for (const row of rows) {
+      if (row.status !== "claimed") closed.add(row.recipientKey);
+      else if (row.claimedAt.getTime() < uncertainBefore) uncertainKeys.add(row.recipientKey);
+    }
   }
+  const isWanted = createRecipientFilter(ctx, campaign);
   let suppressed = 0;
+  let filtered = 0;
+  let toSend = 0;
+  let uncertain = 0;
   for (const [key, address] of addresses) {
-    if (!closed.has(key) && (await isSuppressed(ctx, address))) suppressed += 1;
+    if (closed.has(key)) continue;
+    if (!(await isWanted(address, key))) filtered += 1;
+    else if (await isSuppressed(ctx, address)) suppressed += 1;
+    else if (uncertainKeys.has(key)) {
+      uncertain += 1;
+      if (options.retakeUncertain === true) toSend += 1;
+    } else toSend += 1;
   }
-  return { recipients: addresses.size, done: closed.size, suppressed, toSend: addresses.size - closed.size - suppressed, contentChanged };
+  return { recipients: addresses.size, done: closed.size, suppressed, filtered, uncertain, toSend, contentChanged };
 }
 
 function assertCampaign(content: CampaignContent): void {
@@ -144,13 +210,20 @@ function assertCampaign(content: CampaignContent): void {
 }
 
 function emptyRejections(): Record<MailingErrorCode, number> {
-  return { "mailing.invalid_input": 0, "mailing.rejected": 0, "mailing.unavailable": 0, "mailing.suppressed": 0 };
+  return { "mailing.invalid_input": 0, "mailing.rejected": 0, "mailing.unavailable": 0, "mailing.suppressed": 0, "mailing.provider_refused": 0, "mailing.quota_exceeded": 0 };
+}
+
+interface Counts {
+  sent: number;
+  done: number;
+  inFlight: number;
+  retryLater: number;
+  filtered: number;
+  uncertain: number;
+  rejected: Record<MailingErrorCode, number>;
 }
 
-function countOutcome(
-  counts: { sent: number; done: number; inFlight: number; retryLater: number; rejected: Record<MailingErrorCode, number> },
-  outcome: DeliveryOutcome,
-): void {
+function countOutcome(counts: Counts, outcome: DeliveryOutcome): void {
   switch (outcome.status) {
     case "sent":
       counts.sent += 1;
@@ -165,8 +238,13 @@ function countOutcome(
       counts.inFlight += 1;
       return;
     case "retry-later":
+    case "halted":
+      // A halted recipient is left for the next run, like one the provider could not take now.
       counts.retryLater += 1;
       return;
+    case "uncertain":
+      counts.uncertain += 1;
+      return;
   }
 }
 

package/src/server/deliveries.ts

@@ -1,20 +1,24 @@
 // The delivery ledger (mailing.deliveries): a mail goes out at most once per scope and recipient.
 // The sender claims the row in one conditional upsert before it calls the provider, then closes it
 // with one outcome. A claim left behind by a crash is taken over once it is stale, and the mail is
-// sent again with the same idempotency key, so the provider folds it into the first send.
+// sent again with the same idempotency key, so the provider folds it into the first send. A claim
+// older than the provider keeps that key is "uncertain": it is taken over only when the operator
+// says so. A failure about the sending account (refused key, spent quota) closes nothing: the
+// claim goes back, attempt included, so fixing the account and re-running loses no recipient.
 import { type ModuleContext } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
-import { and, eq, lt, or, sql } from "drizzle-orm";
+import { and, eq, gte, lt, or, sql, type SQL } from "drizzle-orm";
 import { isMailKind } from "../address.js";
-import { TRANSACTIONAL_KIND, type MailingErrorCode, type OutgoingMail } from "../contract.js";
+import { HALTING_ERROR_CODES, TRANSACTIONAL_KIND, type MailingErrorCode, type OutgoingMail } from "../contract.js";
+import { DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS } from "../options.js";
 import { deliveries } from "../schema.js";
+import { getMailingOptions } from "./options.js";
 import { sendMail } from "./send-mail.js";
 import { getRecipientKey } from "./unsubscribe-link.js";
 
 export type DeliveryContext = ModuleContext<Queryable>;
 
-/** How long a claim may stay open before another sender may take it over. */
-export const DEFAULT_STALE_CLAIM_MS = 15 * 60_000;
+export { DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS };
 /** Claims a delivery gets before `mailing.unavailable` becomes its final outcome. */
 export const DEFAULT_MAX_ATTEMPTS = 5;
 
@@ -35,21 +39,42 @@ export interface Delivery {
 }
 
 export interface DeliverOptions {
+  /** Default: the module's `staleClaimMs` (15 minutes). */
   readonly staleClaimMs?: number;
+  /** Default: the module's `uncertainClaimMs` (23 hours). */
+  readonly uncertainClaimMs?: number;
+  /**
+   * Takes over uncertain claims too (older than `uncertainClaimMs`), accepting that their mail may arrive twice.
+   * An operator's decision, e.g. `softure-mail campaign --resend-uncertain`. Default false.
+   */
+  readonly retakeUncertain?: boolean;
   readonly maxAttempts?: number;
 }
 
+/** The codes that stop a run: the sending account, not the mail, is the problem. */
+export type HaltingErrorCode = "mailing.provider_refused" | "mailing.quota_exceeded";
+
 export type DeliveryOutcome =
   /** Sent now; `id` is the provider's message id. */
   | { readonly status: "sent"; readonly id: string }
   /** Refused now, for good (suppressed, rejected, invalid, or unavailable too many times). */
-  | { readonly status: "rejected"; readonly reason: MailingErrorCode }
+  | { readonly status: "rejected"; readonly reason: MailingErrorCode; readonly httpStatus?: number }
   /** An earlier run already closed this delivery; nothing was sent. */
   | { readonly status: "done"; readonly outcome: "sent" | "rejected" }
   /** Another sender holds a fresh claim; nothing was sent. */
   | { readonly status: "in-flight" }
+  /**
+   * A claim older than `uncertainClaimMs` is open: its mail may have gone out. Nothing was sent; only
+   * `retakeUncertain` sends it again.
+   */
+  | { readonly status: "uncertain" }
   /** The provider was unavailable; the claim is released for a later run. */
-  | { readonly status: "retry-later" };
+  | { readonly status: "retry-later"; readonly httpStatus?: number }
+  /**
+   * The provider refused the account or its quota is spent: the claim is released, its attempt given back. Stop
+   * sending (every other mail fails the same way) and run again once the account can send.
+   */
+  | { readonly status: "halted"; readonly reason: HaltingErrorCode; readonly httpStatus?: number };
 
 /**
  * Sends `delivery.mail` unless the ledger already has an outcome (or a fresh claim) for its scope
@@ -58,27 +83,55 @@ export type DeliveryOutcome =
  * malformed scope or kind, and when `sendMail` throws.
  */
 export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryOutcome> {
-  const { staleClaimMs = DEFAULT_STALE_CLAIM_MS, maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
+  const windows = resolveClaimWindows(ctx, options);
+  const { maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
   const kind = delivery.mail.kind ?? TRANSACTIONAL_KIND;
   assertDelivery(delivery, kind);
 
   const recipientKey = getRecipientKey(delivery.mail.to);
   const key = { scope: delivery.scope, recipientKey };
-  const attempt = await claimDelivery(ctx, { ...key, kind, campaignId: delivery.campaignId ?? null, staleClaimMs });
-  if (attempt === null) return readClosedDelivery(ctx, key);
+  const attempt = await claimDelivery(ctx, { ...key, kind, campaignId: delivery.campaignId ?? null, ...windows });
+  if (attempt === null) return readClosedDelivery(ctx, key, windows.uncertainClaimMs);
 
   const result = await sendMail(ctx, delivery.mail, { idempotencyKey: `${delivery.scope}:${recipientKey}` });
   const fence = { ...key, attempt };
   if (result.ok) {
-    await closeDelivery(ctx, fence, { status: "sent", providerMessageId: result.value.id, reason: null });
+    await closeDelivery(ctx, fence, { status: "sent", providerMessageId: result.value.id, reason: null, providerStatus: null });
     return { status: "sent", id: result.value.id };
   }
+  const providerStatus = result.httpStatus ?? null;
+  const httpStatus = result.httpStatus === undefined ? {} : { httpStatus: result.httpStatus };
+  if (isHaltingCode(result.error)) {
+    await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: true });
+    return { status: "halted", reason: result.error, ...httpStatus };
+  }
   if (result.error === "mailing.unavailable" && attempt < maxAttempts) {
-    await releaseDelivery(ctx, fence);
-    return { status: "retry-later" };
+    await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: false });
+    return { status: "retry-later", ...httpStatus };
+  }
+  await closeDelivery(ctx, fence, { status: "rejected", providerMessageId: null, reason: result.error, providerStatus });
+  return { status: "rejected", reason: result.error, ...httpStatus };
+}
+
+function isHaltingCode(code: MailingErrorCode): code is HaltingErrorCode {
+  return HALTING_ERROR_CODES.has(code);
+}
+
+interface ClaimWindows {
+  readonly staleClaimMs: number;
+  readonly uncertainClaimMs: number;
+  readonly retakeUncertain: boolean;
+}
+
+/** The claim windows: the call's options, else the module's, else the defaults. */
+function resolveClaimWindows(ctx: DeliveryContext, options: DeliverOptions): ClaimWindows {
+  const configured = getMailingOptions(ctx.config);
+  const staleClaimMs = options.staleClaimMs ?? configured.staleClaimMs;
+  const uncertainClaimMs = options.uncertainClaimMs ?? configured.uncertainClaimMs;
+  if (uncertainClaimMs <= staleClaimMs) {
+    throw new Error(`@softure-ai/mailing: uncertainClaimMs (${String(uncertainClaimMs)}) must be more than staleClaimMs (${String(staleClaimMs)})`);
   }
-  await closeDelivery(ctx, fence, { status: "rejected", providerMessageId: null, reason: result.error });
-  return { status: "rejected", reason: result.error };
+  return { staleClaimMs, uncertainClaimMs, retakeUncertain: options.retakeUncertain ?? false };
 }
 
 function assertDelivery(delivery: Delivery, kind: string): void {
@@ -100,31 +153,34 @@ interface DeliveryKey {
 
 /**
  * Takes the row in one statement: a new row, a `pending` one, or a claim older than
- * `staleClaimMs`. Resolves with the attempt number that fences the outcome, or `null` when the row
- * is closed or claimed by someone else.
+ * `staleClaimMs` (and, unless `retakeUncertain`, not older than `uncertainClaimMs`). Resolves with
+ * the attempt number that fences the outcome, or `null` when the row is closed, claimed by someone
+ * else, or uncertain.
  */
-async function claimDelivery(
-  ctx: DeliveryContext,
-  claim: DeliveryKey & { readonly kind: string; readonly campaignId: string | null; readonly staleClaimMs: number },
-): Promise<number | null> {
+async function claimDelivery(ctx: DeliveryContext, claim: DeliveryKey & ClaimWindows & { readonly kind: string; readonly campaignId: string | null }): Promise<number | null> {
   const now = ctx.clock.now();
   const staleBefore = new Date(now.getTime() - claim.staleClaimMs);
+  const uncertainBefore = new Date(now.getTime() - claim.uncertainClaimMs);
+  const isStale: SQL | undefined = claim.retakeUncertain
+    ? lt(deliveries.claimedAt, staleBefore)
+    : and(lt(deliveries.claimedAt, staleBefore), gte(deliveries.claimedAt, uncertainBefore));
   const rows = await ctx.db
     .insert(deliveries)
     .values({ scope: claim.scope, recipientKey: claim.recipientKey, kind: claim.kind, campaignId: claim.campaignId, status: "claimed", attempts: 1, claimedAt: now, createdAt: now })
     .onConflictDoUpdate({
       target: [deliveries.scope, deliveries.recipientKey],
       set: { status: "claimed", attempts: sql`${deliveries.attempts} + 1`, claimedAt: now },
-      setWhere: or(eq(deliveries.status, "pending"), and(eq(deliveries.status, "claimed"), lt(deliveries.claimedAt, staleBefore))),
+      setWhere: or(eq(deliveries.status, "pending"), and(eq(deliveries.status, "claimed"), isStale)),
     })
     .returning();
   return rows[0]?.attempts ?? null;
 }
 
-async function readClosedDelivery(ctx: DeliveryContext, key: DeliveryKey): Promise<DeliveryOutcome> {
-  const rows = await ctx.db.select({ status: deliveries.status }).from(deliveries).where(matchKey(key)).limit(1);
-  const status = rows[0]?.status;
-  if (status === "sent" || status === "rejected") return { status: "done", outcome: status };
+async function readClosedDelivery(ctx: DeliveryContext, key: DeliveryKey, uncertainClaimMs: number): Promise<DeliveryOutcome> {
+  const rows = await ctx.db.select({ status: deliveries.status, claimedAt: deliveries.claimedAt }).from(deliveries).where(matchKey(key)).limit(1);
+  const row = rows[0];
+  if (row?.status === "sent" || row?.status === "rejected") return { status: "done", outcome: row.status };
+  if (row?.status === "claimed" && row.claimedAt.getTime() < ctx.clock.now().getTime() - uncertainClaimMs) return { status: "uncertain" };
   // A fresh claim; `pending` only between another sender's release and this read.
   return { status: "in-flight" };
 }
@@ -135,7 +191,7 @@ type Fence = DeliveryKey & { readonly attempt: number };
 async function closeDelivery(
   ctx: DeliveryContext,
   fence: Fence,
-  outcome: { readonly status: "sent" | "rejected"; readonly providerMessageId: string | null; readonly reason: string | null },
+  outcome: { readonly status: "sent" | "rejected"; readonly providerMessageId: string | null; readonly reason: string | null; readonly providerStatus: number | null },
 ): Promise<void> {
   await ctx.db
     .update(deliveries)
@@ -143,10 +199,14 @@ async function closeDelivery(
     .where(and(matchKey(fence), eq(deliveries.status, "claimed"), eq(deliveries.attempts, fence.attempt)));
 }
 
-async function releaseDelivery(ctx: DeliveryContext, fence: Fence): Promise<void> {
+/**
+ * Puts the claim back for a later run. A halt gives its attempt back: the account's failure says
+ * nothing about this mail, so it must not bring the delivery closer to `maxAttempts`.
+ */
+async function releaseDelivery(ctx: DeliveryContext, fence: Fence, release: { readonly providerStatus: number | null; readonly giveAttemptBack: boolean }): Promise<void> {
   await ctx.db
     .update(deliveries)
-    .set({ status: "pending" })
+    .set({ status: "pending", providerStatus: release.providerStatus, ...(release.giveAttemptBack ? { attempts: fence.attempt - 1 } : {}) })
     .where(and(matchKey(fence), eq(deliveries.status, "claimed"), eq(deliveries.attempts, fence.attempt)));
 }
 

package/src/server/index.ts

@@ -7,6 +7,7 @@ export {
   registerCampaign,
   sendCampaign,
   type CampaignErrorCode,
+  type CampaignHalt,
   type CampaignPlan,
   type CampaignSummary,
   type SendCampaignOptions,
@@ -14,11 +15,13 @@ export {
 export {
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_STALE_CLAIM_MS,
+  DEFAULT_UNCERTAIN_CLAIM_MS,
   deliverOnce,
   type DeliverOptions,
   type Delivery,
   type DeliveryContext,
   type DeliveryOutcome,
+  type HaltingErrorCode,
 } from "./deliveries.js";
 export {
   checkSenderDns,
@@ -39,6 +42,9 @@ export { isSuppressed, liftSuppression, suppressRecipient, unsubscribe, type Sup
 export {
   buildUnsubscribeLinks,
   getRecipientKey,
+  getUnsubscribeLinkParams,
+  MAX_LEGACY_VALUE_LENGTH,
+  readUnsubscribeLink,
   MIN_UNSUBSCRIBE_SECRET_LENGTH,
   readUnsubscribeSecrets,
   readUnsubscribeToken,
@@ -49,6 +55,8 @@ export {
   UNSUBSCRIBE_SECRET_ENV,
   verifyUnsubscribeToken,
   type Env,
+  type LinkParams,
+  type UnsubscribeLink,
   type UnsubscribeLinks,
   type UnsubscribeSecrets,
   type UnsubscribeToken,