@pithy-sh/email 0.1.0

package/src/send/suppression.ts

@@ -0,0 +1,194 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { decodeCursor, type PageCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
+import { EmailSuppression } from "../data/emailSuppression";
+import { type EmailKind, SuppressionReason } from "../data/enums";
+import type { EmailSuppressionDatabase } from "../data/tables";
+
+/**
+ * The suppression list: addresses that must not be emailed, fed by hard bounces, complaints, and
+ * unsubscribes. The send path checks it before every send and skips a match, naming the reason it
+ * skipped for.
+ *
+ * Every address here goes through `normalizeAddress` from core, so a check and a write agree on the
+ * key — and so does `auth` matching a sign-in, `support` linking a sender, and `testers` reading this
+ * very table. A suppression written under one rule and read under another is a suppression that does
+ * not suppress, and it reports itself as "the list did not work" rather than as anything about case.
+ *
+ * The list is also the one thing in this capability a management client both reads and writes, and it
+ * is **global** — one database shared by every environment, so a row here stops mail from staging and
+ * production alike. That is why reading it, adding to it, and removing from it are three separate
+ * control-plane scopes rather than one.
+ *
+ * **The reason is part of the answer, not just a label on the row.** The list is keyed by address and
+ * holds no memory of which message a person was refusing, so treating every reason alike meant one
+ * unsubscribe from a weekly digest also withheld that person's sign-in link — and passwordless has no
+ * password to fall back on. `suppressionBlocks` is where the four reasons stop being interchangeable.
+ */
+
+/**
+ * Whether a live suppression for this reason blocks a message of this kind.
+ *
+ * | reason | elective | transactional |
+ * |---|---|---|
+ * | `hard_bounce` | block | **block** — the mailbox does not exist. Sending is futile, and hammering dead addresses damages the sending domain for every other adopter on it. |
+ * | `complaint` | block | **block** — they reported us as spam. Continuing after a complaint is how a domain gets blocked outright. |
+ * | `unsubscribe` | block | **send** — an opt-out is a statement about mail somebody chose to receive. A sign-in link is not that; withholding it respects no preference, it locks the account. |
+ * | `manual` | block | block — an operator's deliberate act, and the one reason a human can point at. Narrowing it would silently overrule the person who set it. |
+ *
+ * Bounce and complaint are facts about the mailbox; unsubscribe and manual are decisions about mail.
+ * Only the unsubscribe decision is about a *category* of mail, which is why it is the only one the kind
+ * can narrow.
+ */
+export function suppressionBlocks(reason: SuppressionReason, kind: EmailKind): boolean {
+  if (reason === "unsubscribe") return kind === "elective";
+  return true;
+}
+
+/**
+ * The live suppression reason blocking a message of this kind, or `null` if nothing does.
+ *
+ * The kind is required rather than defaulted. A default would have to be one of the two, and the one
+ * that reads as safe — block everything — is the one that locks people out of their own accounts.
+ */
+export async function blockingSuppression(
+  db: EmailSuppressionDatabase,
+  email: string,
+  now: Date,
+  kind: EmailKind,
+): Promise<SuppressionReason | null> {
+  const row = await db
+    .selectFrom("pithyEmailSuppressions")
+    .select(["reason", "expiresAt"])
+    // The same key `suppress` writes under. A read normalized differently from the write is a
+    // suppression that silently stops suppressing.
+    .where("email", "=", normalizeAddress(email))
+    .executeTakeFirst();
+  if (!row) return null;
+  const live =
+    row.expiresAt === null || row.expiresAt === undefined || SQLiteDate.parse(row.expiresAt).getTime() > now.getTime();
+  if (!live) return null;
+  // Parsed, not cast: this crosses the D1 boundary, and an unrecognized reason must not fall through the
+  // `=== "unsubscribe"` test into "send it anyway". A row nobody can read is reported as `manual`, the
+  // one reason that claims no observed fact — it blocks, and it does not pretend to know why.
+  const parsed = SuppressionReason.safeParse(row.reason);
+  if (!parsed.success) return "manual";
+  return suppressionBlocks(parsed.data, kind) ? parsed.data : null;
+}
+
+/** Add (or refresh) a suppression for an address. Idempotent on the unique `email` column. */
+export async function suppress(
+  db: EmailSuppressionDatabase,
+  input: {
+    email: string;
+    reason: SuppressionReason;
+    jobId?: string | null;
+    environment?: string | null;
+    detail?: string | null;
+    expiresAt?: Date | null;
+  },
+  now: Date,
+): Promise<void> {
+  const email = normalizeAddress(input.email);
+  const jobId = input.jobId ?? null;
+  const environment = input.environment ?? null;
+  const detail = input.detail ?? null;
+  const expiresAt = input.expiresAt ? SQLiteDate.encode(input.expiresAt) : null;
+  await db
+    .insertInto("pithyEmailSuppressions")
+    .values({ email, reason: input.reason, jobId, environment, detail, expiresAt, createdAt: SQLiteDate.encode(now) })
+    .onConflict((oc) => oc.column("email").doUpdateSet({ reason: input.reason, jobId, environment, detail, expiresAt }))
+    .execute();
+}
+
+/**
+ * Remove a suppression. Returns whether a row was actually removed.
+ *
+ * The boolean matters: an operator unblocking an address that was never blocked, and one unblocking an
+ * address that was, are two different events and the audit trail should not record them as the same
+ * one. It also keeps the route idempotent — asking twice is not an error, it is simply the second one
+ * finding nothing to do.
+ *
+ * There is no soft delete. A suppression is a "do not send" flag, and a lifted flag that stays in the
+ * table is one bad query away from still being enforced.
+ */
+export async function unsuppress(db: EmailSuppressionDatabase, email: string): Promise<boolean> {
+  const result = await db
+    .deleteFrom("pithyEmailSuppressions")
+    .where("email", "=", normalizeAddress(email))
+    .executeTakeFirst();
+  return (result.numDeletedRows ?? 0n) > 0n;
+}
+
+/** What the suppression list filters and pages by. */
+export interface SuppressionListFilter {
+  /** One reason, or every reason when absent. */
+  reason?: SuppressionReason;
+  /** Look one address up exactly, rather than paging the list. */
+  email?: string;
+  /** The previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped into range. */
+  limit?: number;
+}
+
+/** One page of the suppression list. */
+export interface SuppressionPage {
+  /** The suppressed addresses, most recently blocked first. */
+  items: EmailSuppression[];
+  /** Where the next page starts, or null at the end of the list. */
+  nextCursor: string | null;
+}
+
+/**
+ * A cursor this table can resume from.
+ *
+ * Both halves must be numbers here — `createdAt` is a ms-epoch and `id` is an autoincrement integer —
+ * and anything else is treated exactly as a malformed cursor is. A string compared against an integer
+ * column in SQLite does not fail; it orders by something nobody meant, which is worse.
+ */
+function suppressionCursor(raw: string | undefined): { sort: number; id: number } | undefined {
+  const cursor: PageCursor | undefined = decodeCursor(raw);
+  if (!cursor || typeof cursor.sort !== "number" || typeof cursor.id !== "number") return undefined;
+  return { sort: cursor.sort, id: cursor.id };
+}
+
+/**
+ * One page of the suppression list, most recently blocked first.
+ *
+ * Keyset, never offset — the same rule every list in this repo follows, and it applies here even though
+ * the table is quieter than the job log: a hard bounce arriving mid-scroll would otherwise skip a row
+ * for the person reading it.
+ */
+export async function listSuppressions(
+  db: EmailSuppressionDatabase,
+  filter: SuppressionListFilter,
+): Promise<SuppressionPage> {
+  const limit = pageLimit(filter.limit);
+  const after = suppressionCursor(filter.cursor);
+
+  let query = db
+    .selectFrom("pithyEmailSuppressions")
+    .selectAll()
+    .orderBy("createdAt", "desc")
+    .orderBy("id", "desc")
+    .limit(limit + 1);
+
+  if (filter.reason) query = query.where("reason", "=", filter.reason);
+  // Exact equality on the normalized key, never a prefix or a LIKE: a lookup that also matched
+  // neighbors would be a way to enumerate the list one query at a time while looking like a question
+  // about a single address.
+  if (filter.email) query = query.where("email", "=", normalizeAddress(filter.email));
+  if (after) {
+    query = query.where((eb) =>
+      eb.or([eb("createdAt", "<", after.sort), eb.and([eb("createdAt", "=", after.sort), eb("id", "<", after.id)])]),
+    );
+  }
+
+  const rows = await query.execute();
+  const items = rows.map((row) => EmailSuppression.parse(row));
+  return toPage(items, limit, (row) => ({ sort: row.createdAt.getTime(), id: row.id }));
+}

package/src/templates/engine.ts

@@ -0,0 +1,392 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import Handlebars from "handlebars";
+import { mintToken } from "../crypto/token";
+import type { EmailKind } from "../data/enums";
+import { EmailInvalidPayloadError, EmailTemplateNotFoundError } from "../error/errors";
+import { emailTranslator, kitEmailLayers } from "./messages";
+import { precompiledPartials, precompiledTemplates } from "./precompiled.generated";
+import { type EmailTemplate, templates } from "./registry";
+import { severityColor, severityLabelKey } from "./severity";
+import { type EmailTheme, widthPx } from "./theme";
+
+/**
+ * The render engine. Templates are compiled **once at module load** — which in a Worker happens during
+ * isolate startup, where dynamic compilation is permitted — and cached, so a send never compiles or
+ * evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
+ * pure string substitution.
+ *
+ * Tracking is applied here, not in the template: callback tokens are minted ahead of render (signing
+ * is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
+ * Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
+ * template gets an unsubscribe link, which a marketing template additionally cannot render without.
+ *
+ * **A transactional template can never be given one.** The affordance is gated on the kind the template
+ * itself declares, so there is no argument a call site could pass to put an opt-out on a sign-in link —
+ * and `renderEmail` reports the URL it minted, so the send path sets `List-Unsubscribe` from what was
+ * actually rendered rather than from a second, drift-prone judgment of its own.
+ */
+
+/** The mount prefix of the callback routes. Tracking URLs are built against `${baseUrl}${CALLBACK_BASE}`. */
+export const CALLBACK_BASE = "/_pithy/email";
+
+// Build the engine from the **precompiled** specs (generated by `scripts/precompile.ts`).
+// `Handlebars.template(spec)` wraps spec functions that were defined at module-parse time — it never
+// calls `eval`/`new Function`, so this works in the Workers runtime, which forbids runtime code
+// generation entirely (CLAUDE.md §Email: "precompiled, no runtime compile/eval").
+const hbs = Handlebars.create();
+for (const [name, spec] of Object.entries(precompiledPartials)) {
+  hbs.registerPartial(name, hbs.template(spec));
+}
+
+// The only two helpers this engine has, and both exist for one reason: a severity has to be said in
+// three places — the subject line, the body, and the plain-text part — and a mapping repeated three
+// times is a mapping that will disagree with itself. Handlebars has no equality test, so without them a
+// template would carry nine `{{#if}}` blocks to render one word. Registered on this instance at module
+// load; precompiled specs resolve a helper by name at render time, so `scripts/precompile.ts` needs to
+// know nothing about them.
+hbs.registerHelper("severityColor", severityColor);
+
+/**
+ * The English every render falls back to — and the whole render when nothing composed an i18n
+ * capability, which is the seam's zero-config behavior everywhere else in the kit.
+ *
+ * Module-level and shared, because it holds no request state: a translator over one fixed catalog is a
+ * pure lookup table. The per-job translators the send path builds are the ones that carry a locale, and
+ * they live and die with one render.
+ */
+const ENGLISH: Translator = emailTranslator("en", kitEmailLayers);
+
+/** The key the render context carries its translator under. Read by the helpers, never by a template. */
+const TRANSLATOR_KEY = "i18n";
+
+/** The slice of Handlebars' helper options these helpers read. Declared rather than imported, to stay off `any`. */
+interface HelperContext {
+  /** The `key=value` arguments written on the helper call — the message's interpolation parameters. */
+  hash?: Record<string, unknown>;
+  /** Handlebars' data frame. `root` is the render context, which is where the translator rides. */
+  data?: { root?: unknown };
+}
+
+/** Whether a value is a translator, structurally — the seam is an interface, so there is no class to test. */
+function isTranslator(value: unknown): value is Translator {
+  return typeof (value as { t?: unknown } | null | undefined)?.t === "function";
+}
+
+/**
+ * The translator this render is going through, or the kit's English.
+ *
+ * Read off `@root` rather than closed over, because the engine is built once per isolate and a
+ * translator belongs to one message. A module-level "current locale" would be the same hazard
+ * `z.config()` is banned repo-wide for: an isolate serves many recipients, and the one holding the
+ * locale would apply the last render's language to the next.
+ */
+function translatorOf(options: HelperContext): Translator {
+  const held = (options.data?.root as Record<string, unknown> | undefined)?.[TRANSLATOR_KEY];
+  return isTranslator(held) ? held : ENGLISH;
+}
+
+/** The helper's `key=value` arguments as message parameters — scalars only, like every catalog value. */
+function messageParams(hash: Record<string, unknown> | undefined): MessageParams {
+  const params: MessageParams = {};
+  for (const [name, value] of Object.entries(hash ?? {})) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") params[name] = value;
+  }
+  return params;
+}
+
+/**
+ * `{{t "email/magic_link.heading"}}` — one catalog message, with `key=value` interpolation.
+ *
+ * It returns a plain string and **never** a `SafeString`. That is the security constraint, not a style
+ * choice: the HTML body escapes what a mustache produces, so a catalog value — the kit's, or the one
+ * sentence an adopter overrode it with — is escaped on exactly the path a payload value is. `subject`
+ * and `text` are precompiled with `noEscape`, where nothing is escaped and nothing needs to be, which
+ * is why no catalog value in this kit carries markup and why `docs/I18N.md` says so to adopters.
+ */
+hbs.registerHelper("t", (key: unknown, options: HelperContext): string =>
+  translatorOf(options).t(String(key), messageParams(options.hash)),
+);
+
+/**
+ * `{{tn "email/otp.expiry" count=expiresMinutes}}` — the plural form the count calls for.
+ *
+ * Separate from `t` because plural selection is the thing a second locale exposes: "It expires in 1
+ * minutes" was already wrong in English and unfixable without it, and Russian needs three forms where
+ * English needs two. The count is a hash argument rather than a positional one so that a payload field
+ * reaching a template through this helper is still visible to `engine.test.ts`'s check that every
+ * variable a template renders is declared on its payload schema.
+ */
+hbs.registerHelper("tn", (key: unknown, options: HelperContext): string => {
+  const params = messageParams(options.hash);
+  return translatorOf(options).plural(String(key), Number(params.count ?? 0), params);
+});
+
+/** `{{severityLabel severity}}` — the level's word, in the reader's language. */
+hbs.registerHelper("severityLabel", (severity: unknown, options: HelperContext): string =>
+  translatorOf(options).t(severityLabelKey(severity)),
+);
+
+interface Compiled {
+  def: EmailTemplate;
+  subject: HandlebarsTemplateDelegate;
+  html: HandlebarsTemplateDelegate;
+  text: HandlebarsTemplateDelegate;
+}
+
+function delegate(key: string): HandlebarsTemplateDelegate {
+  const spec = (precompiledTemplates as Record<string, unknown>)[key];
+  if (!spec) throw new Error(`missing precompiled template spec '${key}' — run \`bun run precompile\``);
+  return hbs.template(spec);
+}
+
+const compiled = new Map<string, Compiled>(
+  Object.values(templates).map((def) => [
+    def.id,
+    { def, subject: delegate(`${def.id}:subject`), html: delegate(`${def.id}:html`), text: delegate(`${def.id}:text`) },
+  ]),
+);
+
+/** The signing + addressing context a tracked render needs. Shaped to plug straight into the send path. */
+export interface RenderTracking {
+  /** The public base URL of the app worker; callback links are built against it. */
+  baseUrl: string;
+  /** The job this render belongs to — embedded in every token. */
+  jobId: string;
+  /** The recipient address — embedded in every token. */
+  recipient: string;
+  /** The marketing campaign id, for click/open attribution. */
+  campaignId?: string;
+  /** The current signing key value (from `@pithy-sh/secrets`). */
+  key: string;
+  /** The current signing key version, recorded as the token `kid`. */
+  kid: string;
+  /** When the tokens (and so the links) expire. */
+  expiresAt: Date;
+  /** Whether to inject the open-tracking pixel. */
+  openTracking: boolean;
+  /** Whether to rewrite links to tracked click callbacks. */
+  clickTracking: boolean;
+}
+
+/** A rendered email: the three parts a send needs, plus the opt-out URL it actually carries. */
+export interface RenderResult {
+  subject: string;
+  html: string;
+  text: string;
+  /**
+   * The unsubscribe URL rendered into the body, when one was. Present only for an elective template with
+   * a signing context; the send path turns it into the `List-Unsubscribe` header, so the header and the
+   * link in the body can never disagree about whether this message can be opted out of.
+   */
+  unsubscribeUrl?: string;
+}
+
+/** Look up a template by id, or throw `email/template_not_found`. */
+export function getTemplate(id: string): EmailTemplate {
+  const found = compiled.get(id);
+  if (!found) throw new EmailTemplateNotFoundError({ detail: `no template registered with id '${id}'` });
+  return found.def;
+}
+
+/**
+ * The kind a template declares — the one answer to "may this message be refused".
+ *
+ * An id nobody registered is reported as `elective`, deliberately. It cannot be *proved* transactional,
+ * and the alternative reading would let a template deleted in a later release quietly reopen sending to
+ * addresses that opted out. Nothing is locked out by the choice: a job naming an unknown template fails
+ * at render moments later either way, so this only decides which of two failures gets reported.
+ */
+export function templateKind(templateId: string): EmailKind {
+  return compiled.get(templateId)?.def.kind ?? "elective";
+}
+
+/**
+ * Whether this template's payload is dropped once the message is delivered.
+ *
+ * **Keyed on the category, not the kind.** The kind answers "may this be refused"; this question is
+ * "are these inputs a one-time credential". `testerNudge` is the template that proves they are
+ * different axes — it is *elective*, because somebody may say stop chasing me, and its payload carries
+ * an opt-in URL that authenticates a tester. Keying on the kind would have left exactly that one live.
+ *
+ * A transactional message is a reply to something one person just did, and its payload is that
+ * person's one-time input: a sign-in URL, a code, an invitation token. A marketing message's payload is
+ * copy authored for a batch, carrying no per-recipient credential and answering the real question
+ * "what did the forty thousand of them actually receive". So the category is the line, and it falls in
+ * the right place on every template in the registry.
+ *
+ * There is no per-template override, because no template needs one today and an escape hatch nobody
+ * uses is where the bug comes back. The day a marketing template carries a per-recipient credential,
+ * the override is the change to make — with a reason written beside it.
+ *
+ * An id nobody registered redacts, which is the safe direction and, like `templateKind`, decides
+ * nothing real: a job naming an unknown template fails at render and never reaches a delivery.
+ */
+export function redactsPayloadOnDelivery(templateId: string): boolean {
+  return compiled.get(templateId)?.def.category !== "marketing";
+}
+
+/** The registered template ids, for introspection and the CLI. */
+export function listTemplates(): EmailTemplate[] {
+  return Object.values(templates);
+}
+
+/**
+ * Validate a payload against its template and render just the subject line. Used at enqueue to fail
+ * fast on a bad payload and to store the job's subject without rendering the whole body. Throws
+ * `email/template_not_found` or `email/invalid_payload`.
+ */
+export function renderSubject(
+  templateId: string,
+  payload: unknown,
+  theme: EmailTheme,
+  translator: Translator = ENGLISH,
+): string {
+  const entry = compiled.get(templateId);
+  if (!entry) throw new EmailTemplateNotFoundError({ detail: `no template registered with id '${templateId}'` });
+  const parsed = entry.def.payload.safeParse(payload);
+  if (!parsed.success) {
+    const summary = parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}:${i.code}`).join(", ");
+    throw new EmailInvalidPayloadError({ detail: `template '${templateId}' payload invalid: ${summary}` });
+  }
+  return entry.subject(renderContext(parsed.data as Record<string, unknown>, entry, theme, translator)).trim();
+}
+
+/**
+ * The render context: the parsed payload, the theme, and what the shell needs to be written in a
+ * language.
+ *
+ * One builder for both render sites, because the two used to assemble it separately and the *subject*
+ * is the field they were most able to disagree about — `renderSubject` runs at enqueue and `renderEmail`
+ * runs at send, and until the locale landed on the row there was nothing tying them to one language.
+ */
+function renderContext(
+  payload: Record<string, unknown>,
+  entry: Compiled,
+  theme: EmailTheme,
+  translator: Translator,
+): Record<string, unknown> {
+  return {
+    ...payload,
+    theme,
+    layoutWidth: widthPx(entry.def.width),
+    // What the document declares itself as. `lang` is the catalog locale — the language the words are
+    // actually in — and `dir` is what an RTL reader's client needs before it lays anything out.
+    lang: translator.catalogLocale,
+    dir: translator.direction,
+    [TRANSLATOR_KEY]: translator,
+  };
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+/** Rewrite one declared link path (`"url"` or `"articles[].link"`) in the context through `makeUrl`. */
+async function rewriteLink(
+  context: Record<string, unknown>,
+  path: string,
+  label: string,
+  makeUrl: (destination: string, label: string) => Promise<string>,
+): Promise<void> {
+  const arrayMatch = path.split("[].");
+  if (arrayMatch.length === 2) {
+    const arrayKey = arrayMatch[0];
+    const field = arrayMatch[1];
+    if (!arrayKey || !field) return;
+    const items = context[arrayKey];
+    if (Array.isArray(items)) {
+      for (let i = 0; i < items.length; i += 1) {
+        const item = items[i] as Record<string, unknown>;
+        if (item && typeof item[field] === "string")
+          item[field] = await makeUrl(item[field] as string, `${label}-${i}`);
+      }
+    }
+    return;
+  }
+  if (typeof context[path] === "string") context[path] = await makeUrl(context[path] as string, label);
+}
+
+/**
+ * Render a template to `{ subject, html, text }`. Validates the payload against the template's schema
+ * (throws `email/invalid_payload`), applies click/open tracking and — for an elective template — the
+ * unsubscribe link, then substitutes. A marketing template with no tracking context throws: it cannot
+ * render without an unsubscribe link.
+ *
+ * The opt-out rule is two-tier on purpose. Every elective template carries the link *when the engine can
+ * mint one*; a marketing template additionally *refuses to render* without it. Tying the hard refusal to
+ * the kind instead would mean a project that has not configured a link-signing key suddenly cannot send
+ * its testing-cohort nudges — a new outage, in a change whose whole subject is mail that fails silently.
+ */
+export async function renderEmail(
+  templateId: string,
+  payload: unknown,
+  theme: EmailTheme,
+  tracking?: RenderTracking,
+  translator: Translator = ENGLISH,
+): Promise<RenderResult> {
+  const entry = compiled.get(templateId);
+  if (!entry) throw new EmailTemplateNotFoundError({ detail: `no template registered with id '${templateId}'` });
+
+  const parsed = entry.def.payload.safeParse(payload);
+  if (!parsed.success) {
+    const summary = parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}:${i.code}`).join(", ");
+    throw new EmailInvalidPayloadError({ detail: `template '${templateId}' payload invalid: ${summary}` });
+  }
+
+  const isMarketing = entry.def.category === "marketing";
+  const isElective = entry.def.kind === "elective";
+  if (isMarketing && !tracking) {
+    throw new EmailInvalidPayloadError({
+      message: "Marketing emails require an unsubscribe link.",
+      detail: `template '${templateId}' is marketing but no signing/tracking context was provided`,
+    });
+  }
+
+  const context: Record<string, unknown> = renderContext(
+    parsed.data as Record<string, unknown>,
+    entry,
+    theme,
+    translator,
+  );
+  let unsubscribeUrl: string | undefined;
+
+  if (tracking) {
+    const base = trimTrailingSlash(tracking.baseUrl) + CALLBACK_BASE;
+    const mint = (kind: "click" | "open" | "unsubscribe", extra: { destination?: string; linkLabel?: string }) =>
+      mintToken(
+        { kind, jobId: tracking.jobId, recipient: tracking.recipient, campaignId: tracking.campaignId, ...extra },
+        { key: tracking.key, kid: tracking.kid, expiresAt: tracking.expiresAt },
+      );
+
+    if (tracking.clickTracking) {
+      for (const link of entry.def.links) {
+        await rewriteLink(context, link.path, link.label, async (destination, label) => {
+          const token = await mint("click", { destination, linkLabel: label });
+          return `${base}/c/${token}`;
+        });
+      }
+    }
+
+    if (tracking.openTracking) {
+      context.openPixelUrl = `${base}/o/${await mint("open", {})}.png`;
+    }
+
+    // Elective mail carries an unsubscribe link; transactional mail never does. Keyed on the kind the
+    // template declared, so this cannot be reached for a sign-in link by any argument a caller passes.
+    if (isElective) {
+      unsubscribeUrl = `${base}/u/${await mint("unsubscribe", {})}`;
+      context.unsubscribeUrl = unsubscribeUrl;
+    }
+  }
+
+  return {
+    subject: entry.subject(context).trim(),
+    html: entry.html(context),
+    text: entry.text(context),
+    ...(unsubscribeUrl ? { unsubscribeUrl } : {}),
+  };
+}