@softure-ai/mailing 0.1.8 → 0.1.10

package/src/index.ts

@@ -17,7 +17,7 @@ export const MODULE_ID = "mailing";
 export const mailing = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.8",
+    version: "0.1.10",
     dependsOn: {},
     dbSchema: "mailing",
     tables: ["suppressions", "campaigns", "deliveries"],
@@ -68,7 +68,9 @@ export { HALTING_ERROR_CODES, TRANSACTIONAL_KIND } from "./contract.js";
 export type {
   CampaignRecipient,
   CampaignRecipientFilter,
+  CampaignRecipientSource,
   LegacyUnsubscribe,
+  LegacyUnsubscribeParams,
   MailingErrorCode,
   MailProvider,
   OnUnsubscribedHook,
@@ -83,6 +85,7 @@ export type {
   SuppressionSource,
   UnsubscribeErrorCode,
   UnsubscribeEvent,
+  VerifiedUnsubscribeLink,
 } from "./contract.js";
 export { getMailingErrorMessage, mailingMessages, type MailingMessages } from "./messages/index.js";
 export { DEFAULT_STALE_CLAIM_MS, DEFAULT_TIMEOUT_MS, DEFAULT_UNCERTAIN_CLAIM_MS, type MailingOptions, type MailingOptionsInput } from "./options.js";

package/src/next/import-deliveries.ts

@@ -0,0 +1,9 @@
+// `importDeliveries` on the app's registered configuration and the shared database, e.g. for a one-off route or
+// script that seeds the ledger from the app's own history.
+import { importDeliveries as importDeliveriesWithContext, type ImportedDelivery, type ImportResult } from "../server/import-deliveries.js";
+import { getMailingContext } from "./context.js";
+
+/** Seeds the delivery ledger; see `importDeliveries` in `@softure-ai/mailing/server`. */
+export async function importDeliveries(rows: readonly ImportedDelivery[]): Promise<ImportResult> {
+  return importDeliveriesWithContext(await getMailingContext(), rows);
+}

package/src/next/index.ts

@@ -3,6 +3,7 @@
 // (docs/02-module-standard.md §8).
 export { unsubscribeAction } from "./actions.js";
 export { deliverOnce } from "./deliver-once.js";
+export { importDeliveries } from "./import-deliveries.js";
 export { getMailingMessages } from "./messages.js";
 export { UnsubscribePage, type UnsubscribePageProps } from "./pages.js";
 export { UNSUBSCRIBE_STATUS_PARAM, type UnsubscribeStatus } from "./params.js";

package/src/next/route.ts

@@ -10,7 +10,7 @@
 // the only write is an idempotent insert.
 import { errorLogLabel } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
-import { getMailingRoutes } from "../server/options.js";
+import { getMailingOptions, getMailingRoutes } from "../server/options.js";
 import { unsubscribe } from "../server/suppressions.js";
 import { readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { getMailingContext } from "./context.js";
@@ -20,8 +20,9 @@ const NO_STORE = { "cache-control": "no-store" };
 /**
  * Records the opt-out of the link in the URL. The body (`List-Unsubscribe=One-Click`) is not read:
  * anyone can send it, the signature is the proof. 200 once recorded (also again), 400 for a link
- * that does not verify, 500 when the database fails: the client may retry, and 200 would claim an
- * opt-out that did not happen. A legacy link (`mailing({ legacyUnsubscribe })`) is handled the same
+ * that does not verify (200 with `mailing({ oneClickInvalidLinkStatus: 200 })`, so the answer never
+ * tells whether a token is live), 500 when the database fails: the client may retry, and 200 would
+ * claim an opt-out that did not happen. A legacy link (`mailing({ legacyUnsubscribe })`) is handled the same
  * way; mount this route at the old link's path too.
  */
 export async function postUnsubscribeRoute(request: Request): Promise<Response> {
@@ -29,7 +30,7 @@ export async function postUnsubscribeRoute(request: Request): Promise<Response>
     const ctx = await getMailingContext();
     const link = readUnsubscribeLink(new URL(request.url).searchParams, ctx.config);
     const result = await unsubscribe(ctx, link, "one-click");
-    return new Response(null, { status: result.ok ? 200 : 400, headers: NO_STORE });
+    return new Response(null, { status: result.ok ? 200 : getMailingOptions(ctx.config).oneClickInvalidLinkStatus, headers: NO_STORE });
   } catch (error) {
     console.error(`@softure-ai/mailing: one-click unsubscribe failed: ${errorLogLabel(error)}`);
     return new Response(null, { status: 500, headers: NO_STORE });

package/src/options.ts

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

package/src/schema.ts

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

package/src/server/campaigns.ts

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

package/src/server/deliveries.ts

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

package/src/server/import-deliveries.ts

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

package/src/server/index.ts

@@ -3,6 +3,7 @@
 export { getCampaignProblems, parseCampaignFile, parseRecipientList, type CampaignContent, type CampaignFile, type CampaignFileResult } from "./campaign-file.js";
 export {
   getCampaignContentHash,
+  listConfiguredCampaignRecipients,
   planCampaign,
   registerCampaign,
   sendCampaign,
@@ -17,6 +18,7 @@ export {
   DEFAULT_STALE_CLAIM_MS,
   DEFAULT_UNCERTAIN_CLAIM_MS,
   deliverOnce,
+  isDeliveryScope,
   type DeliverOptions,
   type Delivery,
   type DeliveryContext,
@@ -44,6 +46,16 @@ export {
   type SenderDnsReport,
 } from "./dns.js";
 export { checkMailingTables } from "./health.js";
+export {
+  checkImportedDeliveries,
+  importDeliveries,
+  type ImportCheck,
+  type ImportedDelivery,
+  type ImportedRejectionReason,
+  type ImportProblem,
+  type ImportResult,
+  type ImportSummary,
+} from "./import-deliveries.js";
 export { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders, SIGNATURE_SEPARATOR } from "./list-mail.js";
 export { getMailingModule, getMailingOptions, getMailingRoutes, type MailingRoutes } from "./options.js";
 export { sendMail, type MailContext } from "./send-mail.js";

package/src/server/send-mail.ts

@@ -1,7 +1,7 @@
-// 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
+// Sends one mail through the configured provider, with 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 (a mail's own reply-to is
+// the `replyTo` field, checked like `to`). 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";
@@ -51,7 +51,7 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
     return err("mailing.invalid_input");
   }
 
-  const { idempotencyKey, kind, ...content } = validation.value;
+  const { idempotencyKey, kind, replyTo: mailReplyTo, ...content } = validation.value;
   let message: MailContent = content;
   if (kind !== TRANSACTIONAL_KIND) {
     const listMail = await prepareListMail(context, validation.value);
@@ -62,7 +62,7 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
     message = listMail.value;
   }
 
-  const outcome = await callProvider(provider, { ...message, from, replyTo: replyTo ?? null, idempotencyKey }, timeoutMs);
+  const outcome = await callProvider(provider, { ...message, from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey }, timeoutMs);
   if (outcome.status === "sent") {
     return ok({ id: outcome.id, provider: provider.name });
   }

package/src/server/suppressions.ts

@@ -6,7 +6,7 @@
 import { err, ok, type ModuleContext, type Result } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import { and, eq, inArray } from "drizzle-orm";
-import type { SuppressionSource, UnsubscribeErrorCode } from "../contract.js";
+import type { SuppressionSource, UnsubscribeErrorCode, VerifiedUnsubscribeLink } from "../contract.js";
 import { suppressions } from "../schema.js";
 import { getMailingOptions } from "./options.js";
 import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeLink, type UnsubscribeToken } from "./unsubscribe-link.js";
@@ -67,26 +67,33 @@ export async function unsubscribe(
   source: Exclude<SuppressionSource, "operator">,
   env: Env = process.env,
 ): Promise<Result<undefined, UnsubscribeErrorCode>> {
-  const recipientKey = await verifyLink(ctx, link, env);
-  if (recipientKey === null) return err("mailing.invalid_link");
+  const verified = await verifyLink(ctx, link, env);
+  if (verified === null) return err("mailing.invalid_link");
+  const { recipientKey } = verified;
   const { onUnsubscribed } = getMailingOptions(ctx.config);
   await ctx.db.transaction(async (tx) => {
     const txCtx: SuppressionContext = { ...ctx, db: tx };
     await recordSuppression(txCtx, recipientKey, source);
-    await onUnsubscribed?.({ recipientKey, source }, txCtx);
+    await onUnsubscribed?.({ recipientKey, source, link: verified.link }, txCtx);
   });
   return ok();
 }
 
-/** The recipient key a link proves, or `null` when it proves none. */
-async function verifyLink(ctx: SuppressionContext, link: UnsubscribeLink | UnsubscribeToken | null, env: Env): Promise<string | null> {
+interface VerifiedLink {
+  readonly recipientKey: string;
+  readonly link: VerifiedUnsubscribeLink;
+}
+
+/** The recipient key a link proves and the link it came through, or `null` when it proves none. */
+async function verifyLink(ctx: SuppressionContext, link: UnsubscribeLink | UnsubscribeToken | null, env: Env): Promise<VerifiedLink | null> {
   if (link === null) return null;
   if (!("scheme" in link) || link.scheme === "signed") {
     const token = "scheme" in link ? link.token : link;
-    return verifyUnsubscribeToken(token, readUnsubscribeSecrets(env)) ? token.recipientKey : null;
+    return verifyUnsubscribeToken(token, readUnsubscribeSecrets(env)) ? { recipientKey: token.recipientKey, link: { scheme: "signed" } } : null;
   }
   const legacy = getMailingOptions(ctx.config).legacyUnsubscribe;
   if (legacy === undefined) return null;
   const address: unknown = await legacy.verify(link.values, ctx);
-  return typeof address === "string" && address.trim() !== "" ? getRecipientKey(address) : null;
+  if (typeof address !== "string" || address.trim() === "") return null;
+  return { recipientKey: getRecipientKey(address), link: { scheme: "legacy", values: link.values } };
 }

package/src/server/unsubscribe-link.ts

@@ -117,8 +117,9 @@ export interface LinkParams {
 /**
  * The link in a query or a form. A link with the recipient parameter (`r`) is a signed link, whatever else it
  * carries, so a crafted URL cannot route a signed link to the app's legacy check. Without it, and with
- * `mailing({ legacyUnsubscribe })`, a link that has every legacy parameter (non-empty, at most 512 characters) is
- * a legacy link. Anything else is `null`. Checks no signature: `unsubscribe` does.
+ * `mailing({ legacyUnsubscribe })`, a link that has every required legacy parameter (non-empty, at most 512
+ * characters) is a legacy link; its values also hold the optional parameters it has (an empty one is absent, one
+ * over 512 characters makes the link invalid). Anything else is `null`. Checks no signature: `unsubscribe` does.
  */
 export function readUnsubscribeLink(params: LinkParams, config: SoftureConfig): UnsubscribeLink | null {
   if (params.get(RECIPIENT_PARAM) !== null && params.get(RECIPIENT_PARAM) !== undefined) {
@@ -128,11 +129,17 @@ export function readUnsubscribeLink(params: LinkParams, config: SoftureConfig):
   const legacy = getMailingOptions(config).legacyUnsubscribe;
   if (legacy === undefined) return null;
   const values: Record<string, string> = {};
-  for (const name of legacy.params) {
+  for (const name of legacy.params.required) {
     const value = params.get(name);
     if (typeof value !== "string" || value === "" || value.length > MAX_LEGACY_VALUE_LENGTH) return null;
     values[name] = value;
   }
+  for (const name of legacy.params.optional) {
+    const value = params.get(name);
+    if (typeof value !== "string" || value === "") continue;
+    if (value.length > MAX_LEGACY_VALUE_LENGTH) return null;
+    values[name] = value;
+  }
   return { scheme: "legacy", values };
 }
 

package/src/server/validate-mail.ts

@@ -23,6 +23,7 @@ const mailSchema = z.object({
     .refine((html) => html.trim() !== "")
     .optional(),
   headers: headersSchema.optional(),
+  replyTo: z.string().trim().refine(isSingleAddress).optional(),
   kind: z.string().refine(isMailKind).default(TRANSACTIONAL_KIND),
 }).superRefine((mail, context) => {
   // The module writes these two on list mail; a second, unsigned copy would confuse clients.
@@ -41,6 +42,8 @@ export interface ValidMail {
   readonly text: string;
   readonly html: string | null;
   readonly headers: Readonly<Record<string, string>>;
+  /** The mail's own reply-to; null to use the configured one. */
+  readonly replyTo: string | null;
   /** `transactional` or a list kind. */
   readonly kind: string;
   readonly idempotencyKey: string | null;
@@ -50,7 +53,7 @@ export type MailValidation = { readonly ok: true; readonly value: ValidMail } |
 
 /**
  * Checks one mail and its send options. `fields` lists what failed (`to`, `subject`, `text`,
- * `html`, `headers`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
+ * `html`, `headers`, `replyTo`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
  */
 export function validateMail(mail: unknown, options: unknown = {}): MailValidation {
   const parsedMail = mailSchema.safeParse(mail);
@@ -60,9 +63,9 @@ export function validateMail(mail: unknown, options: unknown = {}): MailValidati
     const fields = new Set(issues.map((issue) => (issue.path.length === 0 ? "mail" : String(issue.path[0]))));
     return { ok: false, fields: [...fields] };
   }
-  const { to, subject, text, html, headers, kind } = parsedMail.data;
+  const { to, subject, text, html, headers, replyTo, kind } = parsedMail.data;
   return {
     ok: true,
-    value: { to, subject, text, html: html ?? null, headers: headers ?? {}, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
+    value: { to, subject, text, html: html ?? null, headers: headers ?? {}, replyTo: replyTo ?? null, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
   };
 }