@softure-ai/mailing 0.1.11 → 0.1.13

package/src/cli/run.ts

@@ -1,5 +1,5 @@
-// `softure-mail`: sends a campaign from a content file, imports an app's delivery history into the
-// ledger and checks the sender domain's DNS. The app passes its validated config, so the same
+// `softure-mail`: sends a campaign from a content file, sends a test mail to the configured test
+// address, imports an app's delivery history into the ledger and checks the sender domain's DNS. The app passes its validated config, so the same
 // function serves the bin and an app script that a bundler packs for a container:
 //
 //   // scripts/mail.ts
@@ -12,12 +12,15 @@ import { parseArgs } from "node:util";
 import { systemClock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
 import { z } from "zod";
 import { openCommandDatabase, type CommandDatabase, type DatabaseHandle } from "@softure-ai/db";
-import { parseCampaignFile, parseRecipientList, type CampaignContent } from "../server/campaign-file.js";
+import { TRANSACTIONAL_KIND, type OutgoingMail, type ProviderMessage } from "../contract.js";
+import { getCampaignProblems, parseCampaignFile, parseRecipientList, type CampaignContent } from "../server/campaign-file.js";
 import { listConfiguredCampaignRecipients, planCampaign, sendCampaign, type CampaignSummary } from "../server/campaigns.js";
-import type { DeliveryContext, HaltingErrorCode } from "../server/deliveries.js";
+import type { DeliveryContext, RunHaltReason } from "../server/deliveries.js";
 import { checkSenderDns, getSenderDomain, resendReturnPath, type DmarcAlignment, type DmarcExpectation, type DmarcPolicy, type DnsCheck, type ResolveCname, type ResolveMx, type ResolveTxt, type ReturnPathHost } from "../server/dns.js";
 import { checkImportedDeliveries, importDeliveries, type ImportedDelivery, type ImportProblem } from "../server/import-deliveries.js";
-import { getMailingOptions } from "../server/options.js";
+import { maskAddress, redactUnsubscribeSignatures } from "../server/operator-output.js";
+import { getMailingOptions, resolveMailKind } from "../server/options.js";
+import { previewMail, sendMail } from "../server/send-mail.js";
 import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV, type Env } from "../server/unsubscribe-link.js";
 
 export interface CliOutput {
@@ -26,7 +29,7 @@ export interface CliOutput {
 }
 
 export interface RunMailCliOptions {
-  /** The app's config. Needed by `campaign` and `import`, and by `dns` without `--domain`. */
+  /** The app's config. Needed by `campaign`, `test` and `import`, and by `dns` without `--domain`. */
   readonly config?: SoftureConfig;
   /** The arguments after the executable, e.g. `["campaign", "launch.md", "--recipients", "list.txt"]`. */
   readonly argv: readonly string[];
@@ -54,10 +57,12 @@ export const DEFAULT_PAUSE_MS = 500;
 export const MAIL_USAGE = `Usage:
   softure-mail campaign <content-file> [--recipients <file>] [--dry-run] [--pause-ms <ms>] [--resend-uncertain]
                         [--limit <n>]
+  softure-mail test [<content-file>] [--kind <kind>] [--preview]
   softure-mail import <history-file> [--dry-run]
   softure-mail dns [--domain <domain>] [--dkim-selector <name>]... [--spf-host <host>]...
                    [--dmarc-policy <p>] [--dmarc-sp <p>] [--dmarc-adkim <a>] [--dmarc-aspf <a>]
                    [--reply-to <address>] [--return-path <host>]... [--resend-return-path]
+                   [--inbound cloudflare]
 
 campaign  Sends the campaign in <content-file> (frontmatter id, kind, subject, optional html,
           then the text body) to every address in the recipients file (one per line), at most
@@ -71,6 +76,17 @@ campaign  Sends the campaign in <content-file> (frontmatter id, kind, subject, o
                        (it may have gone out: they may get the mail twice)
   --limit <n>          hand at most n mails to the provider in this run (1 to 1000000);
                        the rest waits for the next run
+  --content-file <file>  the content file, instead of naming it first (for softure-deploy run)
+  The kind may be an alias of kindAliases in the mailing options. A dry run also prints the
+  mail as the test address (testAddress in the mailing options) would get it. Content that
+  carries an unsubscribe link or footer pasted from a sent mail is refused.
+
+test      Sends one mail to testAddress of the mailing options, and to no one else: the
+          campaign in <content-file> (without the ledger: it can be sent again), or a short
+          fixed test mail.
+  --kind <kind>        the mail's kind (default: the file's, else transactional); list kinds
+                       get the unsubscribe footer and headers
+  --preview            print the mail instead of sending it
 
 import    Writes deliveries the app made before it adopted the module into the ledger, so
           later sends skip them. <history-file> holds one JSON object per line: scope,
@@ -93,13 +109,16 @@ dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain
                           (default: replyTo of the config, when --domain is not given)
   --return-path <host>    a return-path host that must be a CNAME or have MX (repeatable)
   --resend-return-path    check Resend's send.<domain> and rsend.<domain> CNAMEs
+  --inbound cloudflare    check that Cloudflare Email Routing receives the reply-to domain's
+                          mail (its MX and one SPF record that includes it)
 
 Options for all:
   --config <file>    the app's softure.config file (bin only)
   --help             show this help
 
 A file given as - is read from standard input (one of them per command), e.g.
-  docker compose exec -T app npx softure-mail campaign - < launch.md`;
+  docker compose exec -T app npx softure-mail campaign - < launch.md
+Addresses in the output are masked and unsubscribe links lose their signature.`;
 
 const consoleOutput: CliOutput = {
   log: (line) => console.log(line),
@@ -119,6 +138,14 @@ type Command =
       /** `null`: no limit. */
       readonly limit: number | null;
     }
+  | {
+      readonly kind: "test";
+      /** `null`: the fixed test mail. */
+      readonly contentFile: string | null;
+      /** `null`: the file's kind, else transactional. */
+      readonly mailKind: string | null;
+      readonly preview: boolean;
+    }
   | { readonly kind: "import"; readonly historyFile: string; readonly dryRun: boolean }
   | {
       readonly kind: "dns";
@@ -129,6 +156,7 @@ type Command =
       readonly replyTo: string | undefined;
       readonly returnPathHosts: readonly string[];
       readonly resendReturnPath: boolean;
+      readonly inbound: "cloudflare" | undefined;
     };
 
 const DMARC_POLICIES: readonly DmarcPolicy[] = ["quarantine", "reject"];
@@ -136,8 +164,10 @@ const DMARC_ALIGNMENTS: readonly DmarcAlignment[] = ["r", "s"];
 /** A file name that means standard input. */
 const STDIN = "-";
 const CAMPAIGN_ONLY_OPTIONS = ["recipients", "pause-ms", "resend-uncertain", "limit"] as const;
+const TEST_ONLY_OPTIONS = ["kind", "preview"] as const;
 const MAX_LIMIT = 1_000_000;
-const DNS_ONLY_OPTIONS = ["domain", "dkim-selector", "spf-host", "dmarc-policy", "dmarc-sp", "dmarc-adkim", "dmarc-aspf", "reply-to", "return-path", "resend-return-path"] as const;
+const DNS_ONLY_OPTIONS = ["domain", "dkim-selector", "spf-host", "dmarc-policy", "dmarc-sp", "dmarc-adkim", "dmarc-aspf", "reply-to", "return-path", "resend-return-path", "inbound"] as const;
+const COMMANDS = ["campaign", "test", "import", "dns"] as const;
 
 /** Runs the command and returns the process exit code: 0 done, 1 failed or incomplete, 2 usage error. */
 export async function runMailCli(options: RunMailCliOptions): Promise<number> {
@@ -156,6 +186,8 @@ export async function runMailCli(options: RunMailCliOptions): Promise<number> {
       return runDns(command, options, output);
     case "campaign":
       return runCampaign(command, options, output);
+    case "test":
+      return runTest(command, options, output);
     case "import":
       return runImport(command, options, output);
   }
@@ -163,9 +195,9 @@ export async function runMailCli(options: RunMailCliOptions): Promise<number> {
 
 function parseCommand(argv: readonly string[]): Command | string {
   const [name, ...rest] = argv;
-  if (name === undefined) return "missing command; use campaign, import or dns";
+  if (name === undefined) return "missing command; use campaign, test, import or dns";
   if (name === "--help") return { kind: "help" };
-  if (name !== "campaign" && name !== "import" && name !== "dns") return `unknown command "${name}"; use campaign, import or dns`;
+  if (!(COMMANDS as readonly string[]).includes(name)) return `unknown command "${name}"; use campaign, test, import or dns`;
 
   let parsed: ReturnType<typeof parseCommandArgs>;
   try {
@@ -177,11 +209,13 @@ function parseCommand(argv: readonly string[]): Command | string {
   if (values.help === true) return { kind: "help" };
 
   if (name === "dns") {
-    const misplaced = ([...CAMPAIGN_ONLY_OPTIONS, "dry-run"] as const).filter((option) => values[option] !== undefined);
+    const misplaced = ([...CAMPAIGN_ONLY_OPTIONS, ...TEST_ONLY_OPTIONS, "content-file", "dry-run"] as const).filter((option) => values[option] !== undefined);
     if (misplaced.length > 0) return `dns does not take --${misplaced.join(", --")}`;
     if (positionals.length > 0) return `dns takes no file, got "${positionals.join(" ")}"`;
     const expectDmarc = parseDmarcExpectation(values);
     if (typeof expectDmarc === "string") return expectDmarc;
+    const inbound = values.inbound?.trim().toLowerCase();
+    if (inbound !== undefined && inbound !== "cloudflare") return `--inbound expects cloudflare, got "${values.inbound ?? ""}"`;
     return {
       kind: "dns",
       domain: values.domain,
@@ -191,11 +225,12 @@ function parseCommand(argv: readonly string[]): Command | string {
       replyTo: values["reply-to"],
       returnPathHosts: values["return-path"] ?? [],
       resendReturnPath: values["resend-return-path"] === true,
+      inbound,
     };
   }
 
   if (name === "import") {
-    const misplaced = [...CAMPAIGN_ONLY_OPTIONS, ...DNS_ONLY_OPTIONS].filter((option) => values[option] !== undefined);
+    const misplaced = [...CAMPAIGN_ONLY_OPTIONS, ...TEST_ONLY_OPTIONS, ...DNS_ONLY_OPTIONS, "content-file" as const].filter((option) => values[option] !== undefined);
     if (misplaced.length > 0) return `import does not take --${misplaced.join(", --")}`;
     const [historyFile, ...extra] = positionals;
     if (historyFile === undefined) return "import needs a history file (- for standard input)";
@@ -203,11 +238,18 @@ function parseCommand(argv: readonly string[]): Command | string {
     return { kind: "import", historyFile, dryRun: values["dry-run"] === true };
   }
 
-  const misplaced = DNS_ONLY_OPTIONS.filter((option) => values[option] !== undefined);
+  const content = pickContentFile(name, positionals, values["content-file"]);
+  if (typeof content !== "object") return content;
+  if (name === "test") {
+    const misplaced = ([...CAMPAIGN_ONLY_OPTIONS, ...DNS_ONLY_OPTIONS, "dry-run"] as const).filter((option) => values[option] !== undefined);
+    if (misplaced.length > 0) return `test does not take --${misplaced.join(", --")}`;
+    return { kind: "test", contentFile: content.file, mailKind: values.kind ?? null, preview: values.preview === true };
+  }
+
+  const misplaced = [...TEST_ONLY_OPTIONS, ...DNS_ONLY_OPTIONS].filter((option) => values[option] !== undefined);
   if (misplaced.length > 0) return `campaign does not take --${misplaced.join(", --")}`;
-  const [contentFile, ...extra] = positionals;
-  if (contentFile === undefined) return "campaign needs a content file";
-  if (extra.length > 0) return `campaign takes one content file, got also "${extra.join(" ")}"`;
+  const contentFile = content.file;
+  if (contentFile === null) return "campaign needs a content file";
   if (contentFile === STDIN && values.recipients === STDIN) return "campaign can read only one of the content file and --recipients from standard input";
   const pauseMs = values["pause-ms"] === undefined ? DEFAULT_PAUSE_MS : Number(values["pause-ms"]);
   if (!Number.isInteger(pauseMs) || pauseMs < 0 || pauseMs > 60_000) return `--pause-ms expects whole milliseconds from 0 to 60000, got "${values["pause-ms"] ?? ""}"`;
@@ -243,6 +285,10 @@ function parseCommandArgs(args: readonly string[]) {
       "reply-to": { type: "string" },
       "return-path": { type: "string", multiple: true },
       "resend-return-path": { type: "boolean" },
+      inbound: { type: "string" },
+      "content-file": { type: "string" },
+      kind: { type: "string" },
+      preview: { type: "boolean" },
       help: { type: "boolean" },
     },
     strict: true,
@@ -252,6 +298,14 @@ function parseCommandArgs(args: readonly string[]) {
 
 type ParsedValues = ReturnType<typeof parseCommandArgs>["values"];
 
+/** The content file, named first or with `--content-file` (not both, at most one); `null` when none was given. */
+function pickContentFile(command: string, positionals: readonly string[], option: string | undefined): { readonly file: string | null } | string {
+  const [first, ...extra] = positionals;
+  if (extra.length > 0) return `${command} takes one content file, got also "${extra.join(" ")}"`;
+  if (first !== undefined && option !== undefined) return `${command} takes the content file once: name it first or with --content-file`;
+  return { file: first ?? option ?? null };
+}
+
 /** One choice of a fixed list, case-insensitive; `undefined` when the option was not given. */
 function pickChoice<T extends string>(values: ParsedValues, option: "dmarc-policy" | "dmarc-sp" | "dmarc-adkim" | "dmarc-aspf", allowed: readonly T[]): { readonly value: T | undefined } | string {
   const given = values[option];
@@ -297,6 +351,7 @@ async function runDns(command: Extract<Command, { kind: "dns" }>, options: RunMa
     ...(command.expectDmarc === undefined ? {} : { expectDmarc: command.expectDmarc }),
     ...(replyTo === undefined ? {} : { replyTo }),
     returnPath,
+    ...(command.inbound === undefined ? {} : { inbound: command.inbound }),
     ...(options.resolveTxt === undefined ? {} : { resolveTxt: options.resolveTxt }),
     ...(options.resolveMx === undefined ? {} : { resolveMx: options.resolveMx }),
     ...(options.resolveCname === undefined ? {} : { resolveCname: options.resolveCname }),
@@ -308,9 +363,10 @@ async function runDns(command: Extract<Command, { kind: "dns" }>, options: RunMa
   ];
   const reply: [string, DnsCheck][] = report.replyTo === null ? [] : [["REPLY", report.replyTo]];
   const paths: [string, DnsCheck][] = report.returnPath.map((check) => ["PATH", check]);
+  const inbound: [string, DnsCheck][] = report.inbound.map((check) => ["INBOUND", check]);
   output.log(`sender domain ${report.domain}`);
-  for (const [name, check] of [...authentication, ...reply, ...paths]) {
-    const line = `${name.padEnd(6)}${check.status.padEnd(6)}${`${check.finding} `.padEnd(15)}${check.host}${check.record === null ? "" : `  ${check.record}`}`;
+  for (const [name, check] of [...authentication, ...reply, ...paths, ...inbound]) {
+    const line = `${name.padEnd(name.length >= 6 ? name.length + 1 : 6)}${check.status.padEnd(6)}${`${check.finding} `.padEnd(15)}${check.host}${check.record === null ? "" : `  ${check.record}`}`;
     if (check.status === "fail") output.error(line);
     else output.log(line);
   }
@@ -318,13 +374,15 @@ async function runDns(command: Extract<Command, { kind: "dns" }>, options: RunMa
   const failedAuthentication = countFailed(authentication);
   const failedReply = countFailed(reply);
   const failedPaths = countFailed(paths);
-  if (failedAuthentication + failedReply + failedPaths === 0) {
+  const failedInbound = countFailed(inbound);
+  if (failedAuthentication + failedReply + failedPaths + failedInbound === 0) {
     output.log("receivers can authenticate mail from this domain");
     return EXIT_OK;
   }
   if (failedAuthentication > 0) output.log(`${String(failedAuthentication)} check(s) failed: list mail from this domain will land in spam or be refused`);
   if (failedReply > 0) output.log("the reply-to domain does not accept mail: replies will bounce");
   if (failedPaths > 0) output.log(`${String(failedPaths)} return-path host(s) failed: the provider cannot use them for bounces`);
+  if (failedInbound > 0) output.log("the inbound service does not receive this domain's mail: replies will not reach it");
   return EXIT_FAILED;
 }
 
@@ -336,7 +394,7 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
     return EXIT_FAILED;
   }
   const input = createInputReader(cwd, options.readStdin ?? readProcessStdin);
-  const content = await loadCampaignContent(command.contentFile, input);
+  const content = await loadCampaignContent(command.contentFile, input, config);
   if (typeof content === "string") {
     output.error(`softure-mail campaign: ${content}`);
     return EXIT_FAILED;
@@ -370,7 +428,7 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
   try {
     const loaded: LoadedCampaign = { campaign: content, recipients: listed ?? (await collectRecipients(ctx, content)) };
     return command.dryRun
-      ? await reportPlan(ctx, loaded, { retakeUncertain: command.resendUncertain, limit: command.limit }, output)
+      ? await reportPlan(ctx, loaded, { retakeUncertain: command.resendUncertain, limit: command.limit, env: options.env ?? process.env }, output)
       : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep, retakeUncertain: command.resendUncertain, limit: command.limit }, output);
   } catch (error) {
     // Driver errors: the message only, never a stack, an address or the database URL.
@@ -401,12 +459,16 @@ function createInputReader(cwd: string, readStdin: () => Promise<string>): Input
   };
 }
 
-async function loadCampaignContent(file: string, input: InputReader): Promise<CampaignContent | string> {
+/**
+ * The campaign in `file`, its kind resolved through `kindAliases`, checked for pasted unsubscribe links and footers;
+ * a string says what is wrong.
+ */
+async function loadCampaignContent(file: string, input: InputReader, config: SoftureConfig): Promise<CampaignContent | string> {
   const source = await input.read(file);
   if (source.text === null) return `cannot read the content file ${source.name}`;
   const parsed = parseCampaignFile(source.text);
   if (!parsed.ok) return `${source.name} is not a campaign:\n  ${parsed.problems.join("\n  ")}`;
-  const { htmlPath, ...content } = parsed.value;
+  const { htmlPath, kind, ...content } = parsed.value;
   let html: string | null = null;
   if (htmlPath !== null) {
     // Next to the content file; for standard input, the working directory.
@@ -415,7 +477,9 @@ async function loadCampaignContent(file: string, input: InputReader): Promise<Ca
     if (html === null) return `cannot read the HTML body ${htmlFile}`;
     if (html.trim() === "") return `the HTML body ${htmlFile} is empty`;
   }
-  return { ...content, html };
+  const campaign: CampaignContent = { ...content, kind: resolveMailKind(config, kind), html };
+  const problems = getCampaignProblems(campaign, config);
+  return problems.length === 0 ? campaign : `${source.name} cannot be sent:\n  ${problems.join("\n  ")}`;
 }
 
 async function loadRecipientFile(file: string, input: InputReader): Promise<readonly string[] | string> {
@@ -537,7 +601,7 @@ function reportImportProblems(problems: readonly LineProblem[], output: CliOutpu
 async function reportPlan(
   ctx: DeliveryContext,
   loaded: LoadedCampaign,
-  run: { readonly retakeUncertain: boolean; readonly limit: number | null },
+  run: { readonly retakeUncertain: boolean; readonly limit: number | null; readonly env: Env },
   output: CliOutput,
 ): Promise<number> {
   const plan = await planCampaign(ctx, loaded, { retakeUncertain: run.retakeUncertain });
@@ -557,9 +621,100 @@ async function reportPlan(
     output.error(`campaign ${loaded.campaign.id} was sent with other content; give this content a new id`);
     return EXIT_FAILED;
   }
+  const { campaign } = loaded;
+  const to = getMailingOptions(ctx.config).testAddress ?? PREVIEW_ADDRESS;
+  const preview = previewMail(ctx.config, { to, subject: campaign.subject, text: campaign.text, kind: campaign.kind, ...(campaign.html === null ? {} : { html: campaign.html }) }, { env: run.env });
+  if (preview.ok) printPreview(preview.value, output);
+  else if (preview.error === "mailing.unavailable") output.log(`no preview: set ${UNSUBSCRIBE_SECRET_ENV} to render the unsubscribe footer`);
+  else output.log(`no preview: the mail is invalid (${preview.fields.join(", ")})`);
   return EXIT_OK;
 }
 
+/** Who a dry run's preview is addressed to without `testAddress`; `.example` never receives mail (RFC 2606). */
+const PREVIEW_ADDRESS = "recipient@example.com";
+
+/** The mail as the provider would get it, one output line per line, the address masked and signatures redacted. */
+function printPreview(message: ProviderMessage, output: CliOutput): void {
+  const headers = [
+    `From: ${message.from}`,
+    `To: ${maskAddress(message.to)}`,
+    ...(message.replyTo === null ? [] : [`Reply-To: ${maskAddress(message.replyTo)}`]),
+    `Subject: ${message.subject}`,
+    ...Object.entries(message.headers).map(([name, value]) => `${name}: ${value}`),
+  ];
+  const sections = [`--- preview (addresses masked, link signatures redacted) ---`, ...headers, "", "--- text ---", message.text];
+  if (message.html !== null) sections.push("--- html ---", message.html);
+  sections.push("--- end of preview ---");
+  for (const line of redactUnsubscribeSignatures(sections.join("\n")).split("\n")) output.log(line);
+}
+
+/** The fixed mail of `softure-mail test` without a content file. Operator text: the test address is the operator's. */
+const TEST_MAIL = {
+  subject: "softure-mail test",
+  text: "This is a test mail from softure-mail. It arrived, so the provider, the sender address and the reply-to work.",
+};
+
+async function runTest(command: Extract<Command, { kind: "test" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
+  const config = options.config;
+  if (config === undefined) {
+    output.error("softure-mail test: needs the app's config");
+    return EXIT_FAILED;
+  }
+  const testAddress = getMailingOptions(config).testAddress;
+  if (testAddress === undefined) {
+    output.error("softure-mail test: set testAddress in the mailing options; the test sends to that address only");
+    return EXIT_FAILED;
+  }
+  let body: { readonly subject: string; readonly text: string; readonly html: string | null; readonly kind: string } = { ...TEST_MAIL, html: null, kind: TRANSACTIONAL_KIND };
+  if (command.contentFile !== null) {
+    const content = await loadCampaignContent(command.contentFile, createInputReader(options.cwd ?? process.cwd(), options.readStdin ?? readProcessStdin), config);
+    if (typeof content === "string") {
+      output.error(`softure-mail test: ${content}`);
+      return EXIT_FAILED;
+    }
+    body = content;
+  }
+  const kind = command.mailKind === null ? body.kind : resolveMailKind(config, command.mailKind);
+  const mail: OutgoingMail = { to: testAddress, subject: body.subject, text: body.text, kind, ...(body.html === null ? {} : { html: body.html }) };
+  const masked = maskAddress(testAddress);
+  if (command.preview) {
+    const preview = previewMail(config, mail, { env: options.env ?? process.env });
+    if (!preview.ok) {
+      output.error(`softure-mail test: ${preview.error === "mailing.invalid_input" ? `the mail is invalid (${preview.fields.join(", ")})` : `set ${UNSUBSCRIBE_SECRET_ENV} to sign the unsubscribe link of list mail`}`);
+      return EXIT_FAILED;
+    }
+    printPreview(preview.value, output);
+    return EXIT_OK;
+  }
+  if (kind === TRANSACTIONAL_KIND) return reportTestSend(await sendMail({ config }, mail), { masked, kind }, output);
+  if (config.database === null) {
+    output.error("softure-mail test: list mail needs the database (its suppression list); set database.url in softure.config");
+    return EXIT_FAILED;
+  }
+  let opened: CommandDatabase;
+  try {
+    opened = await openDatabase(config.database, options.openDatabase);
+  } catch (error) {
+    output.error(`softure-mail test: ${describeError(error)}`);
+    return EXIT_FAILED;
+  }
+  try {
+    return reportTestSend(await sendMail({ config, db: opened.handle.db }, mail), { masked, kind }, output);
+  } finally {
+    await opened.close();
+  }
+}
+
+function reportTestSend(result: Awaited<ReturnType<typeof sendMail>>, sent: { readonly masked: string; readonly kind: string }, output: CliOutput): number {
+  if (result.ok) {
+    output.log(`test mail (${sent.kind}) sent to ${sent.masked}; provider message id ${result.value.id}`);
+    return EXIT_OK;
+  }
+  const status = result.httpStatus === undefined ? "" : ` (HTTP ${String(result.httpStatus)})`;
+  output.error(`test mail (${sent.kind}) to ${sent.masked} not sent: ${result.error.slice("mailing.".length)}${status}`);
+  return EXIT_FAILED;
+}
+
 async function reportSend(
   ctx: DeliveryContext,
   loaded: LoadedCampaign,
@@ -588,7 +743,8 @@ async function reportSend(
   let code = EXIT_OK;
   if (summary.halted !== null) {
     const status = summary.halted.httpStatus === undefined ? "" : ` (HTTP ${String(summary.halted.httpStatus)})`;
-    output.error(`stopped: ${HALT_EXPLANATIONS[summary.halted.reason]}${status}; the remaining recipients were not touched, run the same command again once it is fixed`);
+    const when = summary.halted.reason === "mailing.unavailable" ? "later" : "once it is fixed";
+    output.error(`stopped: ${HALT_EXPLANATIONS[summary.halted.reason]}${status}; the remaining recipients were not touched, run the same command again ${when}`);
     code = EXIT_FAILED;
   }
   const open = summary.inFlight + summary.retryLater;
@@ -605,9 +761,10 @@ async function reportSend(
   return code;
 }
 
-const HALT_EXPLANATIONS: Readonly<Record<HaltingErrorCode, string>> = {
+const HALT_EXPLANATIONS: Readonly<Record<RunHaltReason, string>> = {
   "mailing.provider_refused": "the provider refused the account (check the API key and the account)",
   "mailing.quota_exceeded": "the account's sending quota is spent",
+  "mailing.unavailable": "the provider is unavailable or rate limiting",
 };
 
 function formatSummary(summary: CampaignSummary): string {

package/src/contract.ts

@@ -89,12 +89,18 @@ export type LegacyUnsubscribeParams = readonly string[] | { readonly required: r
  * 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 the values the link carried (every required name, the optional names that are
  * present and non-empty, 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.
+ * else `null`. It must check the link's signature itself: whatever address it returns is unsubscribed. `env` is the
+ * environment `unsubscribe` was given (`process.env` in the page and the route), so the old signing key is read
+ * from it and a test passes its own instead of stubbing `process.env`. A throw reads as a failure (the person may
+ * try again), not as a bad link.
  */
 export interface LegacyUnsubscribe {
   readonly params: LegacyUnsubscribeParams;
-  readonly verify: (values: Readonly<Record<string, string>>, ctx: ModuleContext<Queryable>) => Promise<string | null>;
+  readonly verify: (
+    values: Readonly<Record<string, string>>,
+    ctx: ModuleContext<Queryable>,
+    env: Readonly<Record<string, string | undefined>>,
+  ) => Promise<string | null>;
 }
 
 /** One mail to one recipient. A mail to a list is a loop over recipients, never a list in `to`. */

package/src/index.ts

@@ -17,7 +17,7 @@ export const MODULE_ID = "mailing";
 export const mailing = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.11",
+    version: "0.1.13",
     dependsOn: {},
     dbSchema: "mailing",
     tables: ["suppressions", "campaigns", "deliveries"],

package/src/next/index.ts

@@ -5,7 +5,9 @@ export { unsubscribeAction } from "./actions.js";
 export { deliverOnce } from "./deliver-once.js";
 export { importDeliveries } from "./import-deliveries.js";
 export { getMailingMessages } from "./messages.js";
-export { UnsubscribePage, type UnsubscribePageProps } from "./pages.js";
+export { createUnsubscribePage, UnsubscribePage, type UnsubscribeLayoutProps, type UnsubscribePageOptions, type UnsubscribePageProps, type UnsubscribePageSlot } from "./pages.js";
+export { previewMail } from "./preview-mail.js";
 export { UNSUBSCRIBE_STATUS_PARAM, type UnsubscribeStatus } from "./params.js";
 export { getUnsubscribeRoute, postUnsubscribeRoute } from "./route.js";
+export { runDeliveries } from "./run-deliveries.js";
 export { sendMail } from "./send-mail.js";

package/src/next/pages.tsx

@@ -6,8 +6,8 @@
 // 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 { Button, Card, createSlotClassGetter, FormError, type ClassNames } from "@softure-ai/ui";
+import type { ComponentType, ReactNode } from "react";
 import { getUnsubscribeLinkParams, readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { unsubscribeAction } from "./actions.js";
 import { getMailingMessages } from "./messages.js";
@@ -19,50 +19,105 @@ 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";
+/** The page's parts an app can style: the `main` wrapper, the card, the form and the submit button. */
+export type UnsubscribePageSlot = "root" | "card" | "form" | "submit";
+
+/** What a custom layout receives: the page's copy, and the form (none on the outcome pages). */
+export interface UnsubscribeLayoutProps {
+  readonly title: string;
+  readonly lead: string;
+  readonly children?: ReactNode;
+}
+
+export interface UnsubscribePageOptions {
+  /** Classes per slot, added to the defaults (or alone with `unstyled`). */
+  readonly classNames?: ClassNames<UnsubscribePageSlot>;
+  readonly unstyled?: boolean;
+  /**
+   * Replaces the `main` wrapper and the card, e.g. with the app's header and footer around the copy; the `root` and
+   * `card` classes then do not apply. The form inside stays the module's.
+   */
+  readonly Layout?: ComponentType<UnsubscribeLayoutProps>;
+}
+
+const DEFAULT_CLASSES: Readonly<Record<UnsubscribePageSlot, string>> = {
+  root: "sft:mx-auto sft:box-border sft:w-full sft:sm:max-w-md sft:px-4 sft:py-4",
+  card: "",
+  form: "sft:flex sft:flex-col sft:gap-3 sft:font-sans",
+  submit: "",
+};
 
 function readParam(params: Record<string, string | string[] | undefined>, name: string): string | undefined {
   const value = params[name];
   return Array.isArray(value) ? value[0] : value;
 }
 
+type SlotClass = (slot: UnsubscribePageSlot) => string | undefined;
+
 /**
  * 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.
+ * keeps the Origin header Next checks on server actions. The tag is rendered whatever the layout.
  */
-function UnsubscribeLayout({ title, lead, children }: { title: string; lead: string; children?: ReactNode }) {
+function UnsubscribeLayout({ title, lead, children, slot, options }: UnsubscribeLayoutProps & { readonly slot: SlotClass; readonly options: UnsubscribePageOptions }) {
+  const { Layout } = options;
+  if (Layout !== undefined) {
+    return (
+      <>
+        <meta name="referrer" content="same-origin" />
+        <Layout title={title} lead={lead}>
+          {children}
+        </Layout>
+      </>
+    );
+  }
+  const card = slot("card");
   return (
-    <main className={LAYOUT_CLASS}>
+    <main className={slot("root")}>
       <meta name="referrer" content="same-origin" />
-      <Card title={title} subtitle={lead}>
+      <Card title={title} subtitle={lead} unstyled={options.unstyled} {...(card === undefined ? {} : { classNames: { root: card } })}>
         {children}
       </Card>
     </main>
   );
 }
 
+/**
+ * The unsubscribe page with the app's classes or layout:
+ * `export default createUnsubscribePage({ classNames: { root: "app-narrow" }, Layout: AppShell })`.
+ */
+export function createUnsubscribePage(options: UnsubscribePageOptions = {}) {
+  return async function UnsubscribePageWithOptions({ searchParams }: UnsubscribePageProps) {
+    return renderUnsubscribePage(searchParams, options);
+  };
+}
+
 export async function UnsubscribePage({ searchParams }: UnsubscribePageProps) {
+  return renderUnsubscribePage(searchParams, {});
+}
+
+async function renderUnsubscribePage(searchParams: SearchParams | undefined, options: UnsubscribePageOptions) {
   const config = getSoftureConfig();
   const messages = getMailingMessages(config).unsubscribe;
+  const slot = createSlotClassGetter({ defaults: DEFAULT_CLASSES, classNames: options.classNames, unstyled: options.unstyled });
   const params = (await searchParams) ?? {};
   const status = readParam(params, UNSUBSCRIBE_STATUS_PARAM);
-  if (status === "done") return <UnsubscribeLayout title={messages.doneTitle} lead={messages.doneBody} />;
+  if (status === "done") return <UnsubscribeLayout title={messages.doneTitle} lead={messages.doneBody} slot={slot} options={options} />;
 
   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.invalidTitle} lead={messages.invalidBody} slot={slot} options={options} />;
   }
+  const submit = slot("submit");
   return (
-    <UnsubscribeLayout title={messages.title} lead={messages.lead}>
-      <form action={unsubscribeAction} className={FORM_CLASS}>
+    <UnsubscribeLayout title={messages.title} lead={messages.lead} slot={slot} options={options}>
+      <form action={unsubscribeAction} className={slot("form")}>
         {Object.entries(linkParams).map(([name, value]) => (
           <input key={name} type="hidden" name={name} value={value} />
         ))}
-        <FormError message={status === "failed" ? messages.failed : undefined} />
+        <FormError message={status === "failed" ? messages.failed : undefined} unstyled={options.unstyled} />
         <div>
-          <Button type="submit" variant="primary">
+          <Button type="submit" variant="primary" unstyled={options.unstyled} {...(submit === undefined ? {} : { classNames: { root: submit } })}>
             {messages.submit}
           </Button>
         </div>

package/src/next/preview-mail.ts

@@ -0,0 +1,9 @@
+// `previewMail` on the app's registered configuration, e.g. for an admin page that shows a mail before it goes out.
+import { getSoftureConfig } from "@softure-ai/core/next";
+import type { OutgoingMail } from "../contract.js";
+import { previewMail as previewMailWithConfig, type MailPreviewResult, type PreviewMailOptions } from "../server/send-mail.js";
+
+/** What `sendMail` would hand the provider for `mail`; see `previewMail` in `@softure-ai/mailing/server`. */
+export function previewMail(mail: OutgoingMail, options: PreviewMailOptions = {}): MailPreviewResult {
+  return previewMailWithConfig(getSoftureConfig(), mail, options);
+}

package/src/next/run-deliveries.ts

@@ -0,0 +1,10 @@
+// `runDeliveries` on the app's registered configuration and the shared database, for a route handler or a job that
+// sends lifecycle mail to many recipients at most once each.
+import type { DeliveryRunInput, DeliveryRunSummary, RunDeliveriesOptions } from "../server/run-deliveries.js";
+import { runDeliveries as runDeliveriesWithContext } from "../server/run-deliveries.js";
+import { getMailingContext } from "./context.js";
+
+/** Delivers one mail per recipient through the ledger; see `runDeliveries` in `@softure-ai/mailing/server`. */
+export async function runDeliveries<Recipient>(input: DeliveryRunInput<Recipient>, options: RunDeliveriesOptions = {}): Promise<DeliveryRunSummary> {
+  return runDeliveriesWithContext(await getMailingContext(), input, options);
+}