@softure-ai/mailing 0.0.0-stage → 0.1.6

package/src/server/deliveries.ts

@@ -0,0 +1,155 @@
+// The delivery ledger (mailing.deliveries): a mail goes out at most once per scope and recipient.
+// The sender claims the row in one conditional upsert before it calls the provider, then closes it
+// with one outcome. A claim left behind by a crash is taken over once it is stale, and the mail is
+// sent again with the same idempotency key, so the provider folds it into the first send.
+import { type ModuleContext } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { and, eq, lt, or, sql } from "drizzle-orm";
+import { isMailKind } from "../address.js";
+import { TRANSACTIONAL_KIND, type MailingErrorCode, type OutgoingMail } from "../contract.js";
+import { deliveries } from "../schema.js";
+import { sendMail } from "./send-mail.js";
+import { getRecipientKey } from "./unsubscribe-link.js";
+
+export type DeliveryContext = ModuleContext<Queryable>;
+
+/** How long a claim may stay open before another sender may take it over. */
+export const DEFAULT_STALE_CLAIM_MS = 15 * 60_000;
+/** Claims a delivery gets before `mailing.unavailable` becomes its final outcome. */
+export const DEFAULT_MAX_ATTEMPTS = 5;
+
+const MAX_SCOPE_LENGTH = 128;
+const SCOPE = /^[a-z0-9][a-z0-9._:-]*$/;
+
+export interface Delivery {
+  /**
+   * What the mail is about, unique per recipient: `campaign:<id>` for campaigns (set by
+   * `sendCampaign`), `<module>.<event>:<entity>` for lifecycle mail, e.g.
+   * `billing.trial-ending:sub_42`. Lowercase letters, digits and `._:-`, at most 128 characters.
+   */
+  readonly scope: string;
+  /** The mail. Its `kind` is stored with the row; the idempotency key comes from the ledger. */
+  readonly mail: OutgoingMail;
+  /** The campaign the delivery belongs to; its scope must then be `campaign:<id>`. */
+  readonly campaignId?: string;
+}
+
+export interface DeliverOptions {
+  readonly staleClaimMs?: number;
+  readonly maxAttempts?: number;
+}
+
+export type DeliveryOutcome =
+  /** Sent now; `id` is the provider's message id. */
+  | { readonly status: "sent"; readonly id: string }
+  /** Refused now, for good (suppressed, rejected, invalid, or unavailable too many times). */
+  | { readonly status: "rejected"; readonly reason: MailingErrorCode }
+  /** An earlier run already closed this delivery; nothing was sent. */
+  | { readonly status: "done"; readonly outcome: "sent" | "rejected" }
+  /** Another sender holds a fresh claim; nothing was sent. */
+  | { readonly status: "in-flight" }
+  /** The provider was unavailable; the claim is released for a later run. */
+  | { readonly status: "retry-later" };
+
+/**
+ * Sends `delivery.mail` unless the ledger already has an outcome (or a fresh claim) for its scope
+ * and recipient, and records the outcome. Throws on a database failure (after a send, the claim
+ * stays open and becomes stale, so a later run re-sends with the same idempotency key), for a
+ * malformed scope or kind, and when `sendMail` throws.
+ */
+export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryOutcome> {
+  const { staleClaimMs = DEFAULT_STALE_CLAIM_MS, maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
+  const kind = delivery.mail.kind ?? TRANSACTIONAL_KIND;
+  assertDelivery(delivery, kind);
+
+  const recipientKey = getRecipientKey(delivery.mail.to);
+  const key = { scope: delivery.scope, recipientKey };
+  const attempt = await claimDelivery(ctx, { ...key, kind, campaignId: delivery.campaignId ?? null, staleClaimMs });
+  if (attempt === null) return readClosedDelivery(ctx, key);
+
+  const result = await sendMail(ctx, delivery.mail, { idempotencyKey: `${delivery.scope}:${recipientKey}` });
+  const fence = { ...key, attempt };
+  if (result.ok) {
+    await closeDelivery(ctx, fence, { status: "sent", providerMessageId: result.value.id, reason: null });
+    return { status: "sent", id: result.value.id };
+  }
+  if (result.error === "mailing.unavailable" && attempt < maxAttempts) {
+    await releaseDelivery(ctx, fence);
+    return { status: "retry-later" };
+  }
+  await closeDelivery(ctx, fence, { status: "rejected", providerMessageId: null, reason: result.error });
+  return { status: "rejected", reason: result.error };
+}
+
+function assertDelivery(delivery: Delivery, kind: string): void {
+  if (delivery.scope.length > MAX_SCOPE_LENGTH || !SCOPE.test(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)) {
+    throw new Error(`@softure-ai/mailing: deliverOnce kind "${kind}" must be kebab-case (at most 64 characters)`);
+  }
+  if (delivery.campaignId !== undefined && delivery.scope !== `campaign:${delivery.campaignId}`) {
+    throw new Error(`@softure-ai/mailing: a delivery of campaign "${delivery.campaignId}" must use the scope "campaign:${delivery.campaignId}"`);
+  }
+}
+
+interface DeliveryKey {
+  readonly scope: string;
+  readonly recipientKey: string;
+}
+
+/**
+ * Takes the row in one statement: a new row, a `pending` one, or a claim older than
+ * `staleClaimMs`. Resolves with the attempt number that fences the outcome, or `null` when the row
+ * is closed or claimed by someone else.
+ */
+async function claimDelivery(
+  ctx: DeliveryContext,
+  claim: DeliveryKey & { readonly kind: string; readonly campaignId: string | null; readonly staleClaimMs: number },
+): Promise<number | null> {
+  const now = ctx.clock.now();
+  const staleBefore = new Date(now.getTime() - claim.staleClaimMs);
+  const rows = await ctx.db
+    .insert(deliveries)
+    .values({ scope: claim.scope, recipientKey: claim.recipientKey, kind: claim.kind, campaignId: claim.campaignId, status: "claimed", attempts: 1, claimedAt: now, createdAt: now })
+    .onConflictDoUpdate({
+      target: [deliveries.scope, deliveries.recipientKey],
+      set: { status: "claimed", attempts: sql`${deliveries.attempts} + 1`, claimedAt: now },
+      setWhere: or(eq(deliveries.status, "pending"), and(eq(deliveries.status, "claimed"), lt(deliveries.claimedAt, staleBefore))),
+    })
+    .returning();
+  return rows[0]?.attempts ?? null;
+}
+
+async function readClosedDelivery(ctx: DeliveryContext, key: DeliveryKey): Promise<DeliveryOutcome> {
+  const rows = await ctx.db.select({ status: deliveries.status }).from(deliveries).where(matchKey(key)).limit(1);
+  const status = rows[0]?.status;
+  if (status === "sent" || status === "rejected") return { status: "done", outcome: status };
+  // A fresh claim; `pending` only between another sender's release and this read.
+  return { status: "in-flight" };
+}
+
+type Fence = DeliveryKey & { readonly attempt: number };
+
+/** Writes the outcome if this sender still holds the claim; a stale holder writes nothing. */
+async function closeDelivery(
+  ctx: DeliveryContext,
+  fence: Fence,
+  outcome: { readonly status: "sent" | "rejected"; readonly providerMessageId: string | null; readonly reason: string | null },
+): Promise<void> {
+  await ctx.db
+    .update(deliveries)
+    .set({ ...outcome, finishedAt: ctx.clock.now() })
+    .where(and(matchKey(fence), eq(deliveries.status, "claimed"), eq(deliveries.attempts, fence.attempt)));
+}
+
+async function releaseDelivery(ctx: DeliveryContext, fence: Fence): Promise<void> {
+  await ctx.db
+    .update(deliveries)
+    .set({ status: "pending" })
+    .where(and(matchKey(fence), eq(deliveries.status, "claimed"), eq(deliveries.attempts, fence.attempt)));
+}
+
+function matchKey(key: DeliveryKey) {
+  return and(eq(deliveries.scope, key.scope), eq(deliveries.recipientKey, key.recipientKey));
+}

package/src/server/dns.ts

@@ -0,0 +1,153 @@
+// 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";
+
+export type DnsCheckStatus = "pass" | "warn" | "fail";
+
+export type DnsFinding =
+  | "found"
+  | "missing"
+  | "multiple"
+  | "permissive"
+  | "revoked"
+  | "monitor-only"
+  | "inherited"
+  | "lookup-failed";
+
+export interface DnsCheck {
+  readonly status: DnsCheckStatus;
+  readonly finding: DnsFinding;
+  /** The name that answered (or the first one asked, when none did). */
+  readonly host: string;
+  /** The record that decided the status, when there is one. */
+  readonly record: string | null;
+}
+
+export interface SenderDnsReport {
+  readonly domain: string;
+  readonly spf: DnsCheck;
+  readonly dkim: DnsCheck;
+  readonly dmarc: DnsCheck;
+}
+
+export type ResolveTxt = (hostname: string) => Promise<string[][]>;
+
+export interface CheckSenderDnsOptions {
+  /** DKIM selectors to look up under `_domainkey`. Default `["resend"]`, the Resend selector. */
+  readonly dkimSelectors?: readonly string[];
+  /**
+   * Where SPF is published. Default: the domain itself. Resend checks SPF on `send.<domain>` (its
+   * return path); DMARC accepts that in relaxed alignment.
+   */
+  readonly spfHosts?: readonly string[];
+  readonly resolveTxt?: ResolveTxt;
+}
+
+export const DEFAULT_DKIM_SELECTORS: readonly string[] = ["resend"];
+
+/** 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 resolveTxt = options.resolveTxt ?? resolveTxtRecords;
+  const lookup = (host: string) => lookupTxt(resolveTxt, host);
+  const [spf, dkim, dmarc] = await Promise.all([
+    checkSpf(lookup, options.spfHosts ?? [name]),
+    checkDkim(lookup, (options.dkimSelectors ?? DEFAULT_DKIM_SELECTORS).map((selector) => `${selector}._domainkey.${name}`)),
+    checkDmarc(lookup, name),
+  ]);
+  return { domain: name, spf, dkim, dmarc };
+}
+
+/** The domain part of a sender (`Plan <hello@mail.example.com>` gives `mail.example.com`). */
+export function getSenderDomain(from: string): string {
+  // Index arithmetic, not a regular expression: `from` may come from anywhere, and a pattern over
+  // `<...>` backtracks polynomially on input like "<<<<".
+  const open = from.lastIndexOf("<");
+  const close = from.lastIndexOf(">");
+  const address = open !== -1 && close > open ? from.slice(open + 1, close) : from;
+  return address.slice(address.lastIndexOf("@") + 1).trim().toLowerCase();
+}
+
+type Lookup = (host: string) => Promise<TxtAnswer>;
+type TxtAnswer = { readonly kind: "records"; readonly records: string[] } | { readonly kind: "none" } | { readonly kind: "error" };
+
+const NO_RECORD_CODES = new Set(["ENOTFOUND", "ENODATA", "NXDOMAIN"]);
+
+async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswer> {
+  try {
+    // A TXT record may arrive in 255-byte chunks; they form one string.
+    const records = (await resolveTxt(host)).map((chunks) => chunks.join(""));
+    return records.length === 0 ? { kind: "none" } : { kind: "records", records };
+  } catch (error) {
+    const code = (error as { code?: unknown } | null)?.code;
+    return typeof code === "string" && NO_RECORD_CODES.has(code) ? { kind: "none" } : { kind: "error" };
+  }
+}
+
+function startsWithTag(record: string, tag: string): boolean {
+  return record.trim().toLowerCase().startsWith(tag);
+}
+
+/** One `v=spf1` record per host; `+all` (or a bare `all`) lets anyone send as the domain. */
+async function checkSpf(lookup: Lookup, hosts: readonly string[]): Promise<DnsCheck> {
+  let lookupFailed: string | null = null;
+  for (const host of hosts) {
+    const answer = await lookup(host);
+    if (answer.kind === "error") {
+      lookupFailed ??= host;
+      continue;
+    }
+    const records = answer.kind === "records" ? answer.records.filter((record) => /^v=spf1(\s|$)/i.test(record.trim())) : [];
+    if (records.length > 1) return { status: "fail", finding: "multiple", host, record: null };
+    const record = records[0];
+    if (record === undefined) continue;
+    const permissive = /(^|\s)\+?all(\s|$)/i.test(record);
+    return permissive ? { status: "warn", finding: "permissive", host, record } : { status: "pass", finding: "found", host, record };
+  }
+  return lookupFailed === null ? { status: "fail", finding: "missing", host: hosts[0] ?? "", record: null } : { status: "fail", finding: "lookup-failed", host: lookupFailed, record: null };
+}
+
+/** A key record (`p=`) under one of the selectors; an empty `p=` means the key was revoked. */
+async function checkDkim(lookup: Lookup, hosts: readonly string[]): Promise<DnsCheck> {
+  let fallback: DnsCheck = { status: "fail", finding: "missing", host: hosts[0] ?? "", record: null };
+  for (const host of hosts) {
+    const answer = await lookup(host);
+    if (answer.kind === "error") {
+      if (fallback.finding === "missing") fallback = { status: "fail", finding: "lookup-failed", host, record: null };
+      continue;
+    }
+    if (answer.kind === "none") continue;
+    const record = answer.records.find((candidate) => /(^|;)\s*p=/i.test(candidate));
+    if (record === undefined) continue;
+    const key = /(?:^|;)\s*p=([^;]*)/i.exec(record)?.[1]?.trim() ?? "";
+    if (key !== "") return { status: "pass", finding: "found", host, record };
+    fallback = { status: "fail", finding: "revoked", host, record };
+  }
+  return fallback;
+}
+
+/**
+ * `_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.
+ */
+async function checkDmarc(lookup: Lookup, domain: string): Promise<DnsCheck> {
+  const labels = domain.split(".");
+  const first = `_dmarc.${domain}`;
+  for (let index = 0; index <= labels.length - 2; index += 1) {
+    const host = `_dmarc.${labels.slice(index).join(".")}`;
+    const answer = await lookup(host);
+    if (answer.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+    if (answer.kind === "none") continue;
+    const records = answer.records.filter((record) => startsWithTag(record, "v=dmarc1"));
+    if (records.length > 1) return { status: "fail", finding: "multiple", host, record: null };
+    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";
+    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 };
+}

package/src/server/health.ts

@@ -0,0 +1,14 @@
+// The module's readiness probe for `GET /api/health` of `@softure-ai/ops`: the suppression list,
+// the campaigns and the delivery ledger exist and answer, i.e. `softure migrate` ran. It reads no rows.
+import { ok, type HealthCheck } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { sql } from "drizzle-orm";
+
+export const checkMailingTables: HealthCheck = async (context) => {
+  // Core types `db` as unknown; the health route passes the @softure-ai/db handle.
+  const db = context.db as Queryable;
+  await db.execute(sql`select 1 from mailing.suppressions limit 0`);
+  await db.execute(sql`select 1 from mailing.campaigns limit 0`);
+  await db.execute(sql`select 1 from mailing.deliveries limit 0`);
+  return ok();
+};

package/src/server/index.ts

@@ -0,0 +1,56 @@
+// Server-only logic of @softure-ai/mailing. Functions receive a context and never read request
+// scope; `next/*` imports are not allowed here (ESLint `no-restricted-imports`, NFR-3).
+export { getCampaignProblems, parseCampaignFile, parseRecipientList, type CampaignContent, type CampaignFile, type CampaignFileResult } from "./campaign-file.js";
+export {
+  getCampaignContentHash,
+  planCampaign,
+  registerCampaign,
+  sendCampaign,
+  type CampaignErrorCode,
+  type CampaignPlan,
+  type CampaignSummary,
+  type SendCampaignOptions,
+} from "./campaigns.js";
+export {
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_STALE_CLAIM_MS,
+  deliverOnce,
+  type DeliverOptions,
+  type Delivery,
+  type DeliveryContext,
+  type DeliveryOutcome,
+} from "./deliveries.js";
+export {
+  checkSenderDns,
+  DEFAULT_DKIM_SELECTORS,
+  getSenderDomain,
+  type CheckSenderDnsOptions,
+  type DnsCheck,
+  type DnsCheckStatus,
+  type DnsFinding,
+  type ResolveTxt,
+  type SenderDnsReport,
+} from "./dns.js";
+export { checkMailingTables } from "./health.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 {
+  buildUnsubscribeLinks,
+  getRecipientKey,
+  MIN_UNSUBSCRIBE_SECRET_LENGTH,
+  readUnsubscribeSecrets,
+  readUnsubscribeToken,
+  RECIPIENT_PARAM,
+  signRecipientKey,
+  SIGNATURE_PARAM,
+  UNSUBSCRIBE_PREVIOUS_SECRET_ENV,
+  UNSUBSCRIBE_SECRET_ENV,
+  verifyUnsubscribeToken,
+  type Env,
+  type UnsubscribeLinks,
+  type UnsubscribeSecrets,
+  type UnsubscribeToken,
+} from "./unsubscribe-link.js";
+export { validateMail, type MailValidation, type ValidMail } from "./validate-mail.js";

package/src/server/list-mail.ts

@@ -0,0 +1,42 @@
+// The footer and headers every list mail carries. Ported from FIRE_TRACKER
+// `src/lib/unsubscribe-footer.ts`: one footer and one header pair for all list mail, so no kind of
+// mail can lose its link while its own tests stay green. HTML bodies get a footer too.
+import type { MailingMessages } from "../messages/index.js";
+import type { UnsubscribeLinks } from "./unsubscribe-link.js";
+
+/** The signature separator (RFC 3676): mail clients fold what follows it. */
+export const SIGNATURE_SEPARATOR = "-- ";
+
+type FooterCopy = MailingMessages["footer"];
+
+/** `text` with the unsubscribe footer under the signature separator. */
+export function addTextFooter(text: string, links: UnsubscribeLinks, copy: FooterCopy): string {
+  return [text, "", SIGNATURE_SEPARATOR, copy.text, links.page].join("\n");
+}
+
+/**
+ * `html` with an unsubscribe paragraph before its last `</body>`, or appended when it has none
+ * (a fragment). The copy is escaped; the link is ours and only needs its `&` escaped.
+ */
+export function addHtmlFooter(html: string, links: UnsubscribeLinks, copy: FooterCopy): string {
+  const footer = `<p>${escapeHtml(copy.htmlLead)} <a href="${escapeHtml(links.page)}">${escapeHtml(copy.htmlLink)}</a></p>`;
+  // Searched on the original string: lowercasing can change its length (`İ` becomes two characters).
+  const bodyEnd = [...html.matchAll(/<\/body>/gi)].at(-1)?.index;
+  return bodyEnd === undefined ? `${html}\n${footer}` : `${html.slice(0, bodyEnd)}${footer}\n${html.slice(bodyEnd)}`;
+}
+
+/**
+ * RFC 8058: the mail client shows "Unsubscribe" next to the sender and POSTs to this URL itself,
+ * without opening a page or a session. Both headers must be covered by the DKIM signature, which
+ * the provider applies to every header it sends.
+ */
+export function getListUnsubscribeHeaders(links: UnsubscribeLinks): Record<string, string> {
+  return {
+    "List-Unsubscribe": `<${links.oneClick}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+  };
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}

package/src/server/options.ts

@@ -0,0 +1,32 @@
+// The mailing options and routes of the running app, read from the configuration.
+import { getModule, type AnySoftureModule, type SoftureConfig } from "@softure-ai/core";
+import type { MailingOptions } from "../options.js";
+
+const MODULE_ID = "mailing";
+
+/** The paths of the unsubscribe page and the one-click route (overridable in `mailing({ routes })`). */
+export interface MailingRoutes {
+  readonly unsubscribe: string;
+  readonly oneClick: string;
+}
+
+/** The enabled module. Throws when the app did not enable it: sending then is a bug. */
+export function getMailingModule(config: SoftureConfig): AnySoftureModule {
+  const module = getModule(config, MODULE_ID);
+  if (module === undefined) {
+    throw new Error("@softure-ai/mailing: the module is not enabled; add mailing({ ... }) to modules in softure.config.ts");
+  }
+  return module;
+}
+
+/** The module's options. Throws when the app did not enable it. */
+export function getMailingOptions(config: SoftureConfig): MailingOptions {
+  // The module factory parsed these options with mailingOptionsSchema.
+  return getMailingModule(config).options as MailingOptions;
+}
+
+/** The module's routes, with the app's overrides. Throws when the app did not enable it. */
+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;
+}

package/src/server/send-mail.ts

@@ -0,0 +1,152 @@
+// Sends one mail through the configured provider. Ported from FIRE_TRACKER `src/lib/mail.ts` with
+// its three rules: it never throws for a failed send (every failure is a result), nothing of the
+// mail (address, subject, body, key) reaches a log or the result, and `headers` cannot replace the
+// envelope or the sender. List mail (any kind but `transactional`) also gets a signed unsubscribe
+// link in a footer and the RFC 8058 headers, and is refused for a recipient who unsubscribed.
+import { err, ok, type SoftureConfig } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { TRANSACTIONAL_KIND, type MailingErrorCode, type MailProvider, type OutgoingMail, type ProviderMessage, type ProviderOutcome, type SendMailOptions, type SendMailResult } from "../contract.js";
+import type { MailingMessages } from "../messages/index.js";
+import { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders } from "./list-mail.js";
+import { getMailingModule, getMailingOptions } from "./options.js";
+import { isSuppressed } from "./suppressions.js";
+import { buildUnsubscribeLinks, MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "./unsubscribe-link.js";
+import { validateMail, type ValidMail } from "./validate-mail.js";
+
+/**
+ * What `sendMail` needs: the app's configuration and, for list mail, the database handle (the
+ * suppression check reads it). Transactional mail needs no `db`.
+ */
+export interface MailContext {
+  readonly config: SoftureConfig;
+  readonly db?: Queryable;
+}
+
+type MailContent = Omit<ProviderMessage, "from" | "replyTo" | "idempotencyKey">;
+
+/**
+ * Sends `mail` and resolves with the provider's message id or a `mailing.*` code:
+ * `invalid_input` (fix the input), `rejected` (do not retry), `unavailable` (retry later with the
+ * same `idempotencyKey`), `suppressed` (a list mail to someone who unsubscribed; do not retry).
+ * Throws only when the module is not enabled, or for list mail without `context.db`.
+ */
+export async function sendMail(context: MailContext, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
+  const { from, replyTo, provider, timeoutMs } = getMailingOptions(context.config);
+
+  const validation = validateMail(mail, options);
+  if (!validation.ok) {
+    logFailure(provider, "mailing.invalid_input", { fields: validation.fields });
+    return err("mailing.invalid_input");
+  }
+
+  const { idempotencyKey, kind, ...content } = validation.value;
+  let message: MailContent = content;
+  if (kind !== TRANSACTIONAL_KIND) {
+    const listMail = await prepareListMail(context, validation.value);
+    if (!listMail.ok) {
+      logFailure(provider, listMail.error, { cause: listMail.cause });
+      return err(listMail.error);
+    }
+    message = listMail.value;
+  }
+
+  const outcome = await callProvider(provider, { ...message, from, replyTo: replyTo ?? null, idempotencyKey }, timeoutMs);
+  if (outcome.status === "sent") {
+    return ok({ id: outcome.id, provider: provider.name });
+  }
+  const code: MailingErrorCode = `mailing.${outcome.status}`;
+  logFailure(provider, code, { status: outcome.httpStatus });
+  return err(code);
+}
+
+type ListMailResult =
+  | { readonly ok: true; readonly value: MailContent }
+  | { readonly ok: false; readonly error: "mailing.suppressed" | "mailing.unavailable"; readonly cause: string };
+
+/**
+ * A list mail with its footer and headers, or why it must not go out. Fails closed: without the
+ * secret, or when the suppression list cannot be read, nothing is sent.
+ */
+async function prepareListMail(context: MailContext, mail: ValidMail): Promise<ListMailResult> {
+  if (context.db === undefined) {
+    throw new Error("@softure-ai/mailing: list mail needs the database handle; call sendMail({ config, db }, ...)");
+  }
+  const secret = readUnsubscribeSecrets().current;
+  if (secret === null) {
+    console.error(`mailing: list mail needs ${UNSUBSCRIBE_SECRET_ENV} (at least ${String(MIN_UNSUBSCRIBE_SECRET_LENGTH)} characters) to sign unsubscribe links`);
+    return { ok: false, error: "mailing.unavailable", cause: "no_unsubscribe_secret" };
+  }
+  let suppressed: boolean;
+  try {
+    suppressed = await isSuppressed({ db: context.db }, mail.to);
+  } catch {
+    // The error text can carry the query parameters, the recipient key among them.
+    return { ok: false, error: "mailing.unavailable", cause: "suppressions_unreadable" };
+  }
+  if (suppressed) return { ok: false, error: "mailing.suppressed", cause: "unsubscribed" };
+
+  const links = buildUnsubscribeLinks(context.config, mail.to, secret);
+  // The module factory merged the dictionaries; their shape is the module's own.
+  const copy = (getMailingModule(context.config).messages[context.config.locale] as MailingMessages).footer;
+  return {
+    ok: true,
+    value: {
+      to: mail.to,
+      subject: mail.subject,
+      text: addTextFooter(mail.text, links, copy),
+      html: mail.html === null ? null : addHtmlFooter(mail.html, links, copy),
+      headers: { ...mail.headers, ...getListUnsubscribeHeaders(links) },
+    },
+  };
+}
+
+/**
+ * The provider's outcome, `unavailable` when it throws, answers something else or outlives the
+ * timeout. The timer races the provider, so one that ignores its signal cannot hang the caller.
+ */
+async function callProvider(provider: MailProvider, message: Parameters<MailProvider["send"]>[0], timeoutMs: number): Promise<ProviderOutcome> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<ProviderOutcome>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort(new DOMException("mailing: the provider did not answer in time", "TimeoutError"));
+      resolve({ status: "unavailable" });
+    }, timeoutMs);
+  });
+  const sending = provider
+    .send(message, { signal: controller.signal })
+    .then(readOutcome, (): ProviderOutcome => ({ status: "unavailable" }));
+  try {
+    return await Promise.race([sending, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** A provider's answer, narrowed: anything that is not a known outcome reads as `unavailable`. */
+function readOutcome(outcome: unknown): ProviderOutcome {
+  if (typeof outcome !== "object" || outcome === null) return { status: "unavailable" };
+  const { status, id, httpStatus } = outcome as { status?: unknown; id?: unknown; httpStatus?: unknown };
+  if (status === "sent") {
+    return typeof id === "string" && id !== "" ? { status, id } : { status: "unavailable" };
+  }
+  if (status === "rejected" || status === "unavailable") {
+    return typeof httpStatus === "number" ? { status, httpStatus } : { status };
+  }
+  return { status: "unavailable" };
+}
+
+/**
+ * The module's only log line. Deliberately takes nothing but the provider, the code, a status,
+ * field names and a fixed cause: anything added "for diagnosis" is where an address leaks first.
+ */
+function logFailure(
+  provider: MailProvider,
+  code: MailingErrorCode,
+  details: { readonly status?: number; readonly fields?: readonly string[]; readonly cause?: string },
+): void {
+  const parts = [`provider=${provider.name}`, `reason=${code.slice("mailing.".length)}`, `status=${details.status === undefined ? "none" : String(details.status)}`];
+  if (details.fields !== undefined) parts.push(`fields=${details.fields.join(",")}`);
+  if (details.cause !== undefined) parts.push(`cause=${details.cause}`);
+  console.error(`mailing: send failed ${parts.join(" ")}`);
+}