@softure-ai/mailing 0.1.5 → 0.1.7

package/src/contract.ts

@@ -1,6 +1,6 @@
 // Result types, error codes and the provider contract of the mailing module. No user-facing copy
 // here: the UI translates codes through `messages` (docs/02-module-standard.md §6).
-import type { ModuleContext, Result } from "@softure-ai/core";
+import type { Err, ModuleContext, Ok } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 
 export type MailingErrorCode =
@@ -11,7 +11,17 @@ export type MailingErrorCode =
   /** The provider could not be reached or did not answer in time. Retry later, with the same idempotency key. */
   | "mailing.unavailable"
   /** A list mail to a recipient who unsubscribed. Nothing was sent; do not retry. */
-  | "mailing.suppressed";
+  | "mailing.suppressed"
+  /**
+   * The provider refuses the sender, not the mail: a wrong or revoked API key, a suspended or restricted account
+   * (HTTP 401/403). Every other mail would fail the same way: stop sending, fix the account, then retry.
+   */
+  | "mailing.provider_refused"
+  /** The account's sending quota is spent (HTTP 429 that is not a rate limit). Stop sending; retry when it renews. */
+  | "mailing.quota_exceeded";
+
+/** The codes that are about the sending account, not the mail: a run of sends stops at the first one. */
+export const HALTING_ERROR_CODES: ReadonlySet<MailingErrorCode> = new Set(["mailing.provider_refused", "mailing.quota_exceeded"]);
 
 /** Why an unsubscribe link was refused: missing, malformed, or not signed by a current secret. */
 export type UnsubscribeErrorCode = "mailing.invalid_link";
@@ -36,6 +46,32 @@ export interface UnsubscribeEvent {
  */
 export type OnUnsubscribedHook = (event: UnsubscribeEvent, ctx: ModuleContext<Queryable>) => Promise<void>;
 
+/** What `filterCampaignRecipient` receives for each recipient of a campaign. */
+export interface CampaignRecipient {
+  readonly address: string;
+  /** The recipient key of the address (`getRecipientKey`). */
+  readonly recipientKey: string;
+  readonly campaign: { readonly id: string; readonly kind: string };
+}
+
+/**
+ * Decides whether a campaign goes to a recipient, e.g. by the consent scope the app stored for the address. A
+ * recipient it refuses is skipped before the ledger is touched, so a later re-run sends to them once they qualify.
+ * A throw stops the campaign, like a database failure. Set in `mailing({ filterCampaignRecipient })`.
+ */
+export type CampaignRecipientFilter = (recipient: CampaignRecipient, ctx: ModuleContext<Queryable>) => Promise<boolean>;
+
+/**
+ * Unsubscribe links an app sent before it adopted the module, in its own scheme. `params` are the query names of
+ * such a link; `verify` receives their values (all present once, each at most 512 characters) and returns the
+ * recipient's address when the link is genuine, else `null`. It must check the link's signature itself: whatever
+ * address it returns is unsubscribed. A throw reads as a failure (the person may try again), not as a bad link.
+ */
+export interface LegacyUnsubscribe {
+  readonly params: readonly string[];
+  readonly verify: (values: Readonly<Record<string, string>>, ctx: ModuleContext<Queryable>) => Promise<string | null>;
+}
+
 /** One mail to one recipient. A mail to a list is a loop over recipients, never a list in `to`. */
 export interface OutgoingMail {
   /** Exactly one address: `ada@example.com`. */
@@ -77,7 +113,10 @@ export interface SentMail {
   readonly provider: string;
 }
 
-export type SendMailResult = Result<SentMail, MailingErrorCode>;
+/** A failed send: the code, and the provider's HTTP status when it answered with one. */
+export type SendMailFailure = Err<MailingErrorCode> & { readonly httpStatus?: number };
+
+export type SendMailResult = Ok<SentMail> | SendMailFailure;
 
 /** What a provider receives: a validated mail with the sender and reply-to from the configuration. */
 export interface ProviderMessage {
@@ -91,11 +130,15 @@ export interface ProviderMessage {
   readonly idempotencyKey: string | null;
 }
 
-/** What a provider answers. `httpStatus` is logged; the mail never is. */
+/**
+ * What a provider answers. `httpStatus` is logged and returned with the failure; the mail never is. `refused` is the
+ * provider refusing the sender (key, account), `quota_exceeded` a spent sending quota; `rejected` is about this mail.
+ */
 export type ProviderOutcome =
   | { readonly status: "sent"; readonly id: string }
-  | { readonly status: "rejected"; readonly httpStatus?: number }
-  | { readonly status: "unavailable"; readonly httpStatus?: number };
+  | { readonly status: ProviderFailureStatus; readonly httpStatus?: number };
+
+export type ProviderFailureStatus = "rejected" | "unavailable" | "refused" | "quota_exceeded";
 
 /**
  * A mail service adapter. `send` should resolve with an outcome for every failure it knows; a

package/src/index.ts

@@ -17,7 +17,7 @@ export const MODULE_ID = "mailing";
 export const mailing = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.5",
+    version: "0.1.7",
     dependsOn: {},
     dbSchema: "mailing",
     tables: ["suppressions", "campaigns", "deliveries"],
@@ -64,14 +64,19 @@ export {
   MAX_SUBJECT_LENGTH,
   RESERVED_HEADERS,
 } from "./address.js";
-export { TRANSACTIONAL_KIND } from "./contract.js";
+export { HALTING_ERROR_CODES, TRANSACTIONAL_KIND } from "./contract.js";
 export type {
+  CampaignRecipient,
+  CampaignRecipientFilter,
+  LegacyUnsubscribe,
   MailingErrorCode,
   MailProvider,
   OnUnsubscribedHook,
   OutgoingMail,
+  ProviderFailureStatus,
   ProviderMessage,
   ProviderOutcome,
+  SendMailFailure,
   SendMailOptions,
   SendMailResult,
   SentMail,
@@ -80,6 +85,6 @@ export type {
   UnsubscribeEvent,
 } from "./contract.js";
 export { getMailingErrorMessage, mailingMessages, type MailingMessages } from "./messages/index.js";
-export { DEFAULT_TIMEOUT_MS, type MailingOptions, type MailingOptionsInput } from "./options.js";
+export { DEFAULT_STALE_CLAIM_MS, DEFAULT_TIMEOUT_MS, DEFAULT_UNCERTAIN_CLAIM_MS, type MailingOptions, type MailingOptionsInput } from "./options.js";
 export { resend, RESEND_API_KEY_ENV, RESEND_ENDPOINT, type ResendOptions } from "./providers/resend.js";
 export { campaigns, deliveries, mailingSchema, suppressions, type DeliveryStatus } from "./schema.js";

package/src/messages/en.ts

@@ -5,6 +5,8 @@ export const en = {
       rejected: "The mail service refused this message.",
       unavailable: "The mail service is not answering. Try again in a moment.",
       suppressed: "This address unsubscribed from these emails, so nothing was sent.",
+      provider_refused: "The mail service refused our account, so nothing was sent. We need to fix it on our side.",
+      quota_exceeded: "We reached our sending limit for now. Try again later.",
     },
   },
   footer: {

package/src/messages/pl.ts

@@ -8,6 +8,8 @@ export const pl: typeof en = {
       rejected: "Usługa pocztowa odrzuciła tę wiadomość.",
       unavailable: "Usługa pocztowa nie odpowiada. Spróbuj ponownie za chwilę.",
       suppressed: "Ten adres wypisał się z takich wiadomości, więc nic nie wysłano.",
+      provider_refused: "Usługa pocztowa odrzuciła nasze konto, więc nic nie wysłano. Musimy to naprawić po naszej stronie.",
+      quota_exceeded: "Wyczerpaliśmy na razie limit wysyłki. Spróbuj ponownie później.",
     },
   },
   footer: {

package/src/next/actions.ts

@@ -9,16 +9,16 @@ import { getSoftureConfig } from "@softure-ai/core/next";
 import { redirect } from "next/navigation";
 import { getMailingRoutes } from "../server/options.js";
 import { unsubscribe } from "../server/suppressions.js";
-import { RECIPIENT_PARAM, readUnsubscribeToken, SIGNATURE_PARAM } from "../server/unsubscribe-link.js";
+import { getUnsubscribeLinkParams, readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { getMailingContext } from "./context.js";
 import { UNSUBSCRIBE_STATUS_PARAM, type UnsubscribeStatus } from "./params.js";
 
 export async function unsubscribeAction(formData: FormData): Promise<void> {
   const config = getSoftureConfig();
-  const token = readUnsubscribeToken(formData);
+  const link = readUnsubscribeLink(formData, config);
   let status: UnsubscribeStatus;
   try {
-    const result = await unsubscribe(await getMailingContext(config), token, "page");
+    const result = await unsubscribe(await getMailingContext(config), link, "page");
     status = result.ok ? "done" : "invalid";
   } catch (error) {
     // The label names the kind of failure, never its text: that can carry the link's values.
@@ -26,10 +26,9 @@ export async function unsubscribeAction(formData: FormData): Promise<void> {
     status = "failed";
   }
   const query = new URLSearchParams({ [UNSUBSCRIBE_STATUS_PARAM]: status });
-  if (status === "failed" && token !== null) {
+  if (status === "failed" && link !== null) {
     // The form comes back with the same link, so the person can try again.
-    query.set(RECIPIENT_PARAM, token.recipientKey);
-    query.set(SIGNATURE_PARAM, token.signature);
+    for (const [name, value] of Object.entries(getUnsubscribeLinkParams(link))) query.set(name, value);
   }
   redirect(`${getMailingRoutes(config).unsubscribe}?${query.toString()}`);
 }

package/src/next/context.ts

@@ -2,7 +2,7 @@
 // handle and the wall clock.
 import { systemClock, type SoftureConfig } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
-import { getSharedDatabase } from "@softure-ai/db";
+import { getConfiguredDatabase } from "@softure-ai/db";
 import type { SuppressionContext } from "../server/suppressions.js";
 
 export async function getMailingContext(config: SoftureConfig = getSoftureConfig()): Promise<SuppressionContext> {
@@ -10,6 +10,6 @@ export async function getMailingContext(config: SoftureConfig = getSoftureConfig
     // Unreachable for a validated config: the module has a database schema.
     throw new Error("@softure-ai/mailing: softure.config.ts has no database; mailing needs one");
   }
-  const { db } = await getSharedDatabase(config.database.url);
+  const { db } = await getConfiguredDatabase(config.database);
   return { db, clock: systemClock, config };
 }

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;
   }
 }