@softure-ai/mailing 0.1.10 → 0.1.12

package/src/next/preview-mail.ts

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

package/src/next/run-deliveries.ts

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

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,9 +1,10 @@
 // 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.
+// 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";
@@ -46,6 +47,11 @@ export interface CampaignSummary {
    * after it were left as they were; run again once the account can send.
    */
   readonly halted: CampaignHalt | null;
+  /**
+   * Recipients past the `limit` cut that the next run would send to, counted as `planCampaign` counts `toSend`. 0 when
+   * the run reached the end of the list; `null` when it halted (the rest of the list was not read).
+   */
+  readonly remaining: number | null;
 }
 
 export interface SendCampaignOptions extends DeliverOptions {
@@ -54,6 +60,13 @@ export interface SendCampaignOptions extends DeliverOptions {
   /** Called after every recipient, e.g. for progress output. Never receives the address. */
   readonly onDelivery?: (outcome: DeliveryOutcome) => void;
   readonly sleep?: (ms: number) => Promise<void>;
+  /**
+   * Most mails this run hands to the provider (sent, rejected by it, or not taken now), e.g. to leave part of a shared
+   * daily quota for other mail. Done, unsubscribed, filtered, in-flight and uncertain recipients never count. Once
+   * reached, the run reads the rest of the list only to count `remaining`. A whole number of at least 1. Default: no
+   * limit.
+   */
+  readonly limit?: number;
 }
 
 /** sha256 (hex) of what a recipient reads: kind, subject, text and HTML. */
@@ -66,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)
@@ -79,15 +92,19 @@ 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. Throws on a
- * database failure and when the filter throws.
+ * `filterCampaignRecipient` refuses are skipped. Stops at the first `halted` delivery, 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.
  */
 export async function sendCampaign(
   ctx: DeliveryContext,
   input: { readonly campaign: CampaignContent; readonly recipients: Iterable<string> | AsyncIterable<string> },
   options: SendCampaignOptions = {},
 ): Promise<Result<CampaignSummary, CampaignErrorCode>> {
-  const { pauseMs = 0, onDelivery, sleep = wait, ...deliverOptions } = options;
+  const { pauseMs = 0, onDelivery, sleep = wait, limit, ...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)}`);
+  }
   const { campaign } = input;
   const registered = await registerCampaign(ctx, campaign);
   if (!registered.ok) return registered;
@@ -96,10 +113,16 @@ export async function sendCampaign(
   const seen = new Set<string>();
   const scope = `campaign:${campaign.id}`;
   const isWanted = createRecipientFilter(ctx, campaign);
+  const pastLimit = new Map<string, string>();
+  let handedToProvider = 0;
   for await (const address of input.recipients) {
     const recipientKey = getRecipientKey(address);
     if (seen.has(recipientKey)) continue;
     seen.add(recipientKey);
+    if (limit !== undefined && handedToProvider >= limit) {
+      pastLimit.set(recipientKey, address);
+      continue;
+    }
     if (!(await isWanted(address, recipientKey))) {
       counts.filtered += 1;
       continue;
@@ -116,12 +139,14 @@ export async function sendCampaign(
     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 } });
+      return ok({ recipients: seen.size, ...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 (reachedProvider) handedToProvider += 1;
     if (reachedProvider && pauseMs > 0) await sleep(pauseMs);
   }
-  return ok({ recipients: seen.size, ...counts, halted: null });
+  const remaining = pastLimit.size === 0 ? 0 : (await countPending(ctx, campaign, pastLimit, deliverOptions)).toSend;
+  return ok({ recipients: seen.size, ...counts, halted: null, remaining });
 }
 
 /** `filterCampaignRecipient` bound to the campaign, or "everyone" when the app set none. */
@@ -177,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);
 
@@ -186,6 +211,22 @@ export async function planCampaign(
     const key = getRecipientKey(address);
     if (!addresses.has(key)) addresses.set(key, address);
   }
+  const pending = await countPending(ctx, campaign, addresses, options);
+  return { recipients: addresses.size, ...pending, contentChanged };
+}
+
+type PendingCounts = Pick<CampaignPlan, "done" | "suppressed" | "filtered" | "uncertain" | "toSend">;
+
+/**
+ * How the ledger, the filter and the suppression list sort `addresses` (recipient key to address) for the campaign,
+ * without writing. Throws on a database failure and when the filter throws.
+ */
+async function countPending(
+  ctx: DeliveryContext,
+  campaign: CampaignContent,
+  addresses: ReadonlyMap<string, string>,
+  options: Pick<DeliverOptions, "uncertainClaimMs" | "retakeUncertain">,
+): Promise<PendingCounts> {
   const uncertainBefore = ctx.clock.now().getTime() - (options.uncertainClaimMs ?? getMailingOptions(ctx.config).uncertainClaimMs);
   const closed = new Set<string>();
   const uncertainKeys = new Set<string>();
@@ -214,11 +255,11 @@ export async function planCampaign(
       if (options.retakeUncertain === true) toSend += 1;
     } else toSend += 1;
   }
-  return { recipients: addresses.size, done: closed.size, suppressed, filtered, uncertain, toSend, contentChanged };
+  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;
+}