@softure-ai/mailing 0.1.11 → 0.1.12

package/src/server/campaign-file.ts

@@ -11,8 +11,12 @@
 //
 // `html` is optional and names a file next to the content file, rendered however the operator
 // likes. There is no markdown: the text body is sent as written.
+import type { SoftureConfig } from "@softure-ai/core";
 import { isMailKind, MAX_SUBJECT_LENGTH } from "../address.js";
 import { TRANSACTIONAL_KIND } from "../contract.js";
+import type { MailingMessages } from "../messages/index.js";
+import { getMailingModule, getMailingRoutes } from "./options.js";
+import { RECIPIENT_PARAM, SIGNATURE_PARAM } from "./unsubscribe-link.js";
 
 /** A campaign's content, as `sendCampaign` sends it. */
 export interface CampaignContent {
@@ -75,8 +79,12 @@ export function parseCampaignFile(source: string): CampaignFileResult {
   return problems.length === 0 ? { ok: true, value: file } : { ok: false, problems };
 }
 
-/** What makes `content` unsendable as a campaign; empty when it is fine. */
-export function getCampaignProblems(content: CampaignContent): string[] {
+/**
+ * What makes `content` unsendable as a campaign; empty when it is fine. With the app's config it also refuses a
+ * body that carries an unsubscribe link or footer pasted from a sent mail: the module adds its own to every mail,
+ * and a pasted link is a credential that would let every recipient unsubscribe the person it was signed for.
+ */
+export function getCampaignProblems(content: CampaignContent, config?: SoftureConfig): string[] {
   const problems: string[] = [];
   if (content.id.length > MAX_CAMPAIGN_ID_LENGTH || !CAMPAIGN_ID.test(content.id)) {
     problems.push("id: kebab-case, at most 64 characters, e.g. 2026-10-launch");
@@ -89,6 +97,32 @@ export function getCampaignProblems(content: CampaignContent): string[] {
   }
   if (content.text.trim() === "") problems.push("the text body under the frontmatter is empty");
   if (content.html?.trim() === "") problems.push("the HTML body is empty");
+  if (config !== undefined) problems.push(...getPastedFooterProblems(content, config));
+  return problems;
+}
+
+/** A signed pair of link parameters, raw or HTML-escaped (`&`). */
+const SIGNED_LINK = new RegExp(`[?&](?:amp;)?${RECIPIENT_PARAM}=[A-Za-z0-9_-]{43}&(?:amp;)?${SIGNATURE_PARAM}=`);
+
+function getPastedFooterProblems(content: CampaignContent, config: SoftureConfig): string[] {
+  const routes = getMailingRoutes(config);
+  // The app's own links only: a link to another site's unsubscribe page is the author's business.
+  const linkMarkers = [`${config.appOrigin}${routes.unsubscribe}?`, `${config.appOrigin}${routes.oneClick}?`];
+  // Every locale's footer copy, the app's overrides included: a mail pasted from another locale counts too.
+  const footers = Object.values(getMailingModule(config).messages).map((messages) => (messages as MailingMessages).footer);
+  const bodies: [string, string | null][] = [
+    ["the text body", content.text],
+    ["the HTML body", content.html],
+  ];
+  const problems: string[] = [];
+  for (const [name, body] of bodies) {
+    if (body === null) continue;
+    if (SIGNED_LINK.test(body) || linkMarkers.some((marker) => body.includes(marker))) {
+      problems.push(`${name} carries an unsubscribe link; the module adds a link signed for each recipient, remove the pasted one`);
+    } else if (footers.some((footer) => body.includes(footer.text) || body.includes(`${footer.htmlLead} <a `))) {
+      problems.push(`${name} carries the unsubscribe footer; the module adds it to every mail, remove the pasted one`);
+    }
+  }
   return problems;
 }
 

package/src/server/campaigns.ts

@@ -4,7 +4,7 @@
 // failure about the sending account (refused key, spent quota), leaving the rest for the next run, and
 // after `limit` mails reached the provider, counting the rest for the next run.
 import { createHash } from "node:crypto";
-import { err, ok, type Result } from "@softure-ai/core";
+import { err, ok, type Result, type SoftureConfig } from "@softure-ai/core";
 import { and, eq, inArray } from "drizzle-orm";
 import type { CampaignRecipient, MailingErrorCode } from "../contract.js";
 import { campaigns, deliveries } from "../schema.js";
@@ -79,7 +79,7 @@ export function getCampaignContentHash(content: CampaignContent): string {
  * database failure and for content `getCampaignProblems` refuses.
  */
 export async function registerCampaign(ctx: DeliveryContext, content: CampaignContent): Promise<Result<undefined, CampaignErrorCode>> {
-  assertCampaign(content);
+  assertCampaign(content, ctx.config);
   const contentHash = getCampaignContentHash(content);
   await ctx.db
     .insert(campaigns)
@@ -202,7 +202,7 @@ export async function planCampaign(
   options: Pick<DeliverOptions, "uncertainClaimMs" | "retakeUncertain"> = {},
 ): Promise<CampaignPlan> {
   const { campaign } = input;
-  assertCampaign(campaign);
+  assertCampaign(campaign, ctx.config);
   const stored = await ctx.db.select({ contentHash: campaigns.contentHash }).from(campaigns).where(eq(campaigns.id, campaign.id)).limit(1);
   const contentChanged = stored[0] !== undefined && stored[0].contentHash !== getCampaignContentHash(campaign);
 
@@ -258,8 +258,8 @@ async function countPending(
   return { done: closed.size, suppressed, filtered, uncertain, toSend };
 }
 
-function assertCampaign(content: CampaignContent): void {
-  const problems = getCampaignProblems(content);
+function assertCampaign(content: CampaignContent, config: SoftureConfig): void {
+  const problems = getCampaignProblems(content, config);
   if (problems.length > 0) throw new Error(`@softure-ai/mailing: campaign "${content.id}" cannot be sent: ${problems.join("; ")}`);
 }
 

package/src/server/deliveries.ts

@@ -14,7 +14,9 @@ import { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_M
 import { deliveries } from "../schema.js";
 import { getMailingOptions } from "./options.js";
 import { sendMail } from "./send-mail.js";
+import { isSuppressed } from "./suppressions.js";
 import { getRecipientKey } from "./unsubscribe-link.js";
+import { validateMail } from "./validate-mail.js";
 
 export type DeliveryContext = ModuleContext<Queryable>;
 
@@ -115,6 +117,37 @@ export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, opti
   return { status: "rejected", reason: result.error, ...httpStatus };
 }
 
+/** What `deliverOnce` would do with a delivery now, read without writing or sending. */
+export type DeliveryForecast =
+  | { readonly status: "send" }
+  | { readonly status: "rejected"; readonly reason: "mailing.invalid_input" | "mailing.suppressed" }
+  | { readonly status: "done" }
+  | { readonly status: "in-flight" }
+  | { readonly status: "uncertain" };
+
+/**
+ * Reads the ledger, checks the mail and, for list mail, the suppression list, as `deliverOnce` would, and writes
+ * and sends nothing. A provider's answer cannot be foreseen: `send` means the mail would reach it. Throws like
+ * `deliverOnce` for a malformed scope or kind, and on a database failure.
+ */
+export async function forecastDelivery(ctx: DeliveryContext, delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryForecast> {
+  const windows = resolveClaimWindows(ctx, options);
+  const kind = delivery.mail.kind ?? TRANSACTIONAL_KIND;
+  assertDelivery(delivery, kind);
+  const key = { scope: delivery.scope, recipientKey: getRecipientKey(delivery.mail.to) };
+  const rows = await ctx.db.select({ status: deliveries.status, claimedAt: deliveries.claimedAt }).from(deliveries).where(matchKey(key)).limit(1);
+  const row = rows[0];
+  if (row?.status === "sent" || row?.status === "rejected") return { status: "done" };
+  if (row?.status === "claimed") {
+    const age = ctx.clock.now().getTime() - row.claimedAt.getTime();
+    if (age <= windows.staleClaimMs) return { status: "in-flight" };
+    if (age > windows.uncertainClaimMs && !windows.retakeUncertain) return { status: "uncertain" };
+  }
+  if (!validateMail(delivery.mail).ok) return { status: "rejected", reason: "mailing.invalid_input" };
+  if (kind !== TRANSACTIONAL_KIND && (await isSuppressed(ctx, delivery.mail.to))) return { status: "rejected", reason: "mailing.suppressed" };
+  return { status: "send" };
+}
+
 function isHaltingCode(code: MailingErrorCode): code is HaltingErrorCode {
   return HALTING_ERROR_CODES.has(code);
 }

package/src/server/dns.ts

@@ -1,7 +1,8 @@
 // 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. 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
+// provider's return-path hosts resolve, and that an inbound service (Cloudflare Email Routing)
+// receives the reply domain's mail. 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";
 
@@ -18,6 +19,7 @@ export type DnsFinding =
   | "weak"
   | "null-mx"
   | "unexpected-target"
+  | "missing-include"
   | "lookup-failed";
 
 export interface DnsCheck {
@@ -38,8 +40,13 @@ export interface SenderDnsReport {
   readonly replyTo: DnsCheck | null;
   /** One check per `returnPath` host, in the order given. */
   readonly returnPath: readonly DnsCheck[];
+  /** The inbound service's MX and SPF checks, in that order, when `inbound` was given; `[]` otherwise. */
+  readonly inbound: readonly DnsCheck[];
 }
 
+/** A service that receives the domain's mail: `cloudflare` is Cloudflare Email Routing. */
+export type InboundService = "cloudflare";
+
 export type ResolveTxt = (hostname: string) => Promise<string[][]>;
 export interface MxRecord {
   readonly exchange: string;
@@ -87,6 +94,11 @@ export interface CheckSenderDnsOptions {
   readonly replyTo?: string;
   /** Hosts that must resolve as a CNAME or with MX records; `resendReturnPath(domain)` gives Resend's. */
   readonly returnPath?: readonly ReturnPathHost[];
+  /**
+   * Checks that this service receives mail for the reply-to domain (else the checked domain): every MX record is the
+   * service's, and the one SPF record includes the service's, so replies arrive and forwarding passes SPF.
+   */
+  readonly inbound?: InboundService;
   readonly resolveTxt?: ResolveTxt;
   readonly resolveMx?: ResolveMx;
   readonly resolveCname?: ResolveCname;
@@ -109,6 +121,11 @@ export function resendReturnPath(domain: string): ReturnPathHost[] {
   ];
 }
 
+/** Cloudflare Email Routing: its MX hosts (`route1.mx.cloudflare.net`, ...) and the SPF include it asks for. */
+export const CLOUDFLARE_INBOUND = { mxDomain: "mx.cloudflare.net", spfInclude: "_spf.mx.cloudflare.net" } as const;
+
+const INBOUND_SERVICES: Readonly<Record<InboundService, { readonly mxDomain: string; readonly spfInclude: string }>> = { cloudflare: CLOUDFLARE_INBOUND };
+
 /** 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 = normalizeHost(domain);
@@ -116,14 +133,16 @@ export async function checkSenderDns(domain: string, options: CheckSenderDnsOpti
   const lookup = (host: string) => lookupTxt(resolveTxt, host);
   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([
+  const replyDomain = options.replyTo === undefined ? null : normalizeHost(getSenderDomain(options.replyTo));
+  const [spf, dkim, dmarc, replyTo, returnPath, inbound] = await Promise.all([
     checkSpf(lookup, options.spfHosts ?? [name]),
     checkDkim(lookup, (options.dkimSelectors ?? DEFAULT_DKIM_SELECTORS).map((selector) => `${selector}._domainkey.${name}`)),
     checkDmarc(lookup, name, options.expectDmarc),
-    options.replyTo === undefined ? null : checkReplyPath(lookup, lookupMx, normalizeHost(getSenderDomain(options.replyTo))),
+    replyDomain === null ? null : checkReplyPath(lookup, lookupMx, replyDomain),
     Promise.all((options.returnPath ?? []).map((path) => checkReturnPath(lookupCname, lookupMx, path))),
+    options.inbound === undefined ? [] : checkInbound({ lookup, lookupMx }, replyDomain ?? name, INBOUND_SERVICES[options.inbound]),
   ]);
-  return { domain: name, spf, dkim, dmarc, replyTo, returnPath };
+  return { domain: name, spf, dkim, dmarc, replyTo, returnPath, inbound };
 }
 
 /** The domain part of a sender (`Plan <hello@mail.example.com>` gives `mail.example.com`). */
@@ -309,3 +328,40 @@ async function checkReturnPath(lookupCname: CnameLookup, lookupMx: MxLookup, pat
   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) };
 }
+
+/** Whether `host` is `domain` or under it. Strings, not patterns: the domain is input. */
+function isUnder(host: string, domain: string): boolean {
+  return host === domain || host.endsWith(`.${domain}`);
+}
+
+/** The inbound service's MX (every record its own) and SPF (exactly one record, including the service's). */
+async function checkInbound(
+  { lookup, lookupMx }: { readonly lookup: Lookup; readonly lookupMx: MxLookup },
+  host: string,
+  service: { readonly mxDomain: string; readonly spfInclude: string },
+): Promise<DnsCheck[]> {
+  const [mx, txt] = await Promise.all([lookupMx(host), lookup(host)]);
+  return [checkInboundMx(mx, host, service.mxDomain), checkInboundSpf(txt, host, service.spfInclude)];
+}
+
+function checkInboundMx(mx: Answer<MxRecord>, host: string, mxDomain: string): DnsCheck {
+  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 };
+  const record = formatMx(mx.records);
+  if (isNullMx(mx.records)) return { status: "fail", finding: "null-mx", host, record };
+  const isService = mx.records.every((entry) => isUnder(normalizeHost(entry.exchange), mxDomain));
+  return isService ? { status: "pass", finding: "found", host, record } : { status: "fail", finding: "unexpected-target", host, record };
+}
+
+function checkInboundSpf(txt: TxtAnswer, host: string, include: string): DnsCheck {
+  if (txt.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  const records = txt.kind === "records" ? txt.records.filter(isSpfRecord) : [];
+  if (records.length > 1) return { status: "fail", finding: "multiple", host, record: null };
+  const record = records[0];
+  if (record === undefined) return { status: "fail", finding: "missing", host, record: null };
+  const includes = record
+    .trim()
+    .split(/\s+/)
+    .some((term) => term.toLowerCase().replace(/^\+/, "").replace(/\.$/, "") === `include:${include}`);
+  return includes ? { status: "pass", finding: "found", host, record } : { status: "fail", finding: "missing-include", host, record };
+}

package/src/server/index.ts

@@ -27,6 +27,7 @@ export {
 } from "./deliveries.js";
 export {
   checkSenderDns,
+  CLOUDFLARE_INBOUND,
   DEFAULT_DKIM_SELECTORS,
   getSenderDomain,
   RESEND_RETURN_PATH_DOMAIN,
@@ -38,6 +39,7 @@ export {
   type DnsCheck,
   type DnsCheckStatus,
   type DnsFinding,
+  type InboundService,
   type MxRecord,
   type ResolveCname,
   type ResolveMx,
@@ -57,9 +59,11 @@ export {
   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";
-export { isSuppressed, liftSuppression, suppressRecipient, unsubscribe, type SuppressionContext } from "./suppressions.js";
+export { maskAddress, redactUnsubscribeSignatures } from "./operator-output.js";
+export { getMailingModule, getMailingOptions, getMailingRoutes, resolveMailKind, type MailingRoutes } from "./options.js";
+export { runDeliveries, type DeliveryRunInput, type DeliveryRunSummary, type RunDeliveriesOptions } from "./run-deliveries.js";
+export { previewMail, sendMail, type MailContext, type MailPreviewFailure, type MailPreviewResult, type PreviewMailOptions } from "./send-mail.js";
+export { findSuppressedAddresses, isSuppressed, liftSuppression, suppressRecipient, unsubscribe, type SuppressionContext } from "./suppressions.js";
 export {
   buildUnsubscribeLinks,
   getRecipientKey,

package/src/server/operator-output.ts

@@ -0,0 +1,20 @@
+// What an operator's terminal may show of a mail: addresses masked, link signatures redacted. Command output ends
+// up in shell history, CI logs and pasted chat messages; a full address is personal data, and a signed unsubscribe
+// link lets whoever holds it unsubscribe that address.
+import { SIGNATURE_PARAM } from "./unsubscribe-link.js";
+
+/** `ada@example.org` becomes `a**@example.org`: the first character of the local part, then one `*` per other. */
+export function maskAddress(address: string): string {
+  const trimmed = address.trim();
+  const at = trimmed.lastIndexOf("@");
+  if (at <= 0) return "*".repeat(Math.max(trimmed.length, 1));
+  const local = trimmed.slice(0, at);
+  return `${local.slice(0, 1)}${"*".repeat(local.length - 1)}${trimmed.slice(at)}`;
+}
+
+const SIGNATURE = new RegExp(`([?&](?:amp;)?${SIGNATURE_PARAM}=)[A-Za-z0-9_-]+`, "g");
+
+/** `text` with the signature of every unsubscribe link replaced by `<signature>`, so the link no longer works. */
+export function redactUnsubscribeSignatures(text: string): string {
+  return text.replace(SIGNATURE, "$1<signature>");
+}

package/src/server/options.ts

@@ -30,3 +30,9 @@ export function getMailingRoutes(config: SoftureConfig): MailingRoutes {
   // The manifest declares both routes; the factory only replaces their paths.
   return getMailingModule(config).routes as unknown as MailingRoutes;
 }
+
+/** The kind an alias of `mailing({ kindAliases })` names, or `kind` itself when it is no alias. */
+export function resolveMailKind(config: SoftureConfig, kind: string): string {
+  const aliases = getMailingOptions(config).kindAliases ?? {};
+  return Object.hasOwn(aliases, kind) ? (aliases[kind] ?? kind) : kind;
+}

package/src/server/run-deliveries.ts

@@ -0,0 +1,184 @@
+// A run of lifecycle mail: one delivery per recipient through the ledger (`deliverOnce`), e.g. every subscription
+// whose trial ends this week. The app lists the recipients and builds each mail; the run keeps the ledger's
+// at-most-once rule, stops at the first failure about the sending account (refused key, spent quota) and after
+// `limit` mails reached the provider, and counts what it did. A dry run reads the same state and writes nothing.
+import { TRANSACTIONAL_KIND, type MailingErrorCode } from "../contract.js";
+import { deliverOnce, forecastDelivery, type DeliverOptions, type Delivery, type DeliveryContext, type DeliveryForecast, type DeliveryOutcome, type HaltingErrorCode } from "./deliveries.js";
+import { getRecipientKey, MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "./unsubscribe-link.js";
+
+/** Rejections the provider answered (the others never left the process). */
+const PROVIDER_REASONS: ReadonlySet<MailingErrorCode> = new Set(["mailing.rejected", "mailing.unavailable"]);
+
+export interface DeliveryRunInput<Recipient> {
+  readonly recipients: Iterable<Recipient> | AsyncIterable<Recipient>;
+  /** The delivery for one recipient (its scope and mail), or `null` to skip them. A throw stops the run. */
+  readonly build: (recipient: Recipient) => Delivery | null | Promise<Delivery | null>;
+}
+
+export interface RunDeliveriesOptions extends DeliverOptions {
+  /** Pause after every mail that reached the provider, for its rate limit. Default 0. */
+  readonly pauseMs?: number;
+  /**
+   * Most mails this run hands to the provider (sent, rejected by it, or not taken now). Once reached, the run reads
+   * the rest only to count `remaining`. A whole number of at least 1. Default: no limit.
+   */
+  readonly limit?: number;
+  /** Reads the ledger and the suppression list and sends and writes nothing; `sent` then counts what would go out. */
+  readonly dryRun?: boolean;
+  /** Called after every delivery of a real run, e.g. for progress output. Never receives the address. */
+  readonly onDelivery?: (outcome: DeliveryOutcome) => void;
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+export interface DeliveryRunSummary {
+  readonly dryRun: boolean;
+  /** Recipients read (past the limit too, but not past a halt). */
+  readonly recipients: number;
+  /** `build` returned `null`; nothing stored. */
+  readonly skipped: number;
+  /** Sent in this run; in a dry run, the mails that would reach the provider. */
+  readonly sent: number;
+  /** Rejected in this run, by reason; suppressed list mail is under `mailing.suppressed`. */
+  readonly rejected: Readonly<Record<MailingErrorCode, number>>;
+  /** Closed by an earlier run (or, in a dry run, by a delivery earlier in this one); nothing sent. */
+  readonly done: number;
+  /** Claimed by another run that is still sending. */
+  readonly inFlight: number;
+  /** The provider was unavailable, or the run halted on it; the next run tries again. */
+  readonly retryLater: number;
+  /** Claimed more than `uncertainClaimMs` ago and never closed: their mail may have gone out. */
+  readonly uncertain: number;
+  /** Set when the run stopped at a failure about the sending account; run again once the account can send. */
+  readonly halted: { readonly reason: HaltingErrorCode; readonly httpStatus?: number } | null;
+  /** Deliveries past the `limit` cut that the next run would send; 0 without a cut, `null` after a halt. */
+  readonly remaining: number | null;
+}
+
+type Counts = { -readonly [Key in Exclude<keyof DeliveryRunSummary, "dryRun" | "halted" | "remaining" | "rejected">]: number } & { rejected: Record<MailingErrorCode, number> };
+
+/**
+ * Builds and delivers one mail per recipient, in order, each at most once per scope and recipient. Throws on a
+ * database failure, when `build` throws, like `deliverOnce` for a malformed delivery, at the first list mail when
+ * `MAILING_UNSUBSCRIBE_SECRET` is not set (each send would fail and use up an attempt), and (a `RangeError`) for a
+ * `limit` that is not a whole number of at least 1.
+ */
+export async function runDeliveries<Recipient>(ctx: DeliveryContext, input: DeliveryRunInput<Recipient>, options: RunDeliveriesOptions = {}): Promise<DeliveryRunSummary> {
+  const { pauseMs = 0, limit, dryRun = false, onDelivery, sleep = wait, ...deliverOptions } = options;
+  if (limit !== undefined && !(Number.isInteger(limit) && limit >= 1)) {
+    throw new RangeError(`@softure-ai/mailing: runDeliveries limit must be a whole number of at least 1, got ${String(limit)}`);
+  }
+  const counts: Counts = { recipients: 0, skipped: 0, sent: 0, done: 0, inFlight: 0, retryLater: 0, uncertain: 0, rejected: emptyRejections() };
+  // Deliveries this run already sent or would send, so a dry run (and the count past the limit) sees its own effect.
+  const reached = new Set<string>();
+  let handedToProvider = 0;
+  let remaining = 0;
+  for await (const recipient of input.recipients) {
+    counts.recipients += 1;
+    const delivery = await input.build(recipient);
+    if (delivery === null) {
+      counts.skipped += 1;
+      continue;
+    }
+    assertListMailCanBeSigned(delivery);
+    const isPastLimit = limit !== undefined && handedToProvider >= limit;
+    if (dryRun || isPastLimit) {
+      const forecast = await forecastOnce(ctx, delivery, { options: deliverOptions, reached });
+      if (isPastLimit) {
+        if (forecast.status === "send") remaining += 1;
+        continue;
+      }
+      countForecast(counts, forecast);
+      if (forecast.status === "send") handedToProvider += 1;
+      continue;
+    }
+
+    const outcome = await deliverOnce(ctx, delivery, deliverOptions);
+    countOutcome(counts, outcome);
+    onDelivery?.(outcome);
+    if (outcome.status === "halted") {
+      const httpStatus = outcome.httpStatus === undefined ? {} : { httpStatus: outcome.httpStatus };
+      return { dryRun, ...counts, halted: { reason: outcome.reason, ...httpStatus }, remaining: null };
+    }
+    const reachedProvider = outcome.status === "sent" || outcome.status === "retry-later" || (outcome.status === "rejected" && PROVIDER_REASONS.has(outcome.reason));
+    if (outcome.status === "sent") reached.add(getDeliveryKey(delivery));
+    if (reachedProvider) handedToProvider += 1;
+    if (reachedProvider && pauseMs > 0) await sleep(pauseMs);
+  }
+  return { dryRun, ...counts, halted: null, remaining };
+}
+
+function getDeliveryKey(delivery: Delivery): string {
+  return `${delivery.scope}\n${getRecipientKey(delivery.mail.to)}`;
+}
+
+/** List mail without the signing secret is a configuration bug: stop before any claim is taken. */
+function assertListMailCanBeSigned(delivery: Delivery): void {
+  if ((delivery.mail.kind ?? TRANSACTIONAL_KIND) === TRANSACTIONAL_KIND || readUnsubscribeSecrets().current !== null) return;
+  throw new Error(`@softure-ai/mailing: runDeliveries sends list mail, which needs ${UNSUBSCRIBE_SECRET_ENV} (at least ${String(MIN_UNSUBSCRIBE_SECRET_LENGTH)} characters)`);
+}
+
+/** The forecast, with a delivery this run already sent (or would send) counted as done. */
+async function forecastOnce(
+  ctx: DeliveryContext,
+  delivery: Delivery,
+  { options, reached }: { readonly options: DeliverOptions; readonly reached: Set<string> },
+): Promise<DeliveryForecast> {
+  const key = getDeliveryKey(delivery);
+  const forecast = await forecastDelivery(ctx, delivery, options);
+  if (forecast.status !== "send") return forecast;
+  if (reached.has(key)) return { status: "done" };
+  reached.add(key);
+  return forecast;
+}
+
+function countForecast(counts: Counts, forecast: DeliveryForecast): void {
+  switch (forecast.status) {
+    case "send":
+      counts.sent += 1;
+      return;
+    case "rejected":
+      counts.rejected[forecast.reason] += 1;
+      return;
+    case "done":
+      counts.done += 1;
+      return;
+    case "in-flight":
+      counts.inFlight += 1;
+      return;
+    case "uncertain":
+      counts.uncertain += 1;
+      return;
+  }
+}
+
+function countOutcome(counts: Counts, outcome: DeliveryOutcome): void {
+  switch (outcome.status) {
+    case "sent":
+      counts.sent += 1;
+      return;
+    case "rejected":
+      counts.rejected[outcome.reason] += 1;
+      return;
+    case "done":
+      counts.done += 1;
+      return;
+    case "in-flight":
+      counts.inFlight += 1;
+      return;
+    case "retry-later":
+    case "halted":
+      counts.retryLater += 1;
+      return;
+    case "uncertain":
+      counts.uncertain += 1;
+      return;
+  }
+}
+
+function emptyRejections(): Record<MailingErrorCode, number> {
+  return { "mailing.invalid_input": 0, "mailing.rejected": 0, "mailing.unavailable": 0, "mailing.suppressed": 0, "mailing.provider_refused": 0, "mailing.quota_exceeded": 0 };
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}