@softure-ai/mailing 0.1.11 → 0.1.13

package/src/options.ts

@@ -1,6 +1,6 @@
 // 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 { isMailbox, isMailKind, isSingleAddress } from "./address.js";
 import type { CampaignRecipientFilter, CampaignRecipientSource, LegacyUnsubscribe, MailProvider, OnUnsubscribedHook } from "./contract.js";
 
 export const DEFAULT_TIMEOUT_MS = 10_000;
@@ -42,6 +42,13 @@ const legacyUnsubscribeSchema = z.strictObject({
 
 const HOUR_MS = 60 * 60_000;
 
+const mailKind = z.string().refine(isMailKind, "must be a kebab-case mail kind such as newsletter");
+
+/** Alias to kind; an alias never names a kind another alias points at, so one lookup resolves it. */
+const kindAliasesSchema = z
+  .record(mailKind, mailKind)
+  .refine((aliases) => Object.keys(aliases).every((alias) => !Object.values(aliases).includes(alias)), "must not use a kind as an alias: aliases resolve in one step");
+
 function isMailProvider(value: unknown): value is MailProvider {
   if (typeof value !== "object" || value === null) return false;
   const candidate = value as { name?: unknown; send?: unknown };
@@ -56,6 +63,16 @@ export const mailingOptionsSchema = z.strictObject({
   from: z.string().trim().refine(isMailbox, "must be an address or Name <address>, e.g. Plan <hello@example.com>"),
   /** Where replies go; may sit on another domain than `from` (DMARC does not check it). */
   replyTo: z.string().trim().refine(isSingleAddress, "must be one address, e.g. support@example.com").optional(),
+  /**
+   * The only address `softure-mail test` sends to, e.g. the operator's inbox. Without it the command refuses to send,
+   * so a test never reaches a customer.
+   */
+  testAddress: z.string().trim().refine(isSingleAddress, "must be one address, e.g. ops@example.com").optional(),
+  /**
+   * Short names for mail kinds in campaign files and `softure-mail test --kind`, e.g. `{ news: "newsletter" }`. The
+   * campaign is stored and sent under the kind the alias names.
+   */
+  kindAliases: kindAliasesSchema.optional(),
   /** The adapter that delivers mail: `resend()`, or `fakeMailProvider()` from `/testing`. */
   provider: z.custom<MailProvider>(isMailProvider, "must be a mail provider such as resend()"),
   /** How long one send may take before it reads as `mailing.unavailable`. */

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

@@ -1,15 +1,16 @@
 // Campaigns: one list mail to many recipients through the delivery ledger. The campaign row pins
 // the content (a hash of kind, subject and bodies), so a re-run with the same id sends the rest of
 // the same mail and nothing twice; other content under that id is refused. A run stops at the first
-// 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.
+// failure about the sending account (refused key, spent quota) and, unless told otherwise, at the first
+// mail the provider could not take now, 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";
 import { getCampaignProblems, type CampaignContent } from "./campaign-file.js";
-import { deliverOnce, type DeliverOptions, type DeliveryContext, type DeliveryOutcome, type HaltingErrorCode } from "./deliveries.js";
+import { deliverOnce, getRunHalt, type DeliverOptions, type DeliveryContext, type DeliveryOutcome, type RunHalt } from "./deliveries.js";
 import { getMailingOptions } from "./options.js";
 import { isSuppressed } from "./suppressions.js";
 import { getRecipientKey } from "./unsubscribe-link.js";
@@ -18,10 +19,7 @@ import { getRecipientKey } from "./unsubscribe-link.js";
 const PROVIDER_REASONS: ReadonlySet<MailingErrorCode> = new Set(["mailing.rejected", "mailing.unavailable"]);
 
 /** Why a run stopped before the end of the list. */
-export interface CampaignHalt {
-  readonly reason: HaltingErrorCode;
-  readonly httpStatus?: number;
-}
+export type CampaignHalt = RunHalt;
 
 /** The campaign id is taken by other content. Give the new content a new id. */
 export type CampaignErrorCode = "mailing.campaign_changed";
@@ -43,8 +41,9 @@ export interface CampaignSummary {
   /** 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. The recipient it happened to and every one
-   * after it were left as they were; run again once the account can send.
+   * Set when the run stopped early: at a failure about the sending account (run again once the account can send) or,
+   * with `stopOnRetryLater`, at the first mail the provider could not take now (`mailing.unavailable`; run again
+   * later). The recipient it happened to and every one after it were left as they were.
    */
   readonly halted: CampaignHalt | null;
   /**
@@ -67,6 +66,12 @@ export interface SendCampaignOptions extends DeliverOptions {
    * limit.
    */
   readonly limit?: number;
+  /**
+   * End the run at the first `retry-later` (the provider is down, timed out or rate limited), reported in `halted` as
+   * `mailing.unavailable`. Going on would spend an attempt of every following recipient on the same answer. Default
+   * `true`.
+   */
+  readonly stopOnRetryLater?: boolean;
 }
 
 /** sha256 (hex) of what a recipient reads: kind, subject, text and HTML. */
@@ -79,7 +84,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)
@@ -92,7 +97,8 @@ export async function registerCampaign(ctx: DeliveryContext, content: CampaignCo
 /**
  * Sends `campaign` to every recipient that has no outcome yet, one at a time. Recipients who
  * unsubscribed are rejected (`mailing.suppressed`) and never retried; recipients the module's
- * `filterCampaignRecipient` refuses are skipped. Stops at the first `halted` delivery, and before the recipient
+ * `filterCampaignRecipient` refuses are skipped. Stops at the first `halted` delivery, unless `stopOnRetryLater` is
+ * `false` at the first `retry-later`, and before the recipient
  * after `limit` mails reached the provider. Throws on a database failure, when the filter throws, and (a
  * `RangeError`) for a `limit` that is not a whole number of at least 1.
  */
@@ -101,7 +107,7 @@ export async function sendCampaign(
   input: { readonly campaign: CampaignContent; readonly recipients: Iterable<string> | AsyncIterable<string> },
   options: SendCampaignOptions = {},
 ): Promise<Result<CampaignSummary, CampaignErrorCode>> {
-  const { pauseMs = 0, onDelivery, sleep = wait, limit, ...deliverOptions } = options;
+  const { pauseMs = 0, onDelivery, sleep = wait, limit, stopOnRetryLater = true, ...deliverOptions } = options;
   if (limit !== undefined && !(Number.isInteger(limit) && limit >= 1)) {
     throw new RangeError(`@softure-ai/mailing: sendCampaign limit must be a whole number of at least 1, got ${String(limit)}`);
   }
@@ -136,11 +142,9 @@ export async function sendCampaign(
     );
     countOutcome(counts, outcome);
     onDelivery?.(outcome);
-    if (outcome.status === "halted") {
-      // The rest of the list is not even counted as seen: the summary covers what this run reached.
-      const httpStatus = outcome.httpStatus === undefined ? {} : { httpStatus: outcome.httpStatus };
-      return ok({ recipients: seen.size, ...counts, halted: { reason: outcome.reason, ...httpStatus }, remaining: null });
-    }
+    const halt = getRunHalt(outcome, stopOnRetryLater);
+    // The rest of the list is not even counted as seen: the summary covers what this run reached.
+    if (halt !== null) return ok({ recipients: seen.size, ...counts, halted: halt, remaining: null });
     const reachedProvider = outcome.status === "sent" || outcome.status === "retry-later" || (outcome.status === "rejected" && PROVIDER_REASONS.has(outcome.reason));
     if (reachedProvider) handedToProvider += 1;
     if (reachedProvider && pauseMs > 0) await sleep(pauseMs);
@@ -202,7 +206,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 +262,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>;
 
@@ -56,6 +58,26 @@ export interface DeliverOptions {
 /** The codes that stop a run: the sending account, not the mail, is the problem. */
 export type HaltingErrorCode = "mailing.provider_refused" | "mailing.quota_exceeded";
 
+/**
+ * Why a run of many deliveries (`runDeliveries`, `sendCampaign`) stopped early: the account cannot send
+ * (`HaltingErrorCode`), or the provider answered `retry-later` (`mailing.unavailable`: down, timed out or rate
+ * limited) and the run stops on it.
+ */
+export type RunHaltReason = HaltingErrorCode | "mailing.unavailable";
+
+/** Why a run stopped early, with the provider's HTTP status when it gave one. */
+export interface RunHalt {
+  readonly reason: RunHaltReason;
+  readonly httpStatus?: number;
+}
+
+/** Why a run stops after this outcome: at `halted`, and at `retry-later` when it stops on it; `null` to go on. */
+export function getRunHalt(outcome: DeliveryOutcome, stopOnRetryLater: boolean): RunHalt | null {
+  if (outcome.status !== "halted" && !(stopOnRetryLater && outcome.status === "retry-later")) return null;
+  const reason = outcome.status === "halted" ? outcome.reason : "mailing.unavailable";
+  return outcome.httpStatus === undefined ? { reason } : { reason, httpStatus: outcome.httpStatus };
+}
+
 export type DeliveryOutcome =
   /** Sent now; `id` is the provider's message id. */
   | { readonly status: "sent"; readonly id: string }
@@ -115,6 +137,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

@@ -24,9 +24,12 @@ export {
   type DeliveryContext,
   type DeliveryOutcome,
   type HaltingErrorCode,
+  type RunHalt,
+  type RunHaltReason,
 } from "./deliveries.js";
 export {
   checkSenderDns,
+  CLOUDFLARE_INBOUND,
   DEFAULT_DKIM_SELECTORS,
   getSenderDomain,
   RESEND_RETURN_PATH_DOMAIN,
@@ -38,6 +41,7 @@ export {
   type DnsCheck,
   type DnsCheckStatus,
   type DnsFinding,
+  type InboundService,
   type MxRecord,
   type ResolveCname,
   type ResolveMx,
@@ -57,9 +61,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;
+}