@softure-ai/mailing 0.1.7 → 0.1.9

package/src/options.ts

@@ -1,7 +1,7 @@
 // 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 { CampaignRecipientFilter, LegacyUnsubscribe, MailProvider, OnUnsubscribedHook } from "./contract.js";
+import type { CampaignRecipientFilter, CampaignRecipientSource, LegacyUnsubscribe, MailProvider, OnUnsubscribedHook } from "./contract.js";
 
 export const DEFAULT_TIMEOUT_MS = 10_000;
 /** How long a delivery claim may stay open before another sender may take it over (and send again, same key). */
@@ -11,18 +11,32 @@ export const DEFAULT_STALE_CLAIM_MS = 15 * 60_000;
  * the provider may have forgotten the idempotency key (Resend keeps one for 24 hours), so a retake could mail twice.
  */
 export const DEFAULT_UNCERTAIN_CLAIM_MS = 23 * 60 * 60_000;
+/**
+ * Claims a delivery gets before `mailing.unavailable` becomes its final outcome. A short outage across a few runs is
+ * ridden out, while a provider that keeps failing on one mail does not keep it open forever.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 5;
 
 /** Query names the signed link and the page use; a legacy link cannot claim them. */
 const RESERVED_LINK_PARAMS: ReadonlySet<string> = new Set(["r", "status"]);
 const LINK_PARAM = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
 
+const MAX_LINK_PARAMS = 8;
+const linkParamNames = z.array(z.string().regex(LINK_PARAM, "must be a query name: a letter, then letters, digits, _ or -, at most 32 characters"));
+
+/** Both forms of `params`, normalised to required and optional names, with the limits on all names together. */
+const legacyParamsSchema = z
+  .union([linkParamNames.min(1), z.strictObject({ required: linkParamNames.min(1), optional: linkParamNames.default([]) })])
+  .transform((params) => (Array.isArray(params) ? { required: params, optional: [] } : params))
+  .refine(({ required, optional }) => required.length + optional.length <= MAX_LINK_PARAMS, `must name at most ${String(MAX_LINK_PARAMS)} parameters`)
+  .refine(({ required, optional }) => new Set([...required, ...optional]).size === required.length + optional.length, "must not repeat a name")
+  .refine(
+    ({ required, optional }) => [...required, ...optional].every((param) => !RESERVED_LINK_PARAMS.has(param)),
+    "must not use r or status: the signed link and the page own them",
+  );
+
 const legacyUnsubscribeSchema = z.strictObject({
-  params: z
-    .array(z.string().regex(LINK_PARAM, "must be a query name: a letter, then letters, digits, _ or -, at most 32 characters"))
-    .min(1)
-    .max(8)
-    .refine((params) => new Set(params).size === params.length, "must not repeat a name")
-    .refine((params) => params.every((param) => !RESERVED_LINK_PARAMS.has(param)), "must not use r or status: the signed link and the page own them"),
+  params: legacyParamsSchema,
   verify: z.custom<LegacyUnsubscribe["verify"]>((value) => typeof value === "function", "must be a function"),
 });
 
@@ -53,8 +67,23 @@ export const mailingOptionsSchema = z.strictObject({
   onUnsubscribed: z.custom<OnUnsubscribedHook>((value) => typeof value === "function", "must be a function").optional(),
   /** Verifies unsubscribe links the app sent before it adopted the module (see `LegacyUnsubscribe`). */
   legacyUnsubscribe: legacyUnsubscribeSchema.optional(),
+  /**
+   * What the one-click route answers for a link that does not verify: 400 (the default), or 200 so the answer never
+   * tells whether a token is live. A failure still answers 500, so the mail client retries; the page is unaffected.
+   */
+  oneClickInvalidLinkStatus: z.union([z.literal(200), z.literal(400)]).default(400),
   /** Decides per recipient whether a campaign goes to them, e.g. by consent scope (see `CampaignRecipientFilter`). */
   filterCampaignRecipient: z.custom<CampaignRecipientFilter>((value) => typeof value === "function", "must be a function").optional(),
+  /**
+   * Lists a campaign's recipients from the app's data; `softure-mail campaign` uses it when no `--recipients` file
+   * is given (see `CampaignRecipientSource`).
+   */
+  listCampaignRecipients: z.custom<CampaignRecipientSource>((value) => typeof value === "function", "must be a function").optional(),
+  /**
+   * Claims a delivery gets before `mailing.unavailable` closes it as rejected, 1 to 100; `null` never closes it, for
+   * apps that retry on their own schedule. Default 5.
+   */
+  maxAttempts: z.number().int().min(1).max(100).nullable().default(DEFAULT_MAX_ATTEMPTS),
   /** How long a delivery claim may stay open before another sender takes it over. 1 minute to 23 hours. */
   staleClaimMs: z.number().int().min(60_000).max(23 * HOUR_MS).default(DEFAULT_STALE_CLAIM_MS),
   /**

package/src/schema.ts

@@ -33,6 +33,8 @@ export const deliveries = mailingSchema.table(
     reason: text("reason"),
     /** The provider's HTTP status of the last answer that failed or was released; null when there was none. */
     providerStatus: integer("provider_status"),
+    /** When `importDeliveries` wrote the row; null for a delivery the module made. */
+    importedAt: timestamp("imported_at", { withTimezone: true }),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
   },
   (table) => [primaryKey({ columns: [table.scope, table.recipientKey] })],

package/src/server/campaigns.ts

@@ -135,6 +135,19 @@ function createRecipientFilter(ctx: DeliveryContext, campaign: CampaignContent):
   };
 }
 
+/**
+ * The campaign's recipients from the module's `listCampaignRecipients`, or `null` when the app set none. Throws
+ * what the app's function throws.
+ */
+export async function listConfiguredCampaignRecipients(
+  ctx: DeliveryContext,
+  campaign: Pick<CampaignContent, "id" | "kind">,
+): Promise<Iterable<string> | AsyncIterable<string> | null> {
+  const source = getMailingOptions(ctx.config).listCampaignRecipients;
+  if (source === undefined) return null;
+  return source({ id: campaign.id, kind: campaign.kind }, ctx);
+}
+
 export interface CampaignPlan {
   readonly recipients: number;
   /** Already closed by an earlier run. */

package/src/server/deliveries.ts

@@ -10,7 +10,7 @@ import type { Queryable } from "@softure-ai/db";
 import { and, eq, gte, lt, or, sql, type SQL } from "drizzle-orm";
 import { isMailKind } from "../address.js";
 import { HALTING_ERROR_CODES, TRANSACTIONAL_KIND, type MailingErrorCode, type OutgoingMail } from "../contract.js";
-import { DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS } from "../options.js";
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS } from "../options.js";
 import { deliveries } from "../schema.js";
 import { getMailingOptions } from "./options.js";
 import { sendMail } from "./send-mail.js";
@@ -18,9 +18,7 @@ import { getRecipientKey } from "./unsubscribe-link.js";
 
 export type DeliveryContext = ModuleContext<Queryable>;
 
-export { DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS };
-/** Claims a delivery gets before `mailing.unavailable` becomes its final outcome. */
-export const DEFAULT_MAX_ATTEMPTS = 5;
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS };
 
 const MAX_SCOPE_LENGTH = 128;
 const SCOPE = /^[a-z0-9][a-z0-9._:-]*$/;
@@ -48,7 +46,11 @@ export interface DeliverOptions {
    * An operator's decision, e.g. `softure-mail campaign --resend-uncertain`. Default false.
    */
   readonly retakeUncertain?: boolean;
-  readonly maxAttempts?: number;
+  /**
+   * Claims before `mailing.unavailable` closes the delivery as rejected; `null` never closes it. Default: the module's
+   * `maxAttempts` (5).
+   */
+  readonly maxAttempts?: number | null;
 }
 
 /** The codes that stop a run: the sending account, not the mail, is the problem. */
@@ -84,7 +86,7 @@ export type DeliveryOutcome =
  */
 export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryOutcome> {
   const windows = resolveClaimWindows(ctx, options);
-  const { maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
+  const maxAttempts = options.maxAttempts === undefined ? getMailingOptions(ctx.config).maxAttempts : options.maxAttempts;
   const kind = delivery.mail.kind ?? TRANSACTIONAL_KIND;
   assertDelivery(delivery, kind);
 
@@ -105,7 +107,7 @@ export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, opti
     await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: true });
     return { status: "halted", reason: result.error, ...httpStatus };
   }
-  if (result.error === "mailing.unavailable" && attempt < maxAttempts) {
+  if (result.error === "mailing.unavailable" && (maxAttempts === null || attempt < maxAttempts)) {
     await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: false });
     return { status: "retry-later", ...httpStatus };
   }
@@ -134,8 +136,13 @@ function resolveClaimWindows(ctx: DeliveryContext, options: DeliverOptions): Cla
   return { staleClaimMs, uncertainClaimMs, retakeUncertain: options.retakeUncertain ?? false };
 }
 
+/** Lowercase letters, digits and `._:-`, at most 128 characters. */
+export function isDeliveryScope(scope: string): boolean {
+  return scope.length <= MAX_SCOPE_LENGTH && SCOPE.test(scope);
+}
+
 function assertDelivery(delivery: Delivery, kind: string): void {
-  if (delivery.scope.length > MAX_SCOPE_LENGTH || !SCOPE.test(delivery.scope)) {
+  if (!isDeliveryScope(delivery.scope)) {
     throw new Error(`@softure-ai/mailing: deliverOnce scope "${delivery.scope}" must be lowercase letters, digits and ._:- (at most 128 characters)`);
   }
   if (!isMailKind(kind)) {

package/src/server/dns.ts

@@ -1,7 +1,9 @@
 // The sender domain's DNS, as receivers check it: SPF (RFC 7208), DKIM (RFC 6376) and DMARC
-// (RFC 7489). Without all three, list mail lands in spam or is refused outright. The check only
-// reads public TXT records; it cannot see whether the provider signs with the published key.
-import { resolveTxt as resolveTxtRecords } from "node:dns/promises";
+// (RFC 7489). Without all three, list mail lands in spam or is refused outright. On request it also
+// holds DMARC to a required minimum, checks that the reply-to domain accepts mail (MX) and that the
+// provider's return-path hosts resolve. The check only reads public records; it cannot see whether
+// the provider signs with the published key.
+import { resolveCname as resolveCnameRecords, resolveMx as resolveMxRecords, resolveTxt as resolveTxtRecords } from "node:dns/promises";
 
 export type DnsCheckStatus = "pass" | "warn" | "fail";
 
@@ -13,6 +15,9 @@ export type DnsFinding =
   | "revoked"
   | "monitor-only"
   | "inherited"
+  | "weak"
+  | "null-mx"
+  | "unexpected-target"
   | "lookup-failed";
 
 export interface DnsCheck {
@@ -29,9 +34,41 @@ export interface SenderDnsReport {
   readonly spf: DnsCheck;
   readonly dkim: DnsCheck;
   readonly dmarc: DnsCheck;
+  /** The reply-to domain's MX, when `replyTo` was given. */
+  readonly replyTo: DnsCheck | null;
+  /** One check per `returnPath` host, in the order given. */
+  readonly returnPath: readonly DnsCheck[];
 }
 
 export type ResolveTxt = (hostname: string) => Promise<string[][]>;
+export interface MxRecord {
+  readonly exchange: string;
+  readonly priority: number;
+}
+export type ResolveMx = (hostname: string) => Promise<MxRecord[]>;
+export type ResolveCname = (hostname: string) => Promise<string[]>;
+
+export type DmarcPolicy = "quarantine" | "reject";
+export type DmarcAlignment = "r" | "s";
+
+/** The least a DMARC record must carry; a weaker one fails as `weak`. Absent tags count as their defaults. */
+export interface DmarcExpectation {
+  /** The policy for the checked domain: `p`, or `sp ?? p` of a parent's record. Also requires `pct` 100. */
+  readonly policy?: DmarcPolicy;
+  /** The policy for subdomains: `sp ?? p`. */
+  readonly subdomainPolicy?: DmarcPolicy;
+  /** `adkim`; absent means relaxed (`r`). */
+  readonly adkim?: DmarcAlignment;
+  /** `aspf`; absent means relaxed (`r`). */
+  readonly aspf?: DmarcAlignment;
+}
+
+/** A host the provider uses for MAIL FROM or bounces. */
+export interface ReturnPathHost {
+  readonly host: string;
+  /** When set, a CNAME must point at this domain or under it (`rmta.net` accepts `send.forge.rmta.net`). */
+  readonly targetDomain?: string;
+}
 
 export interface CheckSenderDnsOptions {
   /** DKIM selectors to look up under `_domainkey`. Default `["resend"]`, the Resend selector. */
@@ -41,22 +78,52 @@ export interface CheckSenderDnsOptions {
    * return path); DMARC accepts that in relaxed alignment.
    */
   readonly spfHosts?: readonly string[];
+  /** Turns a DMARC record weaker than this into a `fail` (e.g. `{ policy: "reject", adkim: "s", aspf: "s" }`). */
+  readonly expectDmarc?: DmarcExpectation;
+  /**
+   * Where replies go (an address, `Name <address>` or a domain): its domain must have MX records and at most one
+   * SPF record, or replies bounce while the sender checks pass.
+   */
+  readonly replyTo?: string;
+  /** Hosts that must resolve as a CNAME or with MX records; `resendReturnPath(domain)` gives Resend's. */
+  readonly returnPath?: readonly ReturnPathHost[];
   readonly resolveTxt?: ResolveTxt;
+  readonly resolveMx?: ResolveMx;
+  readonly resolveCname?: ResolveCname;
 }
 
 export const DEFAULT_DKIM_SELECTORS: readonly string[] = ["resend"];
 
+/** Domain of the CNAME targets Resend publishes for its return-path hosts. */
+export const RESEND_RETURN_PATH_DOMAIN = "rmta.net";
+
+/**
+ * Resend's return-path hosts: `send.<domain>` (MAIL FROM) and `rsend.<domain>`, CNAMEs to `*.rmta.net`. Domains
+ * set up before Resend published `rsend` have MX records on `send` and no `rsend`: check `send` alone there.
+ */
+export function resendReturnPath(domain: string): ReturnPathHost[] {
+  const name = normalizeHost(domain);
+  return [
+    { host: `send.${name}`, targetDomain: RESEND_RETURN_PATH_DOMAIN },
+    { host: `rsend.${name}`, targetDomain: RESEND_RETURN_PATH_DOMAIN },
+  ];
+}
+
 /** Reads the SPF, DKIM and DMARC records of `domain`. Never throws: a failed lookup is a finding. */
 export async function checkSenderDns(domain: string, options: CheckSenderDnsOptions = {}): Promise<SenderDnsReport> {
-  const name = domain.trim().toLowerCase().replace(/\.$/, "");
+  const name = normalizeHost(domain);
   const resolveTxt = options.resolveTxt ?? resolveTxtRecords;
   const lookup = (host: string) => lookupTxt(resolveTxt, host);
-  const [spf, dkim, dmarc] = await Promise.all([
+  const lookupMx = (host: string) => lookupRecords(options.resolveMx ?? resolveMxRecords, host);
+  const lookupCname = (host: string) => lookupRecords(options.resolveCname ?? resolveCnameRecords, host);
+  const [spf, dkim, dmarc, replyTo, returnPath] = await Promise.all([
     checkSpf(lookup, options.spfHosts ?? [name]),
     checkDkim(lookup, (options.dkimSelectors ?? DEFAULT_DKIM_SELECTORS).map((selector) => `${selector}._domainkey.${name}`)),
-    checkDmarc(lookup, name),
+    checkDmarc(lookup, name, options.expectDmarc),
+    options.replyTo === undefined ? null : checkReplyPath(lookup, lookupMx, normalizeHost(getSenderDomain(options.replyTo))),
+    Promise.all((options.returnPath ?? []).map((path) => checkReturnPath(lookupCname, lookupMx, path))),
   ]);
-  return { domain: name, spf, dkim, dmarc };
+  return { domain: name, spf, dkim, dmarc, replyTo, returnPath };
 }
 
 /** The domain part of a sender (`Plan <hello@mail.example.com>` gives `mail.example.com`). */
@@ -69,15 +136,21 @@ export function getSenderDomain(from: string): string {
   return address.slice(address.lastIndexOf("@") + 1).trim().toLowerCase();
 }
 
+function normalizeHost(host: string): string {
+  return host.trim().toLowerCase().replace(/\.$/, "");
+}
+
+type Answer<T> = { readonly kind: "records"; readonly records: T[] } | { readonly kind: "none" } | { readonly kind: "error" };
+type TxtAnswer = Answer<string>;
 type Lookup = (host: string) => Promise<TxtAnswer>;
-type TxtAnswer = { readonly kind: "records"; readonly records: string[] } | { readonly kind: "none" } | { readonly kind: "error" };
+type MxLookup = (host: string) => Promise<Answer<MxRecord>>;
+type CnameLookup = (host: string) => Promise<Answer<string>>;
 
 const NO_RECORD_CODES = new Set(["ENOTFOUND", "ENODATA", "NXDOMAIN"]);
 
-async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswer> {
+async function lookupRecords<T>(resolve: (host: string) => Promise<T[]>, host: string): Promise<Answer<T>> {
   try {
-    // A TXT record may arrive in 255-byte chunks; they form one string.
-    const records = (await resolveTxt(host)).map((chunks) => chunks.join(""));
+    const records = await resolve(host);
     return records.length === 0 ? { kind: "none" } : { kind: "records", records };
   } catch (error) {
     const code = (error as { code?: unknown } | null)?.code;
@@ -85,6 +158,15 @@ async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswe
   }
 }
 
+async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswer> {
+  // A TXT record may arrive in 255-byte chunks; they form one string.
+  return lookupRecords(async (name) => (await resolveTxt(name)).map((chunks) => chunks.join("")), host);
+}
+
+function isSpfRecord(record: string): boolean {
+  return /^v=spf1(\s|$)/i.test(record.trim());
+}
+
 function startsWithTag(record: string, tag: string): boolean {
   return record.trim().toLowerCase().startsWith(tag);
 }
@@ -98,7 +180,7 @@ async function checkSpf(lookup: Lookup, hosts: readonly string[]): Promise<DnsCh
       lookupFailed ??= host;
       continue;
     }
-    const records = answer.kind === "records" ? answer.records.filter((record) => /^v=spf1(\s|$)/i.test(record.trim())) : [];
+    const records = answer.kind === "records" ? answer.records.filter(isSpfRecord) : [];
     if (records.length > 1) return { status: "fail", finding: "multiple", host, record: null };
     const record = records[0];
     if (record === undefined) continue;
@@ -129,9 +211,10 @@ async function checkDkim(lookup: Lookup, hosts: readonly string[]): Promise<DnsC
 
 /**
  * `_dmarc.<domain>`, or the nearest parent's record (the organisational domain's policy, with
- * `sp=` for subdomains when it is set). `p=none` only reports; it protects nothing.
+ * `sp=` for subdomains when it is set). `p=none` only reports; it protects nothing. With an
+ * expectation, a record weaker than it fails as `weak`.
  */
-async function checkDmarc(lookup: Lookup, domain: string): Promise<DnsCheck> {
+async function checkDmarc(lookup: Lookup, domain: string, expected: DmarcExpectation | undefined): Promise<DnsCheck> {
   const labels = domain.split(".");
   const first = `_dmarc.${domain}`;
   for (let index = 0; index <= labels.length - 2; index += 1) {
@@ -144,10 +227,85 @@ async function checkDmarc(lookup: Lookup, domain: string): Promise<DnsCheck> {
     const record = records[0];
     if (record === undefined) continue;
     const inherited = host !== first;
-    const tag = (name: string) => new RegExp(`(?:^|;)\\s*${name}=([^;]*)`, "i").exec(record)?.[1]?.trim().toLowerCase();
-    const policy = (inherited ? (tag("sp") ?? tag("p")) : tag("p")) ?? "none";
+    const tags = readDmarcTags(record);
+    const policy = (inherited ? (tags.get("sp") ?? tags.get("p")) : tags.get("p")) ?? "none";
+    if (expected !== undefined && !meetsDmarcExpectation(tags, policy, expected)) return { status: "fail", finding: "weak", host, record };
     if (policy === "none") return { status: "warn", finding: "monitor-only", host, record };
     return inherited ? { status: "pass", finding: "inherited", host, record } : { status: "pass", finding: "found", host, record };
   }
   return { status: "fail", finding: "missing", host: first, record: null };
 }
+
+/** `tag=value` pairs of a DMARC record, names and values lower-cased; the first occurrence wins. */
+function readDmarcTags(record: string): Map<string, string> {
+  const tags = new Map<string, string>();
+  for (const part of record.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) continue;
+    const name = part.slice(0, separator).trim().toLowerCase();
+    if (!tags.has(name)) tags.set(name, part.slice(separator + 1).trim().toLowerCase());
+  }
+  return tags;
+}
+
+const POLICY_RANK: Readonly<Record<string, number>> = { none: 0, quarantine: 1, reject: 2 };
+
+/** An unknown policy value counts as `none`, as receivers treat an invalid `p=`. */
+function rankPolicy(policy: string | undefined): number {
+  return (policy === undefined ? undefined : POLICY_RANK[policy]) ?? 0;
+}
+
+function meetsAlignment(actual: string | undefined, expected: DmarcAlignment | undefined): boolean {
+  return expected !== "s" || actual === "s";
+}
+
+function meetsDmarcExpectation(tags: ReadonlyMap<string, string>, policy: string, expected: DmarcExpectation): boolean {
+  if (expected.policy !== undefined) {
+    if (rankPolicy(policy) < rankPolicy(expected.policy)) return false;
+    const percent = tags.get("pct");
+    if (percent !== undefined && Number(percent) !== 100) return false;
+  }
+  if (expected.subdomainPolicy !== undefined && rankPolicy(tags.get("sp") ?? tags.get("p")) < rankPolicy(expected.subdomainPolicy)) return false;
+  return meetsAlignment(tags.get("adkim"), expected.adkim) && meetsAlignment(tags.get("aspf"), expected.aspf);
+}
+
+function formatMx(records: readonly MxRecord[]): string {
+  return [...records]
+    .sort((left, right) => left.priority - right.priority)
+    .map((record) => `${String(record.priority)} ${normalizeHost(record.exchange) || "."}`)
+    .join(", ");
+}
+
+/** A null MX (RFC 7505: one record, exchange `.`) says the domain accepts no mail. Node reports it as `""`. */
+function isNullMx(records: readonly MxRecord[]): boolean {
+  return records.length === 1 && normalizeHost(records[0]?.exchange ?? "") === "";
+}
+
+/** The reply-to domain must accept mail (MX, not a null MX) and publish at most one SPF record. */
+async function checkReplyPath(lookup: Lookup, lookupMx: MxLookup, host: string): Promise<DnsCheck> {
+  const mx = await lookupMx(host);
+  if (mx.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (mx.kind === "none") return { status: "fail", finding: "missing", host, record: null };
+  if (isNullMx(mx.records)) return { status: "fail", finding: "null-mx", host, record: formatMx(mx.records) };
+  const txt = await lookup(host);
+  if (txt.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (txt.kind === "records" && txt.records.filter(isSpfRecord).length > 1) return { status: "fail", finding: "multiple", host, record: null };
+  return { status: "pass", finding: "found", host, record: formatMx(mx.records) };
+}
+
+/** A CNAME (to `targetDomain` or under it, when set), else MX records. Strings, not patterns: the domain is input. */
+async function checkReturnPath(lookupCname: CnameLookup, lookupMx: MxLookup, path: ReturnPathHost): Promise<DnsCheck> {
+  const host = normalizeHost(path.host);
+  const cname = await lookupCname(host);
+  if (cname.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (cname.kind === "records") {
+    const target = normalizeHost(cname.records[0] ?? "");
+    const expected = path.targetDomain === undefined ? null : normalizeHost(path.targetDomain);
+    const matches = expected === null || target === expected || target.endsWith(`.${expected}`);
+    return matches ? { status: "pass", finding: "found", host, record: target } : { status: "fail", finding: "unexpected-target", host, record: target };
+  }
+  const mx = await lookupMx(host);
+  if (mx.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (mx.kind === "none" || isNullMx(mx.records)) return { status: "fail", finding: "missing", host, record: null };
+  return { status: "pass", finding: "found", host, record: formatMx(mx.records) };
+}

package/src/server/import-deliveries.ts

@@ -0,0 +1,149 @@
+// Seeds the delivery ledger with deliveries an app made before it adopted the module, so `deliverOnce` and
+// campaigns skip them. Every row is checked before anything is written; a row whose scope and recipient are
+// already in the ledger is left as it is (the ledger wins, and a live claim keeps its fence), so a re-run imports
+// nothing twice.
+import { isMailKind, isSingleAddress } from "../address.js";
+import { TRANSACTIONAL_KIND, type MailingErrorCode } from "../contract.js";
+import { deliveries } from "../schema.js";
+import { isDeliveryScope, type DeliveryContext } from "./deliveries.js";
+import { getRecipientKey } from "./unsubscribe-link.js";
+
+/** The reasons a rejected row may carry: the codes `deliverOnce` closes a row with. */
+export type ImportedRejectionReason = Extract<MailingErrorCode, "mailing.invalid_input" | "mailing.rejected" | "mailing.unavailable" | "mailing.suppressed">;
+
+const REJECTION_REASONS: ReadonlySet<string> = new Set<ImportedRejectionReason>(["mailing.invalid_input", "mailing.rejected", "mailing.unavailable", "mailing.suppressed"]);
+
+/** Rows written per statement. */
+const BATCH_SIZE = 500;
+
+export interface ImportedDelivery {
+  /** The scope `deliverOnce` will use for this mail: `campaign:<id>` for a campaign, else e.g. `billing.trial-ending:sub_42`. */
+  readonly scope: string;
+  /** The recipient's address; only its key is stored (any case or spacing gives the same key). */
+  readonly address: string;
+  readonly status: "sent" | "rejected";
+  /** When the delivery was closed; a `Date` or an ISO 8601 string, not in the future. */
+  readonly finishedAt: Date | string;
+  /** The provider's message id, when the app kept it. Only on `sent`. */
+  readonly providerMessageId?: string;
+  /** Why a rejected delivery is final. Only on `rejected`; default `mailing.rejected`. */
+  readonly reason?: ImportedRejectionReason;
+  /** The mail kind. Default `transactional`. */
+  readonly kind?: string;
+}
+
+export interface ImportProblem {
+  /** The row's index in the input (0-based). */
+  readonly index: number;
+  /** What is wrong, naming the field; never the address. */
+  readonly problem: string;
+}
+
+export interface ImportSummary {
+  /** Rows given. */
+  readonly rows: number;
+  /** Rows written now. */
+  readonly imported: number;
+  /** Rows whose scope and recipient the ledger already had (from an earlier import or a send); left as they were. */
+  readonly alreadyPresent: number;
+  /** Rows with the scope and recipient of an earlier row in the input; the first one counts. */
+  readonly duplicates: number;
+}
+
+/** The import's answer: a summary, or every problem (and nothing written). */
+export type ImportResult = { readonly ok: true; readonly value: ImportSummary } | { readonly ok: false; readonly problems: readonly ImportProblem[] };
+
+/** The checked rows, ready for the ledger, or every problem. */
+export type ImportCheck =
+  | { readonly ok: true; readonly value: { readonly ledgerRows: readonly LedgerRow[]; readonly duplicates: number } }
+  | { readonly ok: false; readonly problems: readonly ImportProblem[] };
+
+type LedgerRow = typeof deliveries.$inferInsert;
+
+/**
+ * Writes `rows` into `mailing.deliveries` as closed deliveries. Returns the problems, and writes nothing, when any
+ * row is invalid. Throws on a database failure; rows written before it stay, and a re-run skips them.
+ */
+export async function importDeliveries(ctx: DeliveryContext, rows: readonly ImportedDelivery[]): Promise<ImportResult> {
+  const checked = checkImportedDeliveries(ctx, rows);
+  if (!checked.ok) return checked;
+  const { ledgerRows, duplicates } = checked.value;
+
+  let imported = 0;
+  for (let start = 0; start < ledgerRows.length; start += BATCH_SIZE) {
+    const written = await ctx.db
+      .insert(deliveries)
+      .values(ledgerRows.slice(start, start + BATCH_SIZE))
+      .onConflictDoNothing({ target: [deliveries.scope, deliveries.recipientKey] })
+      .returning();
+    imported += written.length;
+  }
+  return { ok: true, value: { rows: rows.length, imported, alreadyPresent: ledgerRows.length - imported, duplicates } };
+}
+
+/**
+ * Checks every row and builds the ledger rows, without touching the database (e.g. for a dry run). The problems
+ * cover every invalid row, not only the first.
+ */
+export function checkImportedDeliveries(
+  ctx: Pick<DeliveryContext, "clock">,
+  rows: readonly ImportedDelivery[],
+): ImportCheck {
+  const now = ctx.clock.now();
+  const problems: ImportProblem[] = [];
+  const ledgerRows: LedgerRow[] = [];
+  const seen = new Set<string>();
+  let duplicates = 0;
+  rows.forEach((row, index) => {
+    const rowProblems = findRowProblems(row, now);
+    if (rowProblems.length > 0) {
+      problems.push(...rowProblems.map((problem) => ({ index, problem })));
+      return;
+    }
+    const recipientKey = getRecipientKey(row.address);
+    const key = `${row.scope}\n${recipientKey}`;
+    if (seen.has(key)) {
+      duplicates += 1;
+      return;
+    }
+    seen.add(key);
+    const finishedAt = new Date(row.finishedAt);
+    ledgerRows.push({
+      scope: row.scope,
+      recipientKey,
+      kind: row.kind ?? TRANSACTIONAL_KIND,
+      // Campaign rows are matched by scope; a campaign id would need the campaign's content, which history lacks.
+      campaignId: null,
+      status: row.status,
+      attempts: 1,
+      claimedAt: finishedAt,
+      finishedAt,
+      providerMessageId: row.status === "sent" ? (row.providerMessageId ?? null) : null,
+      reason: row.status === "rejected" ? (row.reason ?? "mailing.rejected") : null,
+      providerStatus: null,
+      createdAt: now,
+      importedAt: now,
+    });
+  });
+  return problems.length > 0 ? { ok: false, problems } : { ok: true, value: { ledgerRows, duplicates } };
+}
+
+function findRowProblems(row: ImportedDelivery, now: Date): string[] {
+  const problems: string[] = [];
+  if (!isDeliveryScope(row.scope)) problems.push("scope must be lowercase letters, digits and ._:- (at most 128 characters)");
+  if (!isSingleAddress(row.address.trim())) problems.push("address must be one email address");
+  if (row.status !== "sent" && row.status !== "rejected") problems.push('status must be "sent" or "rejected"');
+  const finishedAt = new Date(row.finishedAt);
+  if (Number.isNaN(finishedAt.getTime())) problems.push("finishedAt must be a date");
+  else if (finishedAt.getTime() > now.getTime()) problems.push("finishedAt must not be in the future");
+  if (row.providerMessageId !== undefined) {
+    if (row.status !== "sent") problems.push("providerMessageId belongs only to a sent row");
+    else if (row.providerMessageId.trim() === "" || row.providerMessageId.length > 256) problems.push("providerMessageId must be 1 to 256 characters");
+  }
+  if (row.reason !== undefined) {
+    if (row.status !== "rejected") problems.push("reason belongs only to a rejected row");
+    else if (!REJECTION_REASONS.has(row.reason)) problems.push(`reason must be one of ${[...REJECTION_REASONS].join(", ")}`);
+  }
+  if (row.kind !== undefined && !isMailKind(row.kind)) problems.push("kind must be kebab-case (at most 64 characters)");
+  return problems;
+}

package/src/server/index.ts

@@ -3,6 +3,7 @@
 export { getCampaignProblems, parseCampaignFile, parseRecipientList, type CampaignContent, type CampaignFile, type CampaignFileResult } from "./campaign-file.js";
 export {
   getCampaignContentHash,
+  listConfiguredCampaignRecipients,
   planCampaign,
   registerCampaign,
   sendCampaign,
@@ -17,6 +18,7 @@ export {
   DEFAULT_STALE_CLAIM_MS,
   DEFAULT_UNCERTAIN_CLAIM_MS,
   deliverOnce,
+  isDeliveryScope,
   type DeliverOptions,
   type Delivery,
   type DeliveryContext,
@@ -27,14 +29,33 @@ export {
   checkSenderDns,
   DEFAULT_DKIM_SELECTORS,
   getSenderDomain,
+  RESEND_RETURN_PATH_DOMAIN,
+  resendReturnPath,
   type CheckSenderDnsOptions,
+  type DmarcAlignment,
+  type DmarcExpectation,
+  type DmarcPolicy,
   type DnsCheck,
   type DnsCheckStatus,
   type DnsFinding,
+  type MxRecord,
+  type ResolveCname,
+  type ResolveMx,
   type ResolveTxt,
+  type ReturnPathHost,
   type SenderDnsReport,
 } from "./dns.js";
 export { checkMailingTables } from "./health.js";
+export {
+  checkImportedDeliveries,
+  importDeliveries,
+  type ImportCheck,
+  type ImportedDelivery,
+  type ImportedRejectionReason,
+  type ImportProblem,
+  type ImportResult,
+  type ImportSummary,
+} from "./import-deliveries.js";
 export { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders, SIGNATURE_SEPARATOR } from "./list-mail.js";
 export { getMailingModule, getMailingOptions, getMailingRoutes, type MailingRoutes } from "./options.js";
 export { sendMail, type MailContext } from "./send-mail.js";