@softure-ai/mailing 0.0.0-stage → 0.1.6

package/src/next/next-modules.d.ts

@@ -0,0 +1,12 @@
+// Next.js has no `exports` map, so NodeNext resolution (tsconfig.base.json) only finds
+// `next/navigation.js` and `next/headers.js`. The code must still import the bare specifiers:
+// Next's bundler aliases them per runtime, and the `.js` form bypasses the alias (measured:
+// `next build` failed to collect a route handler importing `next/navigation.js`, MODULE_UNPARSABLE
+// on the vendored app-router context). These declarations give the bare specifiers their types.
+declare module "next/navigation" {
+  export * from "next/navigation.js";
+}
+
+declare module "next/headers" {
+  export * from "next/headers.js";
+}

package/src/next/pages.tsx

@@ -0,0 +1,69 @@
+// The unsubscribe page, ready to mount with one line:
+// `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.
+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 { unsubscribeAction } from "./actions.js";
+import { getMailingMessages } from "./messages.js";
+import { UNSUBSCRIBE_STATUS_PARAM } from "./params.js";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export interface UnsubscribePageProps {
+  readonly searchParams?: SearchParams;
+}
+
+const LAYOUT_CLASS = "sft:mx-auto sft:box-border sft:w-full sft:sm:max-w-md sft:px-4 sft:py-4";
+const FORM_CLASS = "sft:flex sft:flex-col sft:gap-3 sft:font-sans";
+
+function readParam(params: Record<string, string | string[] | undefined>, name: string): string | undefined {
+  const value = params[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+/**
+ * The link's token stays out of other sites' Referer headers; `same-origin` (not `no-referrer`)
+ * keeps the Origin header Next checks on server actions.
+ */
+function UnsubscribeLayout({ title, lead, children }: { title: string; lead: string; children?: ReactNode }) {
+  return (
+    <main className={LAYOUT_CLASS}>
+      <meta name="referrer" content="same-origin" />
+      <Card title={title} subtitle={lead}>
+        {children}
+      </Card>
+    </main>
+  );
+}
+
+export async function UnsubscribePage({ searchParams }: UnsubscribePageProps) {
+  const config = getSoftureConfig();
+  const messages = getMailingMessages(config).unsubscribe;
+  const params = (await searchParams) ?? {};
+  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 === "") {
+    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} />
+        <FormError message={status === "failed" ? messages.failed : undefined} />
+        <div>
+          <Button type="submit" variant="primary">
+            {messages.submit}
+          </Button>
+        </div>
+      </form>
+    </UnsubscribeLayout>
+  );
+}

package/src/next/params.ts

@@ -0,0 +1,6 @@
+// The query parameter the unsubscribe page and its action pass between each other.
+
+/** Set by the action after a submit: `done`, `invalid` or `failed`. */
+export const UNSUBSCRIBE_STATUS_PARAM = "status";
+
+export type UnsubscribeStatus = "done" | "invalid" | "failed";

package/src/next/route.ts

@@ -0,0 +1,45 @@
+// The RFC 8058 one-click route. Mount both handlers with a rename in
+// app/api/mailing/unsubscribe/route.ts:
+// `export { postUnsubscribeRoute as POST, getUnsubscribeRoute as GET } from "@softure-ai/mailing/next"`.
+//
+// Mail clients (Gmail, Outlook, Apple Mail) POST here from their own servers: no cookies, no
+// server action id, a foreign Origin. That is why this is a route handler and not an action. It
+// needs no session and must stay outside any auth guard. There is no per-IP rate limit on
+// purpose: a few provider addresses act for millions of people, so a bucket would refuse real
+// unsubscribes. The link is checked by shape and signature before the database is touched, and
+// the only write is an idempotent insert.
+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 { getMailingContext } from "./context.js";
+
+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.
+ */
+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");
+    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)}`);
+    return new Response(null, { status: 500, headers: NO_STORE });
+  }
+}
+
+/**
+ * A client without RFC 8058 opens the header's URL in a browser: send it to the page with the
+ * same link (303, so nothing changes on GET). A 405 would also put the token in access logs that
+ * record failed requests.
+ */
+export function getUnsubscribeRoute(request: Request): Response {
+  const { search } = new URL(request.url);
+  return new Response(null, { status: 303, headers: { ...NO_STORE, location: `${getMailingRoutes(getSoftureConfig()).unsubscribe}${search}` } });
+}

package/src/next/send-mail.ts

@@ -0,0 +1,15 @@
+// `sendMail` on the app's registered configuration, for server actions and route handlers. List
+// mail also gets the shared database handle (its suppression check); transactional mail never
+// touches the database.
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { TRANSACTIONAL_KIND, type OutgoingMail, type SendMailOptions, type SendMailResult } from "../contract.js";
+import { sendMail as sendMailWithContext } from "../server/send-mail.js";
+import { getMailingContext } from "./context.js";
+
+/** Sends one mail with the registered config; see `sendMail` in `@softure-ai/mailing/server`. */
+export async function sendMail(mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
+  const config = getSoftureConfig();
+  if ((mail.kind ?? TRANSACTIONAL_KIND) === TRANSACTIONAL_KIND) return sendMailWithContext({ config }, mail, options);
+  const { db } = await getMailingContext(config);
+  return sendMailWithContext({ config, db }, mail, options);
+}

package/src/options.ts

@@ -0,0 +1,34 @@
+// 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";
+
+export const DEFAULT_TIMEOUT_MS = 10_000;
+
+function isMailProvider(value: unknown): value is MailProvider {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { name?: unknown; send?: unknown };
+  return typeof candidate.name === "string" && candidate.name !== "" && typeof candidate.send === "function";
+}
+
+export const mailingOptionsSchema = z.strictObject({
+  /**
+   * The sender of every mail: `hello@example.com` or `Plan <hello@example.com>`. It must be on a
+   * domain the provider signs (DKIM), or DMARC rejects the mail.
+   */
+  from: z.string().trim().refine(isMailbox, "must be an address or Name <address>, e.g. Plan <hello@example.com>"),
+  /** Where replies go; may sit on another domain than `from` (DMARC does not check it). */
+  replyTo: z.string().trim().refine(isSingleAddress, "must be one address, e.g. support@example.com").optional(),
+  /** The adapter that delivers mail: `resend()`, or `fakeMailProvider()` from `/testing`. */
+  provider: z.custom<MailProvider>(isMailProvider, "must be a mail provider such as resend()"),
+  /** How long one send may take before it reads as `mailing.unavailable`. */
+  timeoutMs: z.number().int().min(1_000).max(60_000).default(DEFAULT_TIMEOUT_MS),
+  /**
+   * Reacts to an unsubscribe in its transaction, e.g. `withdrawWaitlistConsents` of
+   * `@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(),
+});
+
+export type MailingOptionsInput = z.input<typeof mailingOptionsSchema>;
+export type MailingOptions = z.output<typeof mailingOptionsSchema>;

package/src/providers/resend.ts

@@ -0,0 +1,86 @@
+// The Resend adapter (https://resend.com/docs/api-reference/emails/send-email). Ported from
+// FIRE_TRACKER `src/lib/mail.ts`, where the sender, reply-to and timeout were constants; here they
+// come from the module options and `sendMail` owns validation, the timeout and the log line.
+import type { MailProvider, ProviderMessage, ProviderOutcome } from "../contract.js";
+
+export const RESEND_ENDPOINT = "https://api.resend.com/emails";
+export const RESEND_API_KEY_ENV = "RESEND_API_KEY";
+
+export interface ResendOptions {
+  /**
+   * The API key. Default: `process.env.RESEND_API_KEY`, read on every send, so the configuration
+   * loads at build time without the secret.
+   */
+  readonly apiKey?: string;
+  /** Default: Resend's `POST /emails`. For a proxy or a test server. */
+  readonly endpoint?: string;
+  /** Injected in tests; default: the global `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+
+/** 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]);
+
+/** Sends through Resend's HTTP API. */
+export function resend(options: ResendOptions = {}): MailProvider {
+  const endpoint = options.endpoint ?? RESEND_ENDPOINT;
+  return {
+    name: "resend",
+    send: async (message, { signal }) => {
+      const apiKey = (options.apiKey ?? process.env[RESEND_API_KEY_ENV] ?? "").trim();
+      if (apiKey === "") {
+        // A deployment without the key cannot send anything until it is set; never a caller error.
+        console.error(`mailing: resend has no API key; set ${RESEND_API_KEY_ENV} or pass resend({ apiKey })`);
+        return { status: "unavailable" };
+      }
+      const fetchImpl = options.fetch ?? fetch;
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+          ...(message.idempotencyKey === null ? {} : { "Idempotency-Key": message.idempotencyKey }),
+        },
+        body: JSON.stringify(toResendBody(message)),
+        signal,
+        cache: "no-store",
+      });
+      return readOutcome(response);
+    },
+  };
+}
+
+function toResendBody(message: ProviderMessage): Record<string, unknown> {
+  return {
+    from: message.from,
+    to: [message.to],
+    subject: message.subject,
+    text: message.text,
+    ...(message.html === null ? {} : { html: message.html }),
+    ...(message.replyTo === null ? {} : { reply_to: message.replyTo }),
+    ...(Object.keys(message.headers).length === 0 ? {} : { headers: message.headers }),
+  };
+}
+
+async function readOutcome(response: Response): Promise<ProviderOutcome> {
+  const payload: unknown = await response.json().catch(() => null);
+  if (response.ok) {
+    const id = readString(payload, "id");
+    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 };
+}
+
+function readString(payload: unknown, key: string): string | null {
+  if (typeof payload !== "object" || payload === null || !Object.hasOwn(payload, key)) return null;
+  const value: unknown = (payload as Record<string, unknown>)[key];
+  return typeof value === "string" && value !== "" ? value : null;
+}

package/src/schema.ts

@@ -0,0 +1,40 @@
+// Drizzle view of the module's tables (migrations/). The migrations are the source of truth; this
+// file only types the queries.
+import { integer, pgSchema, primaryKey, text, timestamp } from "drizzle-orm/pg-core";
+
+export const mailingSchema = pgSchema("mailing");
+
+export const suppressions = mailingSchema.table("suppressions", {
+  recipientKey: text("recipient_key").primaryKey(),
+  source: text("source").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
+
+export const campaigns = mailingSchema.table("campaigns", {
+  id: text("id").primaryKey(),
+  kind: text("kind").notNull(),
+  subject: text("subject").notNull(),
+  contentHash: text("content_hash").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
+
+export const deliveries = mailingSchema.table(
+  "deliveries",
+  {
+    scope: text("scope").notNull(),
+    recipientKey: text("recipient_key").notNull(),
+    kind: text("kind").notNull(),
+    campaignId: text("campaign_id"),
+    status: text("status").$type<DeliveryStatus>().notNull(),
+    attempts: integer("attempts").notNull(),
+    claimedAt: timestamp("claimed_at", { withTimezone: true }).notNull(),
+    finishedAt: timestamp("finished_at", { withTimezone: true }),
+    providerMessageId: text("provider_message_id"),
+    reason: text("reason"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.scope, table.recipientKey] })],
+);
+
+/** A ledger row's state: `pending` (released for a retry), `claimed`, or a final `sent` / `rejected`. */
+export type DeliveryStatus = "pending" | "claimed" | "sent" | "rejected";

package/src/server/campaign-file.ts

@@ -0,0 +1,101 @@
+// The campaign content file of `softure-mail campaign`: a frontmatter block and a plain-text body.
+//
+//   ---
+//   id: 2026-10-launch
+//   kind: newsletter
+//   subject: Something new in Plan
+//   html: launch.html
+//   ---
+//   Hello,
+//   ...
+//
+// `html` is optional and names a file next to the content file, rendered however the operator
+// likes. There is no markdown: the text body is sent as written.
+import { isMailKind, MAX_SUBJECT_LENGTH } from "../address.js";
+import { TRANSACTIONAL_KIND } from "../contract.js";
+
+/** A campaign's content, as `sendCampaign` sends it. */
+export interface CampaignContent {
+  /** Kebab-case, at most 64 characters, e.g. `2026-10-launch`. Never reuse an id for other content. */
+  readonly id: string;
+  /** The list it belongs to, e.g. `newsletter`; never `transactional`. */
+  readonly kind: string;
+  readonly subject: string;
+  readonly text: string;
+  readonly html: string | null;
+}
+
+/** A parsed content file: the HTML body is still a path relative to the file. */
+export interface CampaignFile extends Omit<CampaignContent, "html"> {
+  readonly htmlPath: string | null;
+}
+
+export type CampaignFileResult = { readonly ok: true; readonly value: CampaignFile } | { readonly ok: false; readonly problems: readonly string[] };
+
+const FENCE = "---";
+const KEYS = new Set(["id", "kind", "subject", "html"]);
+const CAMPAIGN_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_CAMPAIGN_ID_LENGTH = 64;
+
+/** Parses a content file, listing every problem at once. */
+export function parseCampaignFile(source: string): CampaignFileResult {
+  const lines = source.replace(/^\uFEFF/, "").split(/\r?\n/);
+  if (lines[0]?.trim() !== FENCE) return { ok: false, problems: ["the file must start with a --- line opening the frontmatter"] };
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === FENCE);
+  if (end === -1) return { ok: false, problems: ["the frontmatter has no closing --- line"] };
+
+  const problems: string[] = [];
+  const fields = new Map<string, string>();
+  lines.slice(1, end).forEach((line, index) => {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) return;
+    const match = /^([a-z]+):(.*)$/.exec(line);
+    const key = match?.[1];
+    const value = match?.[2]?.trim();
+    if (key === undefined || value === undefined) {
+      problems.push(`frontmatter line ${String(index + 2)} must read "key: value"`);
+    } else if (!KEYS.has(key)) {
+      problems.push(`unknown frontmatter key "${key}"; use ${[...KEYS].join(", ")}`);
+    } else if (fields.has(key)) {
+      problems.push(`frontmatter key "${key}" appears twice`);
+    } else {
+      fields.set(key, value);
+    }
+  });
+
+  const text = lines.slice(end + 1).join("\n").trim();
+  const file: CampaignFile = {
+    id: fields.get("id") ?? "",
+    kind: fields.get("kind") ?? "",
+    subject: fields.get("subject") ?? "",
+    text,
+    htmlPath: fields.get("html") ?? null,
+  };
+  problems.push(...getCampaignProblems({ ...file, html: null }));
+  if (file.htmlPath === "") problems.push("html: give a file name or leave the key out");
+  return problems.length === 0 ? { ok: true, value: file } : { ok: false, problems };
+}
+
+/** What makes `content` unsendable as a campaign; empty when it is fine. */
+export function getCampaignProblems(content: CampaignContent): string[] {
+  const problems: string[] = [];
+  if (content.id.length > MAX_CAMPAIGN_ID_LENGTH || !CAMPAIGN_ID.test(content.id)) {
+    problems.push("id: kebab-case, at most 64 characters, e.g. 2026-10-launch");
+  }
+  if (!isMailKind(content.kind) || content.kind === TRANSACTIONAL_KIND) {
+    problems.push("kind: a kebab-case list name such as newsletter; campaigns are never transactional");
+  }
+  if (content.subject.trim() === "" || content.subject.length > MAX_SUBJECT_LENGTH || /[\r\n]/.test(content.subject)) {
+    problems.push(`subject: one line, 1 to ${String(MAX_SUBJECT_LENGTH)} characters`);
+  }
+  if (content.text.trim() === "") problems.push("the text body under the frontmatter is empty");
+  if (content.html?.trim() === "") problems.push("the HTML body is empty");
+  return problems;
+}
+
+/** The addresses of a recipients file: one per line; blank lines and `#` comments are skipped. */
+export function parseRecipientList(source: string): string[] {
+  return source
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && !line.startsWith("#"));
+}

package/src/server/campaigns.ts

@@ -0,0 +1,175 @@
+// 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.
+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 { 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 { 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"]);
+
+/** The campaign id is taken by other content. Give the new content a new id. */
+export type CampaignErrorCode = "mailing.campaign_changed";
+
+export interface CampaignSummary {
+  /** Distinct recipients in the list (addresses that differ only in case or spaces count once). */
+  readonly recipients: number;
+  readonly sent: number;
+  /** Rejected in this run, by reason. Suppressed recipients are here, under `mailing.suppressed`. */
+  readonly rejected: Readonly<Record<MailingErrorCode, number>>;
+  /** Closed by an earlier run; nothing sent. */
+  readonly done: number;
+  /** Claimed by another run that is still sending. */
+  readonly inFlight: number;
+  /** The provider was unavailable; the next run tries them again. */
+  readonly retryLater: number;
+}
+
+export interface SendCampaignOptions extends DeliverOptions {
+  /** Pause after every mail that reached the provider, for its rate limit. Default 0. */
+  readonly pauseMs?: number;
+  /** Called after every recipient, e.g. for progress output. Never receives the address. */
+  readonly onDelivery?: (outcome: DeliveryOutcome) => void;
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/** sha256 (hex) of what a recipient reads: kind, subject, text and HTML. */
+export function getCampaignContentHash(content: CampaignContent): string {
+  return createHash("sha256").update(JSON.stringify([content.kind, content.subject, content.text, content.html])).digest("hex");
+}
+
+/**
+ * Records the campaign, or confirms that the stored one has the same content. Throws on a
+ * database failure and for content `getCampaignProblems` refuses.
+ */
+export async function registerCampaign(ctx: DeliveryContext, content: CampaignContent): Promise<Result<undefined, CampaignErrorCode>> {
+  assertCampaign(content);
+  const contentHash = getCampaignContentHash(content);
+  await ctx.db
+    .insert(campaigns)
+    .values({ id: content.id, kind: content.kind, subject: content.subject, contentHash, createdAt: ctx.clock.now() })
+    .onConflictDoNothing();
+  const rows = await ctx.db.select({ contentHash: campaigns.contentHash }).from(campaigns).where(eq(campaigns.id, content.id)).limit(1);
+  return rows[0]?.contentHash === contentHash ? ok() : err("mailing.campaign_changed");
+}
+
+/**
+ * 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.
+ */
+export async function sendCampaign(
+  ctx: DeliveryContext,
+  input: { readonly campaign: CampaignContent; readonly recipients: Iterable<string> | AsyncIterable<string> },
+  options: SendCampaignOptions = {},
+): Promise<Result<CampaignSummary, CampaignErrorCode>> {
+  const { pauseMs = 0, onDelivery, sleep = wait, ...deliverOptions } = options;
+  const { campaign } = input;
+  const registered = await registerCampaign(ctx, campaign);
+  if (!registered.ok) return registered;
+
+  const counts = { sent: 0, done: 0, inFlight: 0, retryLater: 0, rejected: emptyRejections() };
+  const seen = new Set<string>();
+  const scope = `campaign:${campaign.id}`;
+  for await (const address of input.recipients) {
+    const recipientKey = getRecipientKey(address);
+    if (seen.has(recipientKey)) continue;
+    seen.add(recipientKey);
+
+    const html = campaign.html === null ? {} : { html: campaign.html };
+    const outcome = await deliverOnce(
+      ctx,
+      { scope, campaignId: campaign.id, mail: { to: address, subject: campaign.subject, text: campaign.text, kind: campaign.kind, ...html } },
+      deliverOptions,
+    );
+    countOutcome(counts, outcome);
+    onDelivery?.(outcome);
+    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 });
+}
+
+export interface CampaignPlan {
+  readonly recipients: number;
+  /** Already closed by an earlier run. */
+  readonly done: number;
+  /** Not closed yet, but unsubscribed: they will be rejected without a send. */
+  readonly suppressed: 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. */
+export async function planCampaign(
+  ctx: DeliveryContext,
+  input: { readonly campaign: CampaignContent; readonly recipients: Iterable<string> | AsyncIterable<string> },
+): Promise<CampaignPlan> {
+  const { campaign } = input;
+  assertCampaign(campaign);
+  const stored = await ctx.db.select({ contentHash: campaigns.contentHash }).from(campaigns).where(eq(campaigns.id, campaign.id)).limit(1);
+  const contentChanged = stored[0] !== undefined && stored[0].contentHash !== getCampaignContentHash(campaign);
+
+  const addresses = new Map<string, string>();
+  for await (const address of input.recipients) {
+    const key = getRecipientKey(address);
+    if (!addresses.has(key)) addresses.set(key, address);
+  }
+  const closed = 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 })
+      .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));
+  }
+  let suppressed = 0;
+  for (const [key, address] of addresses) {
+    if (!closed.has(key) && (await isSuppressed(ctx, address))) suppressed += 1;
+  }
+  return { recipients: addresses.size, done: closed.size, suppressed, toSend: addresses.size - closed.size - suppressed, contentChanged };
+}
+
+function assertCampaign(content: CampaignContent): void {
+  const problems = getCampaignProblems(content);
+  if (problems.length > 0) throw new Error(`@softure-ai/mailing: campaign "${content.id}" cannot be sent: ${problems.join("; ")}`);
+}
+
+function emptyRejections(): Record<MailingErrorCode, number> {
+  return { "mailing.invalid_input": 0, "mailing.rejected": 0, "mailing.unavailable": 0, "mailing.suppressed": 0 };
+}
+
+function countOutcome(
+  counts: { sent: number; done: number; inFlight: number; retryLater: number; rejected: Record<MailingErrorCode, number> },
+  outcome: DeliveryOutcome,
+): void {
+  switch (outcome.status) {
+    case "sent":
+      counts.sent += 1;
+      return;
+    case "rejected":
+      counts.rejected[outcome.reason] += 1;
+      return;
+    case "done":
+      counts.done += 1;
+      return;
+    case "in-flight":
+      counts.inFlight += 1;
+      return;
+    case "retry-later":
+      counts.retryLater += 1;
+      return;
+  }
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}