@softure-ai/mailing 0.1.7 → 0.1.9

package/src/cli/run.ts

@@ -1,6 +1,6 @@
-// `softure-mail`: sends a campaign from a content file 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:
+// `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
+// function serves the bin and an app script that a bundler packs for a container:
 //
 //   // scripts/mail.ts
 //   import { runMailCli } from "@softure-ai/mailing/cli";
@@ -10,11 +10,13 @@ import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 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 { planCampaign, sendCampaign, type CampaignSummary } from "../server/campaigns.js";
+import { listConfiguredCampaignRecipients, planCampaign, sendCampaign, type CampaignSummary } from "../server/campaigns.js";
 import type { DeliveryContext, HaltingErrorCode } from "../server/deliveries.js";
-import { checkSenderDns, getSenderDomain, type DnsCheck, type ResolveTxt } from "../server/dns.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 { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV, type Env } from "../server/unsubscribe-link.js";
 
@@ -24,7 +26,7 @@ export interface CliOutput {
 }
 
 export interface RunMailCliOptions {
-  /** The app's config. Needed by `campaign`, and by `dns` without `--domain`. */
+  /** The app's config. Needed by `campaign` 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[];
@@ -34,8 +36,12 @@ export interface RunMailCliOptions {
   /** Opens the campaign's database connection. Default: the config's `database.handle`, else `createDatabase(url, { max: 1 })`. */
   readonly openDatabase?: (url: string) => Promise<DatabaseHandle>;
   readonly resolveTxt?: ResolveTxt;
+  readonly resolveMx?: ResolveMx;
+  readonly resolveCname?: ResolveCname;
   readonly sleep?: (ms: number) => Promise<void>;
   readonly env?: Env;
+  /** Reads all of standard input, for a file given as `-`. Default: `process.stdin`. */
+  readonly readStdin?: () => Promise<string>;
 }
 
 export const EXIT_OK = 0;
@@ -46,27 +52,51 @@ export const EXIT_USAGE = 2;
 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]
+  softure-mail campaign <content-file> [--recipients <file>] [--dry-run] [--pause-ms <ms>] [--resend-uncertain]
+  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]
 
 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
-          once each. Re-running sends only to recipients without an outcome yet. A refused
-          API key or a spent quota stops the run; the rest go out on the next one.
+          once each. Without --recipients, the recipients come from listCampaignRecipients in
+          the mailing options. Re-running sends only to recipients without an outcome yet. A
+          refused API key or a spent quota stops the run; the rest go out on the next one.
+  --recipients <file>  the recipients, one address per line
   --dry-run            count what would be sent and change nothing
   --pause-ms <ms>      pause after every send (default ${String(DEFAULT_PAUSE_MS)})
   --resend-uncertain   also send to recipients whose send was interrupted long ago
                        (it may have gone out: they may get the mail twice)
 
+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,
+          address, status (sent or rejected), finishedAt, and optional providerMessageId,
+          reason, kind. Rows already in the ledger are left as they are; any invalid row
+          stops the import before anything is written.
+  --dry-run            check the file and change nothing
+
 dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain of "from").
   --domain <domain>       check this domain instead
   --dkim-selector <name>  DKIM selector to look up (default resend; repeatable)
   --spf-host <host>       where SPF is published (default the domain; repeatable;
                           Resend publishes it on send.<domain>)
+  --dmarc-policy <p>      require at least this DMARC policy (quarantine or reject)
+                          and pct=100; a weaker record fails
+  --dmarc-sp <p>          require at least this subdomain policy (sp, else p)
+  --dmarc-adkim <a>       require this DKIM alignment (r or s; absent counts as r)
+  --dmarc-aspf <a>        require this SPF alignment (r or s; absent counts as r)
+  --reply-to <address>    check that this address's domain accepts mail (MX, one SPF)
+                          (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
 
-Options for both:
+Options for all:
   --config <file>    the app's softure.config file (bin only)
-  --help             show this help`;
+  --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`;
 
 const consoleOutput: CliOutput = {
   log: (line) => console.log(line),
@@ -78,12 +108,30 @@ type Command =
   | {
       readonly kind: "campaign";
       readonly contentFile: string;
-      readonly recipientsFile: string;
+      /** `null`: the module's `listCampaignRecipients`. */
+      readonly recipientsFile: string | null;
       readonly dryRun: boolean;
       readonly pauseMs: number;
       readonly resendUncertain: boolean;
     }
-  | { readonly kind: "dns"; readonly domain: string | undefined; readonly dkimSelectors: readonly string[] | undefined; readonly spfHosts: readonly string[] | undefined };
+  | { readonly kind: "import"; readonly historyFile: string; readonly dryRun: boolean }
+  | {
+      readonly kind: "dns";
+      readonly domain: string | undefined;
+      readonly dkimSelectors: readonly string[] | undefined;
+      readonly spfHosts: readonly string[] | undefined;
+      readonly expectDmarc: DmarcExpectation | undefined;
+      readonly replyTo: string | undefined;
+      readonly returnPathHosts: readonly string[];
+      readonly resendReturnPath: boolean;
+    };
+
+const DMARC_POLICIES: readonly DmarcPolicy[] = ["quarantine", "reject"];
+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"] 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"] 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> {
@@ -102,14 +150,16 @@ export async function runMailCli(options: RunMailCliOptions): Promise<number> {
       return runDns(command, options, output);
     case "campaign":
       return runCampaign(command, options, output);
+    case "import":
+      return runImport(command, options, output);
   }
 }
 
 function parseCommand(argv: readonly string[]): Command | string {
   const [name, ...rest] = argv;
-  if (name === undefined) return "missing command; use campaign or dns";
+  if (name === undefined) return "missing command; use campaign, import or dns";
   if (name === "--help") return { kind: "help" };
-  if (name !== "campaign" && name !== "dns") return `unknown command "${name}"; use campaign or dns`;
+  if (name !== "campaign" && name !== "import" && name !== "dns") return `unknown command "${name}"; use campaign, import or dns`;
 
   let parsed: ReturnType<typeof parseCommandArgs>;
   try {
@@ -121,21 +171,41 @@ function parseCommand(argv: readonly string[]): Command | string {
   if (values.help === true) return { kind: "help" };
 
   if (name === "dns") {
-    const misplaced = (["recipients", "dry-run", "pause-ms", "resend-uncertain"] as const).filter((option) => values[option] !== undefined);
+    const misplaced = ([...CAMPAIGN_ONLY_OPTIONS, "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(" ")}"`;
-    return { kind: "dns", domain: values.domain, dkimSelectors: values["dkim-selector"], spfHosts: values["spf-host"] };
+    const expectDmarc = parseDmarcExpectation(values);
+    if (typeof expectDmarc === "string") return expectDmarc;
+    return {
+      kind: "dns",
+      domain: values.domain,
+      dkimSelectors: values["dkim-selector"],
+      spfHosts: values["spf-host"],
+      expectDmarc,
+      replyTo: values["reply-to"],
+      returnPathHosts: values["return-path"] ?? [],
+      resendReturnPath: values["resend-return-path"] === true,
+    };
   }
 
-  const misplaced = (["domain", "dkim-selector", "spf-host"] as const).filter((option) => values[option] !== undefined);
+  if (name === "import") {
+    const misplaced = [...CAMPAIGN_ONLY_OPTIONS, ...DNS_ONLY_OPTIONS].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)";
+    if (extra.length > 0) return `import takes one history file, got also "${extra.join(" ")}"`;
+    return { kind: "import", historyFile, dryRun: values["dry-run"] === true };
+  }
+
+  const misplaced = 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(" ")}"`;
-  if (values.recipients === undefined) return "campaign needs --recipients <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"] ?? ""}"`;
-  return { kind: "campaign", contentFile, recipientsFile: values.recipients, dryRun: values["dry-run"] === true, pauseMs, resendUncertain: values["resend-uncertain"] === true };
+  return { kind: "campaign", contentFile, recipientsFile: values.recipients ?? null, dryRun: values["dry-run"] === true, pauseMs, resendUncertain: values["resend-uncertain"] === true };
 }
 
 function parseCommandArgs(args: readonly string[]) {
@@ -149,6 +219,13 @@ function parseCommandArgs(args: readonly string[]) {
       domain: { type: "string" },
       "dkim-selector": { type: "string", multiple: true },
       "spf-host": { type: "string", multiple: true },
+      "dmarc-policy": { type: "string" },
+      "dmarc-sp": { type: "string" },
+      "dmarc-adkim": { type: "string" },
+      "dmarc-aspf": { type: "string" },
+      "reply-to": { type: "string" },
+      "return-path": { type: "string", multiple: true },
+      "resend-return-path": { type: "boolean" },
       help: { type: "boolean" },
     },
     strict: true,
@@ -156,34 +233,82 @@ function parseCommandArgs(args: readonly string[]) {
   });
 }
 
+type ParsedValues = ReturnType<typeof parseCommandArgs>["values"];
+
+/** 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];
+  if (given === undefined) return { value: undefined };
+  const found = allowed.find((candidate) => candidate === given.trim().toLowerCase());
+  return found === undefined ? `--${option} expects ${allowed.join(" or ")}, got "${given}"` : { value: found };
+}
+
+function parseDmarcExpectation(values: ParsedValues): DmarcExpectation | undefined | string {
+  const policy = pickChoice(values, "dmarc-policy", DMARC_POLICIES);
+  if (typeof policy === "string") return policy;
+  const subdomainPolicy = pickChoice(values, "dmarc-sp", DMARC_POLICIES);
+  if (typeof subdomainPolicy === "string") return subdomainPolicy;
+  const adkim = pickChoice(values, "dmarc-adkim", DMARC_ALIGNMENTS);
+  if (typeof adkim === "string") return adkim;
+  const aspf = pickChoice(values, "dmarc-aspf", DMARC_ALIGNMENTS);
+  if (typeof aspf === "string") return aspf;
+  const expectation: DmarcExpectation = {
+    ...(policy.value === undefined ? {} : { policy: policy.value }),
+    ...(subdomainPolicy.value === undefined ? {} : { subdomainPolicy: subdomainPolicy.value }),
+    ...(adkim.value === undefined ? {} : { adkim: adkim.value }),
+    ...(aspf.value === undefined ? {} : { aspf: aspf.value }),
+  };
+  return Object.keys(expectation).length === 0 ? undefined : expectation;
+}
+
 async function runDns(command: Extract<Command, { kind: "dns" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
   let domain = command.domain;
+  let replyTo = command.replyTo;
   if (domain === undefined) {
     if (options.config === undefined) {
       output.error("softure-mail dns: pass --domain <domain>, or run it with the app's config to check the sender's domain");
       return EXIT_FAILED;
     }
-    domain = getSenderDomain(getMailingOptions(options.config).from);
+    const mailing = getMailingOptions(options.config);
+    domain = getSenderDomain(mailing.from);
+    replyTo ??= mailing.replyTo;
   }
+  const returnPath: ReturnPathHost[] = [...(command.resendReturnPath ? resendReturnPath(domain) : []), ...command.returnPathHosts.map((host) => ({ host }))];
   const report = await checkSenderDns(domain, {
     ...(command.dkimSelectors === undefined ? {} : { dkimSelectors: command.dkimSelectors }),
     ...(command.spfHosts === undefined ? {} : { spfHosts: command.spfHosts }),
+    ...(command.expectDmarc === undefined ? {} : { expectDmarc: command.expectDmarc }),
+    ...(replyTo === undefined ? {} : { replyTo }),
+    returnPath,
     ...(options.resolveTxt === undefined ? {} : { resolveTxt: options.resolveTxt }),
+    ...(options.resolveMx === undefined ? {} : { resolveMx: options.resolveMx }),
+    ...(options.resolveCname === undefined ? {} : { resolveCname: options.resolveCname }),
   });
-  const checks: [string, DnsCheck][] = [
+  const authentication: [string, DnsCheck][] = [
     ["SPF", report.spf],
     ["DKIM", report.dkim],
     ["DMARC", report.dmarc],
   ];
+  const reply: [string, DnsCheck][] = report.replyTo === null ? [] : [["REPLY", report.replyTo]];
+  const paths: [string, DnsCheck][] = report.returnPath.map((check) => ["PATH", check]);
   output.log(`sender domain ${report.domain}`);
-  for (const [name, check] of checks) {
-    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]) {
+    const line = `${name.padEnd(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);
   }
-  const failed = checks.filter(([, check]) => check.status === "fail").length;
-  output.log(failed === 0 ? "receivers can authenticate mail from this domain" : `${String(failed)} check(s) failed: list mail from this domain will land in spam or be refused`);
-  return failed === 0 ? EXIT_OK : EXIT_FAILED;
+  const countFailed = (checks: readonly [string, DnsCheck][]) => checks.filter(([, check]) => check.status === "fail").length;
+  const failedAuthentication = countFailed(authentication);
+  const failedReply = countFailed(reply);
+  const failedPaths = countFailed(paths);
+  if (failedAuthentication + failedReply + failedPaths === 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`);
+  return EXIT_FAILED;
 }
 
 async function runCampaign(command: Extract<Command, { kind: "campaign" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
@@ -193,9 +318,19 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
     output.error("softure-mail campaign: needs the app's config");
     return EXIT_FAILED;
   }
-  const loaded = await loadCampaign(resolve(cwd, command.contentFile), resolve(cwd, command.recipientsFile));
-  if (typeof loaded === "string") {
-    output.error(`softure-mail campaign: ${loaded}`);
+  const input = createInputReader(cwd, options.readStdin ?? readProcessStdin);
+  const content = await loadCampaignContent(command.contentFile, input);
+  if (typeof content === "string") {
+    output.error(`softure-mail campaign: ${content}`);
+    return EXIT_FAILED;
+  }
+  const listed = command.recipientsFile === null ? null : await loadRecipientFile(command.recipientsFile, input);
+  if (typeof listed === "string") {
+    output.error(`softure-mail campaign: ${listed}`);
+    return EXIT_FAILED;
+  }
+  if (listed === null && getMailingOptions(config).listCampaignRecipients === undefined) {
+    output.error("softure-mail campaign: pass --recipients <file>, or set listCampaignRecipients in the mailing options");
     return EXIT_FAILED;
   }
   if (!command.dryRun && readUnsubscribeSecrets(options.env ?? process.env).current === null) {
@@ -216,6 +351,7 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
   }
   const ctx: DeliveryContext = { db: opened.handle.db, clock: systemClock, config };
   try {
+    const loaded: LoadedCampaign = { campaign: content, recipients: listed ?? (await collectRecipients(ctx, content)) };
     return command.dryRun
       ? await reportPlan(ctx, loaded, command.resendUncertain, output)
       : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep, retakeUncertain: command.resendUncertain }, output);
@@ -233,22 +369,152 @@ interface LoadedCampaign {
   readonly recipients: readonly string[];
 }
 
-async function loadCampaign(contentPath: string, recipientsPath: string): Promise<LoadedCampaign | string> {
-  const source = await readText(contentPath);
-  if (source === null) return `cannot read the content file ${contentPath}`;
-  const parsed = parseCampaignFile(source);
-  if (!parsed.ok) return `${contentPath} is not a campaign:\n  ${parsed.problems.join("\n  ")}`;
+/** Reads a named file, or standard input for `-`; `name` is what messages call it. */
+interface InputReader {
+  readonly read: (file: string) => Promise<{ readonly text: string | null; readonly name: string; readonly dir: string }>;
+}
+
+function createInputReader(cwd: string, readStdin: () => Promise<string>): InputReader {
+  return {
+    read: async (file) => {
+      if (file === STDIN) return { text: await readStdin(), name: "standard input", dir: cwd };
+      const path = resolve(cwd, file);
+      return { text: await readText(path), name: path, dir: dirname(path) };
+    },
+  };
+}
+
+async function loadCampaignContent(file: string, input: InputReader): 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;
   let html: string | null = null;
   if (htmlPath !== null) {
-    const htmlFile = resolve(dirname(contentPath), htmlPath);
+    // Next to the content file; for standard input, the working directory.
+    const htmlFile = resolve(source.dir, htmlPath);
     html = await readText(htmlFile);
     if (html === null) return `cannot read the HTML body ${htmlFile}`;
     if (html.trim() === "") return `the HTML body ${htmlFile} is empty`;
   }
-  const list = await readText(recipientsPath);
-  if (list === null) return `cannot read the recipients file ${recipientsPath}`;
-  return { campaign: { ...content, html }, recipients: parseRecipientList(list) };
+  return { ...content, html };
+}
+
+async function loadRecipientFile(file: string, input: InputReader): Promise<readonly string[] | string> {
+  const list = await input.read(file);
+  if (list.text === null) return `cannot read the recipients file ${list.name}`;
+  return parseRecipientList(list.text);
+}
+
+/** The recipients from `listCampaignRecipients`, which the caller checked is set. */
+async function collectRecipients(ctx: DeliveryContext, campaign: CampaignContent): Promise<readonly string[]> {
+  const recipients: string[] = [];
+  const source = await listConfiguredCampaignRecipients(ctx, campaign);
+  if (source === null) return recipients;
+  for await (const address of source) recipients.push(address);
+  return recipients;
+}
+
+/** One line of a history file. Unknown keys are refused, so a typo does not drop a field. */
+const historyRowSchema = z.strictObject({
+  scope: z.string(),
+  address: z.string(),
+  status: z.enum(["sent", "rejected"]),
+  finishedAt: z.string(),
+  providerMessageId: z.string().optional(),
+  reason: z.enum(["mailing.invalid_input", "mailing.rejected", "mailing.unavailable", "mailing.suppressed"]).optional(),
+  kind: z.string().optional(),
+});
+
+async function runImport(command: Extract<Command, { kind: "import" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
+  const config = options.config;
+  if (config === undefined) {
+    output.error("softure-mail import: needs the app's config");
+    return EXIT_FAILED;
+  }
+  const source = await createInputReader(options.cwd ?? process.cwd(), options.readStdin ?? readProcessStdin).read(command.historyFile);
+  if (source.text === null) {
+    output.error(`softure-mail import: cannot read the history file ${source.name}`);
+    return EXIT_FAILED;
+  }
+  const parsed = parseHistory(source.text);
+  if (parsed.problems.length > 0) return reportImportProblems(parsed.problems, output);
+  const rows = parsed.rows.map((row) => row.delivery);
+  const lineOf = (problem: ImportProblem) => parsed.rows[problem.index]?.line ?? 0;
+
+  // Checked before the database is opened, so a bad file costs no connection.
+  const checked = checkImportedDeliveries({ clock: systemClock }, rows);
+  if (!checked.ok) return reportImportProblems(checked.problems.map((problem) => ({ line: lineOf(problem), problem: problem.problem })), output);
+  if (command.dryRun) {
+    output.log(`import, dry run: nothing written; rows ${String(rows.length)}, duplicates ${String(checked.value.duplicates)}`);
+    return EXIT_OK;
+  }
+  if (config.database === null) {
+    output.error("softure-mail import: the config has no database; 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 import: ${describeError(error)}`);
+    return EXIT_FAILED;
+  }
+  try {
+    const result = await importDeliveries({ db: opened.handle.db, clock: systemClock, config }, rows);
+    if (!result.ok) return reportImportProblems(result.problems.map((problem) => ({ line: lineOf(problem), problem: problem.problem })), output);
+    const summary = result.value;
+    output.log(`import: rows ${String(summary.rows)}, imported ${String(summary.imported)}, already present ${String(summary.alreadyPresent)}, duplicates ${String(summary.duplicates)}`);
+    return EXIT_OK;
+  } catch (error) {
+    output.error(`softure-mail import: ${describeError(error)} (did softure migrate run?)`);
+    return EXIT_FAILED;
+  } finally {
+    await opened.close();
+  }
+}
+
+interface LineProblem {
+  readonly line: number;
+  readonly problem: string;
+}
+
+/** The history file's rows with their line numbers; problems name lines and fields, never values. */
+function parseHistory(text: string): { readonly rows: readonly { readonly line: number; readonly delivery: ImportedDelivery }[]; readonly problems: readonly LineProblem[] } {
+  const rows: { line: number; delivery: ImportedDelivery }[] = [];
+  const problems: LineProblem[] = [];
+  text.split(/\r?\n/).forEach((source, index) => {
+    const line = index + 1;
+    if (source.trim() === "") return;
+    let value: unknown;
+    try {
+      value = JSON.parse(source);
+    } catch {
+      problems.push({ line, problem: "not a JSON object" });
+      return;
+    }
+    const parsed = historyRowSchema.safeParse(value);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        const field = issue.path.length === 0 ? "row" : issue.path.join(".");
+        problems.push({ line, problem: issue.code === "unrecognized_keys" ? `unknown field(s) ${issue.keys.join(", ")}` : `${field}: ${issue.message}` });
+      }
+      return;
+    }
+    const { providerMessageId, reason, kind, ...required } = parsed.data;
+    rows.push({
+      line,
+      delivery: { ...required, ...(providerMessageId === undefined ? {} : { providerMessageId }), ...(reason === undefined ? {} : { reason }), ...(kind === undefined ? {} : { kind }) },
+    });
+  });
+  return { rows, problems };
+}
+
+function reportImportProblems(problems: readonly LineProblem[], output: CliOutput): number {
+  output.error(`softure-mail import: nothing written, ${String(problems.length)} problem(s):`);
+  for (const { line, problem } of problems) output.error(`  line ${String(line)}: ${problem}`);
+  return EXIT_FAILED;
 }
 
 async function reportPlan(ctx: DeliveryContext, loaded: LoadedCampaign, retakeUncertain: boolean, output: CliOutput): Promise<number> {
@@ -341,6 +607,12 @@ async function openDatabase(database: SoftureDatabaseConfig, open: ((url: string
   return { handle, close: handle.close };
 }
 
+async function readProcessStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : (chunk as Buffer));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
 async function readText(path: string): Promise<string | null> {
   try {
     return await readFile(path, "utf8");

package/src/contract.ts

@@ -32,11 +32,18 @@ export const TRANSACTIONAL_KIND = "transactional";
 /** How an opt-out arrived: a mail client's one-click POST, the page's button, or an operator. */
 export type SuppressionSource = "one-click" | "page" | "operator";
 
-/** What `onUnsubscribed` receives: who opted out (never the address) and how. */
+/**
+ * The link an unsubscribe came through, once verified: the module's signed link, or a legacy link with the values
+ * the app's `verify` accepted (only the names the link carried), so a hook can find the row that link named.
+ */
+export type VerifiedUnsubscribeLink = { readonly scheme: "signed" } | { readonly scheme: "legacy"; readonly values: Readonly<Record<string, string>> };
+
+/** What `onUnsubscribed` receives: who opted out (never the address), how, and through which link. */
 export interface UnsubscribeEvent {
   /** The recipient key of the link: privacy's email key of the same address (`getEmailKey`). */
   readonly recipientKey: string;
   readonly source: Exclude<SuppressionSource, "operator">;
+  readonly link: VerifiedUnsubscribeLink;
 }
 
 /**
@@ -61,14 +68,32 @@ export interface CampaignRecipient {
  */
 export type CampaignRecipientFilter = (recipient: CampaignRecipient, ctx: ModuleContext<Queryable>) => Promise<boolean>;
 
+/**
+ * Lists the addresses a campaign goes to, from the app's own data (e.g. the people who opted in to its kind), so a
+ * campaign can run where the database is without a recipients file. Duplicates are fine; `filterCampaignRecipient`
+ * and the suppression list still apply. A throw stops the campaign. Set in `mailing({ listCampaignRecipients })`.
+ */
+export type CampaignRecipientSource = (
+  campaign: { readonly id: string; readonly kind: string },
+  ctx: ModuleContext<Queryable>,
+) => Iterable<string> | AsyncIterable<string> | Promise<Iterable<string>>;
+
+/**
+ * The query names of a legacy link. An array lists names the link must all carry. The object form adds names it
+ * may carry: a link is legacy when it has every `required` name, and the `optional` ones it has go to `verify` too.
+ * At most 8 names in all, none repeated, never `r` or `status`.
+ */
+export type LegacyUnsubscribeParams = readonly string[] | { readonly required: readonly string[]; readonly optional?: readonly string[] };
+
 /**
  * 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.
+ * 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.
  */
 export interface LegacyUnsubscribe {
-  readonly params: readonly string[];
+  readonly params: LegacyUnsubscribeParams;
   readonly verify: (values: Readonly<Record<string, string>>, ctx: ModuleContext<Queryable>) => Promise<string | null>;
 }
 

package/src/index.ts

@@ -17,7 +17,7 @@ export const MODULE_ID = "mailing";
 export const mailing = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.7",
+    version: "0.1.9",
     dependsOn: {},
     dbSchema: "mailing",
     tables: ["suppressions", "campaigns", "deliveries"],
@@ -68,7 +68,9 @@ export { HALTING_ERROR_CODES, TRANSACTIONAL_KIND } from "./contract.js";
 export type {
   CampaignRecipient,
   CampaignRecipientFilter,
+  CampaignRecipientSource,
   LegacyUnsubscribe,
+  LegacyUnsubscribeParams,
   MailingErrorCode,
   MailProvider,
   OnUnsubscribedHook,
@@ -83,6 +85,7 @@ export type {
   SuppressionSource,
   UnsubscribeErrorCode,
   UnsubscribeEvent,
+  VerifiedUnsubscribeLink,
 } from "./contract.js";
 export { getMailingErrorMessage, mailingMessages, type MailingMessages } from "./messages/index.js";
 export { DEFAULT_STALE_CLAIM_MS, DEFAULT_TIMEOUT_MS, DEFAULT_UNCERTAIN_CLAIM_MS, type MailingOptions, type MailingOptionsInput } from "./options.js";

package/src/next/import-deliveries.ts

@@ -0,0 +1,9 @@
+// `importDeliveries` on the app's registered configuration and the shared database, e.g. for a one-off route or
+// script that seeds the ledger from the app's own history.
+import { importDeliveries as importDeliveriesWithContext, type ImportedDelivery, type ImportResult } from "../server/import-deliveries.js";
+import { getMailingContext } from "./context.js";
+
+/** Seeds the delivery ledger; see `importDeliveries` in `@softure-ai/mailing/server`. */
+export async function importDeliveries(rows: readonly ImportedDelivery[]): Promise<ImportResult> {
+  return importDeliveriesWithContext(await getMailingContext(), rows);
+}

package/src/next/index.ts

@@ -3,6 +3,7 @@
 // (docs/02-module-standard.md §8).
 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 { UNSUBSCRIBE_STATUS_PARAM, type UnsubscribeStatus } from "./params.js";

package/src/next/route.ts

@@ -10,7 +10,7 @@
 // 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 { getMailingOptions, getMailingRoutes } from "../server/options.js";
 import { unsubscribe } from "../server/suppressions.js";
 import { readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { getMailingContext } from "./context.js";
@@ -20,8 +20,9 @@ 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. A legacy link (`mailing({ legacyUnsubscribe })`) is handled the same
+ * that does not verify (200 with `mailing({ oneClickInvalidLinkStatus: 200 })`, so the answer never
+ * tells whether a token is live), 500 when the database fails: the client may retry, and 200 would
+ * claim an 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> {
@@ -29,7 +30,7 @@ export async function postUnsubscribeRoute(request: Request): Promise<Response>
     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 });
+    return new Response(null, { status: result.ok ? 200 : getMailingOptions(ctx.config).oneClickInvalidLinkStatus, 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 });