@pithy-sh/email 0.1.0

package/src/data/emailJob.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { Locale } from "@pithy-sh/core/src/i18n/locale";
+import { z } from "zod";
+import { EmailJobStatus, SendMode, TemplateCategory } from "./enums";
+
+/**
+ * The template input variables, stored as a JSON column. The per-template Zod payload schema
+ * validates these before a job is enqueued; the row keeps the validated object so the send Workflow
+ * can re-render without the caller present. A bag of strings/unknowns at the row level — the template
+ * id plus this payload reconstruct the email.
+ */
+export const EmailJobPayload = z
+  .record(z.string(), z.unknown())
+  .describe(
+    "The validated template input variables for this job, re-rendered by the send Workflow. Empty once `payloadRedactedAt` is set — a transactional job's inputs are dropped when the message goes out.",
+  );
+export type EmailJobPayload = z.output<typeof EmailJobPayload>;
+
+/**
+ * What the `payload` column holds once a job's inputs are spent.
+ *
+ * An empty object, encoded through the same codec every other write uses rather than written as a
+ * `"{}"` literal — a column this schema could not read back would turn a delivered job into a row that
+ * throws when an operator opens it. The fact that it *was* redacted is `payloadRedactedAt`; this is
+ * only what is left where the variables were.
+ */
+export const SPENT_PAYLOAD = sqliteJson(EmailJobPayload).encode({});
+
+/**
+ * One row in `pithy_email_jobs` — the spine of the capability. Every email is a row first: a request
+ * handler only ever enqueues one, and the actual send always runs inside a Workflow. `z.output` is the
+ * app shape (Dates, booleans); `z.input` is the SQLite row (ms-epoch, 0|1, JSON string).
+ */
+export const EmailJob = z
+  .object({
+    id: z
+      .string()
+      .describe(
+        "UUID primary key. Text, not autoincrement, so a job id embedded in a tracking link cannot be enumerated.",
+      ),
+    toAddress: z
+      .string()
+      .describe("The recipient's email address. Lowercased and checked against the suppression list before sending."),
+    recipientKey: z
+      .string()
+      .describe(
+        "The recipient under `normalizeAddress` — the one form every comparison in the kit is against, and the only column anything matches a recipient on. `toAddress` deliberately keeps what the caller typed, because an operator diagnosing a send needs to see the string that was actually addressed; that makes it useless as a key, since `Ada@example.com` and `ada@example.com` are one mailbox and two rows. Doing the folding in SQL instead would not work: SQLite's `lower()` is ASCII-only while `normalizeAddress` is `toLowerCase()`, so the two disagree on exactly the addresses nobody tests with. The same value `pithy_email_events.recipient` is keyed on, so a job and its events agree on who the person is.",
+      ),
+    fromAddress: z.string().describe("The sender address. Must use a domain onboarded onto Cloudflare Email Service."),
+    fromName: z.string().describe("The sender display name recipients see in their inbox."),
+    subject: z.string().describe("The rendered subject line."),
+    template: z.string().describe("The template id (e.g. `magicLink`, `newsletter`) used to render this email."),
+    category: TemplateCategory.describe(
+      "The template's category — drives unsubscribe enforcement and tracking defaults.",
+    ),
+    payload: sqliteJson(EmailJobPayload).describe(
+      "The validated template input variables, as a JSON column. Emptied when the message is delivered, for every template whose category is `transactional` — see `payloadRedactedAt`.",
+    ),
+    payloadRedactedAt: SQLiteDate.nullish().describe(
+      "When this job's inputs were dropped, or null while it still holds them. A magic link's payload *is* the sign-in link, so keeping it after delivery is a second, permanent copy of a credential in a table nobody thinks of as holding secrets. Null and an empty payload mean different things — the first is a job enqueued with no variables, the second is one whose variables were spent — which is why this is a timestamp and not the absence of data.",
+    ),
+    status: EmailJobStatus.describe("The job's lifecycle state."),
+    mode: SendMode.describe("How this job's send time was determined."),
+    attempts: z.number().int().describe("How many send attempts have been made; incremented on each Workflow try."),
+    batchId: z
+      .string()
+      .nullish()
+      .describe(
+        "The send batch holding this job — the id of the send Workflow instance dispatched for it, minted by whoever claimed it. Null for a job nothing has claimed. This *is* the claim: liveness belongs to the batch, not to a row, so the scheduler asks the Workflow runtime whether this instance is still running rather than inferring it from how long ago the row was written.",
+      ),
+    sendAt: SQLiteDate.describe("The absolute time this job should send. Equal to creation time for immediate sends."),
+    timezone: z.string().nullish().describe("The recipient's IANA timezone for `timezone` mode; null otherwise."),
+    localTime: z
+      .string()
+      .nullish()
+      .describe("The recipient-local time-of-day (e.g. `10:00`) for `timezone` mode; null otherwise."),
+    campaignId: z
+      .string()
+      .nullish()
+      .describe("The marketing campaign this job belongs to, for click/open attribution; null for transactional."),
+    locale: Locale.nullish().describe(
+      "The language this message is written in, as a BCP-47 tag; null when the recipient never chose one. **Null is not `en`** — it means nothing was chosen, so the render falls back to the kit's English rather than asserting English was picked, the same distinction `pithy_auth_users.locale` draws. It lives on the row because the two renders happen in different places at different times: the subject at enqueue, inside a request that knows the reader, and the body at send, inside a Workflow with no request on it at all. Without a stored locale those two could agree only by accident, and an operator opening a send log had nothing that explained why a subject read the way it did.",
+    ),
+    correlation: z
+      .string()
+      .nullish()
+      .describe(
+        "What this message was *about*, as the caller names it — the discriminator for a template that carries more than one kind of message. Opaque here: this capability never parses it, never renders it, and never puts it on a header or a link. Set at enqueue, matched by `sentSince`, indexed with `createdAt`. **Not `campaignId`**, which is documented marketing-only and is not merely a naming preference: `campaignId` is copied onto every `pithy_email_events` row, grouped by `campaignStats`, and signed into the click/open tracking token that travels in the URL of a delivered email — so a transactional discriminator put there would land in campaign analytics and in a string the recipient's mail client fetches. This column goes nowhere but this row. Null for a template whose id already says everything about what the message is, which is most of them.",
+      ),
+    openTracking: SQLiteBoolean.describe("Whether an open-tracking pixel was injected into the rendered HTML."),
+    clickTracking: SQLiteBoolean.describe("Whether links were rewritten to tracked click-callback URLs."),
+    messageId: z
+      .string()
+      .nullish()
+      .describe(
+        "The Email Service message id returned on send — the handle that ties an inbound bounce back to this job.",
+      ),
+    error: z
+      .string()
+      .nullish()
+      .describe("The last error code/message recorded on a failed or retried send; null when healthy."),
+    bounceCode: z
+      .string()
+      .nullish()
+      .describe("The SMTP or Email Service code from a bounce/complaint; null unless the job bounced."),
+    bounceType: z
+      .string()
+      .nullish()
+      .describe(
+        "The classification of a bounce (`hard`/`soft`/`complaint`/`auto_reply`); null unless the job bounced.",
+      ),
+    replyTo: z
+      .string()
+      .nullish()
+      .describe(
+        "The `Reply-To` address, when this job should be answered somewhere other than `fromAddress` — a support inbox replying from a no-reply sender is the case this exists for. Null for an ordinary send.",
+      ),
+    inReplyTo: z
+      .string()
+      .nullish()
+      .describe(
+        "The `In-Reply-To` header value, angle brackets included — the message this one answers. Null unless this job is a reply.",
+      ),
+    references: z
+      .string()
+      .nullish()
+      .describe(
+        "The `References` header value, angle-bracketed and space-separated. Stored as the wire string rather than a JSON array because that is exactly what goes on the header, and re-deriving it at send time is a second chance to get threading wrong. Null unless this job is a reply.",
+      ),
+    createdAt: SQLiteDate.describe("When the job row was created."),
+    updatedAt: SQLiteDate.describe("When the job row was last written."),
+    sentAt: SQLiteDate.nullish().describe("When the send succeeded; null until then."),
+  })
+  .describe("One email job in `pithy_email_jobs` — the auditable, retryable record of a single email.");
+export type EmailJob = z.output<typeof EmailJob>;

package/src/data/emailSuppression.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { SuppressionReason } from "./enums";
+
+/**
+ * One row in `pithy_email_suppressions` — an address that must not be sent to, fed by hard bounces,
+ * complaints, and unsubscribes. The send path checks this list before every send and skips a match,
+ * recording why. `z.output` is the app shape; `z.input` is the SQLite row.
+ */
+export const EmailSuppression = z
+  .object({
+    id: z.number().int().describe("Surrogate primary key, autoincremented by SQLite."),
+    email: z.string().describe("The suppressed address, lowercased. Uniquely indexed — one row per address."),
+    reason: SuppressionReason.describe(
+      "Why the address is suppressed: hard bounce, complaint, unsubscribe, or manual.",
+    ),
+    jobId: z
+      .string()
+      .nullish()
+      .describe(
+        "The job that triggered the suppression (a bounce/complaint/unsubscribe), if any. Job ids are per-environment, so pair it with `environment` for context.",
+      ),
+    environment: z
+      .string()
+      .nullish()
+      .describe(
+        "The environment the triggering job came from (e.g. `prod`, `feature-27`). The suppression itself is global; this records where it originated.",
+      ),
+    detail: z
+      .string()
+      .nullish()
+      .describe("Free-form context — the bounce code or complaint source; null when not applicable."),
+    createdAt: SQLiteDate.describe("When the address was suppressed."),
+    expiresAt: SQLiteDate.nullish().describe("When a temporary suppression lifts; null for a permanent suppression."),
+  })
+  .describe("One suppressed address in `pithy_email_suppressions`.");
+export type EmailSuppression = z.output<typeof EmailSuppression>;

package/src/data/enums.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The closed enums of the email capability. Each is the documented vocabulary for one column, shared
+ * across the row schemas, the send path, and the callback/bounce handlers. Stored as text in SQLite.
+ */
+
+export const TemplateCategory = z
+  .enum(["transactional", "marketing"])
+  .describe(
+    "What a template's message *is*. `transactional` is triggered by a user action (magic link, receipt); `marketing` is promotional, and cannot render at all without an unsubscribe link. The category drives tracking defaults and that hard requirement. Whether a person may *refuse* the message is a separate question, answered by `EmailKind` — a testing-program nudge is transactional in style and elective in consent.",
+  );
+export type TemplateCategory = z.output<typeof TemplateCategory>;
+
+export const EmailKind = z
+  .enum(["transactional", "elective"])
+  .describe(
+    "Whether a recipient may refuse a message. `transactional` answers something the person just did — a sign-in link, an invitation they are waiting on, a security notice — and carries no unsubscribe affordance and no `List-Unsubscribe` header; `elective` is mail somebody chose to receive and carries both. The kind is declared by the template, never passed by a caller, and it decides how the suppression list is consulted: an unsubscribe blocks elective mail only, while a bounce or a complaint blocks everything.",
+  );
+export type EmailKind = z.output<typeof EmailKind>;
+
+export const SendMode = z
+  .enum(["immediate", "scheduled", "timezone"])
+  .describe(
+    "How a job's send time is determined. `immediate` sends now (a Workflow starts at enqueue); `scheduled` sends at a fixed absolute time; `timezone` resolves a recipient's local time-of-day to an absolute time using their IANA zone.",
+  );
+export type SendMode = z.output<typeof SendMode>;
+
+/**
+ * **`canceled` has one `l` here, and `@pithy-sh/payments` spells it the same way for a different reason.**
+ *
+ * The kit writes American English (pithy-sh/pithy#434). This enum is the kit's own vocabulary — nobody
+ * else names these states, no wire format outside this package carries them — so the spelling was ours to
+ * pick, and we picked the one the rest of the prose uses. `PurchaseStatus` in `payments/src/data/status.ts`
+ * arrives at the same string from the other direction: `canceled` is Paddle's wire value, and rewriting a
+ * vendor's own string would be inventing a translation layer over somebody else's API.
+ *
+ * Two capabilities, two arguments, one spelling. That is the point — the kit stopped spelling one concept
+ * both ways, and neither side has to be re-derived by the next reader.
+ *
+ * **This was settled before the first publish, and that window is closed.** Every package was `0.0.0`,
+ * nothing was on npm, and `0001_init.ts` declares `status` as bare `text` with no CHECK, so no row and no
+ * migration ever held the old value. Changing one now would be a breaking change with a real migration
+ * behind it.
+ */
+export const EmailJobStatus = z
+  .enum(["pending", "scheduled", "sending", "sent", "failed", "suppressed", "bounced", "undispatched", "canceled"])
+  .describe(
+    "The lifecycle state of an email job. `pending` (immediate, awaiting dispatch) and `scheduled` (future sendAt) are pre-send; `sending` is in-flight; `sent` succeeded; `failed` exhausted retries; `suppressed` was skipped because the address is on the suppression list; `bounced` was reported undeliverable; `undispatched` means this composition binds no send Workflow, so nothing was started and nothing is coming while that holds — a configuration fact, not a transient one, and the scheduler claims those rows once a host worker exists; `canceled` was withdrawn before sending.",
+  );
+export type EmailJobStatus = z.output<typeof EmailJobStatus>;
+
+export const EmailEventType = z
+  .enum(["sent", "open", "click", "bounce", "complaint", "unsubscribe", "suppressed", "failed"])
+  .describe(
+    "A per-recipient event recorded for history and campaign attribution: `sent` on a successful send, `open` from the tracking pixel, `click` from a tracked link, `bounce`/`complaint` from inbound mail, `unsubscribe` from the opt-out callback, `suppressed` when a send was skipped, `failed` on a terminal send error.",
+  );
+export type EmailEventType = z.output<typeof EmailEventType>;
+
+export const BounceType = z
+  .enum(["hard", "soft", "complaint", "auto_reply"])
+  .describe(
+    "How an inbound delivery-status or complaint message was classified: `hard` (permanent — suppress), `soft` (transient — Cloudflare auto-retries), `complaint` (recipient reported spam — suppress), `auto_reply` (vacation responder — a no-op, never suppressed).",
+  );
+export type BounceType = z.output<typeof BounceType>;
+
+export const SuppressionReason = z
+  .enum(["hard_bounce", "complaint", "unsubscribe", "manual"])
+  .describe(
+    "Why an address is on the suppression list and will not be sent to: `hard_bounce` (permanent delivery failure), `complaint` (spam report), `unsubscribe` (recipient opted out), `manual` (added by an operator).",
+  );
+export type SuppressionReason = z.output<typeof SuppressionReason>;

package/src/data/tables.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import { EmailEvent } from "./emailEvent";
+import { EmailJob } from "./emailJob";
+import { EmailSuppression } from "./emailSuppression";
+
+/**
+ * The email capability spans two databases. Jobs and events are **per-environment** — they live in the
+ * app `DB`, alongside the app's own data, scoped to the environment that sent them. Suppression is
+ * **global** — an address that hard-bounced, complained, or unsubscribed must never be emailed from any
+ * environment — so it lives in a dedicated, durable `EMAIL_SUPPRESSIONS` database (the same shared-DB
+ * pattern `@pithy-sh/secrets` uses), written by the single inbound bounce worker and the unsubscribe
+ * callbacks and read by every environment's send path.
+ */
+
+/** The per-environment email tables, on the app `DB`. */
+export const emailTables = {
+  pithyEmailJobs: EmailJob,
+  pithyEmailEvents: EmailEvent,
+};
+export type EmailTables = typeof emailTables;
+
+/** The global suppression table, on the dedicated durable `EMAIL_SUPPRESSIONS` database. */
+export const emailSuppressionTables = {
+  pithyEmailSuppressions: EmailSuppression,
+};
+export type EmailSuppressionTables = typeof emailSuppressionTables;
+
+/** The typed Kysely database over the per-environment email tables (jobs + events). */
+export type EmailDatabase = Kysely<DatabaseSchema<EmailTables>>;
+
+/** The typed Kysely database over the global suppression table. */
+export type EmailSuppressionDatabase = Kysely<DatabaseSchema<EmailSuppressionTables>>;
+
+/** Build the per-environment email database from the app `DB` binding (CamelCasePlugin installed). */
+export function emailDatabase(d1: D1Database): EmailDatabase {
+  return createDatabase(d1, emailTables);
+}
+
+/** Build the global suppression database from the `EMAIL_SUPPRESSIONS` binding. */
+export function emailSuppressionDatabase(d1: D1Database): EmailSuppressionDatabase {
+  return createDatabase(d1, emailSuppressionTables);
+}

package/src/error/errors.ts

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/email` throw sugar. The `email/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors: capabilities add their codes to the one union); these subclasses are the
+ * package-local vehicles that set one of those members — the same pattern as `@pithy-sh/secrets`.
+ * Runtime code in this package throws one of these, never a plain `new Error`.
+ */
+
+/** Variable parts each subclass accepts; `code`/`status` are fixed by the subclass. */
+interface EmailErrorArgs {
+  /** Override the public, safe-to-expose message. */
+  message?: string;
+  /** A remediation hint (CLI action line). */
+  action?: string;
+  /** Internal context for logs + audit. Never serialized to clients. */
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+/** The requested template id is not registered. */
+export class EmailTemplateNotFoundError extends PithyError {
+  constructor(args: EmailErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "email/template_not_found",
+        status: 404,
+        message: args.message ?? "Email template not found.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A template's input variables failed validation against its payload schema. */
+export class EmailInvalidPayloadError extends PithyError {
+  constructor(args: EmailErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "email/invalid_payload",
+        status: 400,
+        message: args.message ?? "Email template payload failed validation.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A callback token (click/open/unsubscribe) is malformed, expired, forged, or signed by an unknown key. */
+export class EmailInvalidTokenError extends PithyError {
+  constructor(args: EmailErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "email/invalid_token",
+        status: 400,
+        message: args.message ?? "This link is invalid or has expired.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The recipient address is on the suppression list and cannot be sent to. */
+export class EmailSuppressedError extends PithyError {
+  constructor(args: EmailErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "email/suppressed",
+        status: 409,
+        message: args.message ?? "This address is suppressed and cannot be emailed.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The Email Service rejected the send for a rate or daily-quota limit; the send is retryable. */
+export class EmailRateLimitedError extends PithyError {
+  constructor(args: EmailErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "email/rate_limited",
+        status: 429,
+        message: args.message ?? "The email rate limit was exceeded.",
+        action: args.action ?? "Retry with backoff.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** A send through the Email Service binding failed for a non-retryable reason. */
+export class EmailSendFailedError extends PithyError {
+  constructor(args: EmailErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "email/send_failed",
+        status: 502,
+        message: args.message ?? "The email could not be sent.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/callbacks.ts

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import type { Hono } from "hono";
+import { resolveSigningKeys } from "../crypto/signingKey";
+import { type CallbackToken, type TokenKind, verifyToken } from "../crypto/token";
+import {
+  type EmailDatabase,
+  type EmailSuppressionDatabase,
+  emailDatabase,
+  emailSuppressionDatabase,
+} from "../data/tables";
+import { EmailInvalidTokenError } from "../error/errors";
+import { recordEvent } from "../send/events";
+import { suppress } from "../send/suppression";
+import { CALLBACK_BASE } from "../templates/engine";
+import { CallbackTokenParam, UnsubscribeQuery } from "./schemas";
+
+/**
+ * The callback routes — click, open, and unsubscribe. Every link in a tracked email points here with
+ * an HMAC-signed token (see `crypto/token`). The routes are **public + signed-token**: they take no
+ * session, and the token's signature is the only gate. A forged, altered, or expired token is rejected
+ * (`email/invalid_token` → 400) before anything is recorded. The click route only ever 302-redirects to
+ * an `http(s)` destination carried inside the signed token, so it cannot be turned into an open redirect.
+ *
+ * | Method | Path                          | Strategy      | Validates |
+ * |--------|-------------------------------|---------------|-----------|
+ * | GET    | /_pithy/email/c/:token        | signed token  | param `CallbackTokenParam` |
+ * | GET    | /_pithy/email/o/:token        | signed token  | param `CallbackTokenParam` |
+ * | GET    | /_pithy/email/u/:token        | signed token  | param `CallbackTokenParam`, query `UnsubscribeQuery` |
+ * | POST   | /_pithy/email/u/:token        | signed token  | param `CallbackTokenParam`, query `UnsubscribeQuery` |
+ *
+ * The unsubscribe route answers POST as well as GET because elective mail carries
+ * `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) — the mail client posts to the URL
+ * itself, with no human ever loading the page, and Gmail's and Yahoo's bulk-sender rules require that to
+ * work. Same handler: the underlying write is an upsert, so the two methods cannot disagree and a
+ * client that retries costs nothing.
+ *
+ * The validators bound shape and size only — the signature check stays in the handler, so a well-formed
+ * token that is forged or expired is still `email/invalid_token` (400), not `validation/invalid_input`.
+ * No route reads a body, the one-click POST included: RFC 8058 fixes its body to a constant, so parsing
+ * it could only ever restate what the method and the signed token already say.
+ *
+ * The per-request handlers take the signing-key version set directly so they are unit-testable without
+ * standing up the secrets store; `registerCallbacks` is the thin shell that resolves the keys from the
+ * worker env (via `@pithy-sh/secrets`) and the database from the `DB` binding.
+ */
+
+/** The env the callbacks read: the app + shared suppression databases plus the secrets bindings for the signing key. */
+type CallbackEnv = SecretsStoreEnv & { DB: D1Database; EMAIL_SUPPRESSIONS: D1Database };
+
+/** The signing-key version set a handler verifies against. */
+export interface SigningKeys {
+  versions: Record<string, string>;
+}
+
+/** A 1×1 transparent PNG — the open-tracking pixel body. */
+const PIXEL = Uint8Array.from(
+  atob("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="),
+  (c) => c.charCodeAt(0),
+);
+
+/** Verify a token and assert its kind, or throw `email/invalid_token`. */
+async function verify(keys: SigningKeys, token: string, expected: TokenKind, now: Date): Promise<CallbackToken> {
+  const claims = await verifyToken(token, keys, now);
+  if (claims.kind !== expected) {
+    throw new EmailInvalidTokenError({ detail: `token kind '${claims.kind}' does not match callback '${expected}'` });
+  }
+  return claims;
+}
+
+/** Handle a click: record it, then 302-redirect to the signed http(s) destination. */
+export async function handleClick(db: EmailDatabase, keys: SigningKeys, token: string, now: Date): Promise<Response> {
+  const claims = await verify(keys, token, "click", now);
+  const destination = claims.destination ?? "";
+  if (!/^https?:\/\//i.test(destination)) {
+    throw new EmailInvalidTokenError({ detail: "click token has no http(s) destination" });
+  }
+  await recordEvent(
+    db,
+    {
+      jobId: claims.jobId,
+      recipient: normalizeAddress(claims.recipient),
+      type: "click",
+      linkLabel: claims.linkLabel ?? null,
+      linkUrl: destination,
+      campaignId: claims.campaignId ?? null,
+    },
+    now,
+  );
+  return new Response(null, { status: 302, headers: { location: destination } });
+}
+
+/** Handle an open: record it, return the 1×1 pixel. */
+export async function handleOpen(db: EmailDatabase, keys: SigningKeys, token: string, now: Date): Promise<Response> {
+  const claims = await verify(keys, token.replace(/\.png$/i, ""), "open", now);
+  await recordEvent(
+    db,
+    {
+      jobId: claims.jobId,
+      recipient: normalizeAddress(claims.recipient),
+      type: "open",
+      campaignId: claims.campaignId ?? null,
+    },
+    now,
+  );
+  return new Response(PIXEL, {
+    status: 200,
+    headers: { "content-type": "image/png", "cache-control": "no-store, max-age=0" },
+  });
+}
+
+/**
+ * Handle an unsubscribe: suppress the address (shared DB), record the opt-out event (app DB), confirm.
+ * An optional `reason` — supplied by the app's own unsubscribe/preferences flow via the `?reason=` query
+ * param — is stored on the suppression `detail` and the event, so a project can capture *why* someone
+ * opted out using its own logic. It is length-bounded so the link can't be used to stuff the column.
+ */
+export async function handleUnsubscribe(
+  db: EmailDatabase,
+  suppressionDb: EmailSuppressionDatabase,
+  keys: SigningKeys,
+  token: string,
+  now: Date,
+  reason?: string,
+  environment?: string,
+): Promise<Response> {
+  const claims = await verify(keys, token, "unsubscribe", now);
+  const recipient = normalizeAddress(claims.recipient);
+  const detail = reason ? reason.slice(0, 200) : "unsubscribe link";
+  await suppress(
+    suppressionDb,
+    { email: recipient, reason: "unsubscribe", jobId: claims.jobId, environment, detail },
+    now,
+  );
+  await recordEvent(
+    db,
+    { jobId: claims.jobId, recipient, type: "unsubscribe", campaignId: claims.campaignId ?? null, detail },
+    now,
+  );
+  // The copy states the scope, because the scope is not what "unsubscribe" implies to most people and
+  // getting it wrong in either direction is alarming: somebody who believes this killed their sign-in
+  // link, or somebody who believes it stopped everything and then receives a security notice.
+  const body =
+    "<p>You've been unsubscribed. Messages you ask for — a sign-in link, a security notice — still arrive. Nothing else will.</p>";
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}
+
+/** Mount the click/open/unsubscribe callback routes under `${CALLBACK_BASE}` on the app's Hono router. */
+export function registerCallbacks(app: Hono<PithyHonoEnv>): void {
+  const setup = async (
+    env: CallbackEnv,
+  ): Promise<{ db: EmailDatabase; suppressionDb: EmailSuppressionDatabase; keys: SigningKeys }> => {
+    const keys = await resolveSigningKeys(env);
+    return {
+      db: emailDatabase(env.DB),
+      suppressionDb: emailSuppressionDatabase(env.EMAIL_SUPPRESSIONS),
+      keys: { versions: keys.versions },
+    };
+  };
+
+  app.get(`${CALLBACK_BASE}/c/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
+    const { db, keys } = await setup(c.env as unknown as CallbackEnv);
+    return handleClick(db, keys, c.req.valid("param").token, new Date());
+  });
+
+  app.get(`${CALLBACK_BASE}/o/:token`, zValidator("param", CallbackTokenParam, validationHook), async (c) => {
+    const { db, keys } = await setup(c.env as unknown as CallbackEnv);
+    return handleOpen(db, keys, c.req.valid("param").token, new Date());
+  });
+
+  app.on(
+    ["GET", "POST"],
+    `${CALLBACK_BASE}/u/:token`,
+    zValidator("param", CallbackTokenParam, validationHook),
+    zValidator("query", UnsubscribeQuery, validationHook),
+    async (c) => {
+      const env = c.env as unknown as CallbackEnv;
+      const { db, suppressionDb, keys } = await setup(env);
+      return handleUnsubscribe(
+        db,
+        suppressionDb,
+        keys,
+        c.req.valid("param").token,
+        new Date(),
+        c.req.valid("query").reason,
+        env.ENVIRONMENT,
+      );
+    },
+  );
+}