@pithy-sh/email 0.1.0

package/src/send/enqueue.ts

@@ -0,0 +1,391 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { isLocale } from "@pithy-sh/core/src/i18n/locale";
+import type { EmailJob } from "../data/emailJob";
+import { EmailJob as EmailJobSchema } from "../data/emailJob";
+import type { EmailJobStatus, SendMode, SuppressionReason } from "../data/enums";
+import type { EmailDatabase, EmailSuppressionDatabase } from "../data/tables";
+import { EmailInvalidPayloadError } from "../error/errors";
+import { getTemplate, renderSubject, templateKind } from "../templates/engine";
+import { type EmailMessageLayers, emailTranslator, kitEmailLayers } from "../templates/messages";
+import type { EmailTheme } from "../templates/theme";
+import { mintBatchId } from "./batchIdentity";
+import { recordEvent } from "./events";
+import { resolveTimezoneSendAt } from "./sendAt";
+import { blockingSuppression } from "./suppression";
+
+/**
+ * Enqueue an email. A request handler only ever does this — it never sends inline. Every email becomes
+ * a `pithy_email_jobs` row; an `immediate` job also kicks the send Workflow now (lowest latency), while
+ * `scheduled` and `timezone` jobs are left for the every-minute scheduler to pick up. The payload is
+ * validated against the template schema here, so a bad call fails at enqueue, not mid-send.
+ *
+ * **Suppression is consulted here too, and no caller asks for it** (pithy-sh/pithy#355). A blocked
+ * recipient never becomes a queued send: the row is born `suppressed`, no Workflow is started, and the
+ * reason comes back on the result. The point is not a second gate — `runSend` is and stays the
+ * authority, because whether an address is blocked is a question about the instant of sending and a
+ * scheduled job is enqueued days before that. The point is that the caller **learns**, at the moment it
+ * asked, without holding the suppression database itself. A three-person account whose addresses have
+ * all hard-bounced is otherwise three ordinary skips in a send log nobody reads, rather than one notice
+ * that reached nobody, said at the moment it went out.
+ *
+ * **The kind comes from the template, never from a caller** — {@link templateKind}, the same accessor
+ * `runSend` uses. That is what keeps an unsubscribe from a newsletter from withholding an invitation:
+ * the four suppression reasons stopped being interchangeable, and a check that restated
+ * `"transactional"` at the call site would be making a claim about somebody else's template.
+ */
+
+/**
+ * The Workflow binding used to start a send (Cloudflare `Workflow.create`). At enqueue it sends a batch
+ * of one; the scheduler's fan-out starts one instance per batch through the same binding.
+ *
+ * `id` names the instance being created, and **every dispatcher passes one** (pithy-sh/pithy#342): the
+ * scheduler passes its batch's, an enqueue passes the one it just stamped on the row, and a retry passes
+ * the one it minted to replace the failed batch's. It is optional here only because the platform allows
+ * omitting it, and omitting it is what made an immediate send unattributable to any instance — so the
+ * row could not say a Workflow was coming and the safety net sent a second one. See
+ * `send/batchIdentity.ts`.
+ */
+export interface SendWorkflowBinding {
+  create(options: { id?: string; params: { jobIds: string[] } }): Promise<unknown>;
+}
+
+/** What the caller provides to enqueue an email. */
+export interface EnqueueInput {
+  /** The recipient address. */
+  to: string;
+  /** The template id (e.g. `magicLink`). */
+  template: string;
+  /** The template input variables; validated against the template's payload schema. */
+  payload: unknown;
+  /** Send mode; defaults to `immediate`. */
+  mode?: SendMode;
+  /** For `scheduled` mode: the absolute time to send. */
+  sendAt?: Date;
+  /** For `timezone` mode: the recipient-local time-of-day, `HH:MM`. */
+  localTime?: string;
+  /** For `timezone` mode: the recipient's IANA timezone. */
+  timezone?: string;
+  /** The marketing campaign id, for attribution. */
+  campaignId?: string;
+  /**
+   * The language to write this message in, as a BCP-47 tag. Omit where the recipient has not chosen one.
+   *
+   * **The recipient's, never the caller's.** A magic link is answered by the person who asked for it,
+   * and the request that triggers it is theirs — but a nudge, an invitation and an operational notice
+   * are all enqueued by somebody else's request, or by a cron with no request at all. So the tag comes
+   * from what is known about the *recipient* (`pithy_auth_users.locale` for a signed-up reader, the
+   * negotiated request locale for somebody signing in for the first time), and it is stored on the row
+   * so the send Workflow renders the body in the language the subject was already written in.
+   *
+   * Omitted renders the kit's English, which is the seam's behavior everywhere: a project that never
+   * composed an i18n capability sends exactly what it sent before any of this landed.
+   */
+  locale?: string;
+  /**
+   * What this message is *about*, when the template id does not say it on its own.
+   *
+   * The discriminator for a template that carries more than one kind of message (pithy-sh/pithy#382).
+   * `sentSince` matches on it, so a caller deciding whether to send — or whether to send a *correction* —
+   * can tell two messages apart that share a template and a recipient. Opaque: nothing here parses it,
+   * renders it, or puts it on a header or a link.
+   *
+   * **Not `campaignId`.** That one is marketing attribution and it leaves this row — onto every event,
+   * into `campaignStats`, and signed into the tracking token that travels in a delivered email's URLs.
+   * See the column's own note on `EmailJob`.
+   *
+   * Omit it where the template id already answers "what is this", which is most templates.
+   */
+  correlation?: string;
+  /** Override click-link rewriting (defaults on for marketing, off for transactional). */
+  clickTracking?: boolean;
+  /** Override open-pixel injection (defaults on for marketing, off for transactional). */
+  openTracking?: boolean;
+  /**
+   * The address a recipient's answer should go to, when it is not `fromAddress`.
+   *
+   * `@pithy-sh/support` is what this is for: a reply is sent as the adopter's onboarded sending
+   * identity (Cloudflare validates the `From` domain against exactly what was onboarded) while the
+   * conversation has to come back to the support inbox, which is usually a different subdomain.
+   */
+  replyTo?: string;
+  /**
+   * The `Message-ID` this job answers, angle brackets included — the `In-Reply-To` header.
+   *
+   * Set together with {@link references}. Threading on ids is what keeps a customer's client showing
+   * one conversation instead of one message per answer, and only the Worker holds the chain, which
+   * is why a reply is enqueued here rather than composed by whatever surface a human typed it into.
+   */
+  inReplyTo?: string;
+  /** The `References` chain, angle-bracketed and space-separated. Built by the caller from the parent. */
+  references?: string;
+}
+
+/** Dependencies enqueue needs: the database, the from identity, optional send-Workflow binding, time, ids. */
+export interface EnqueueDeps {
+  db: EmailDatabase;
+  fromAddress: string;
+  fromName: string;
+  theme: EmailTheme;
+  /**
+   * Where the words for a locale come from — the composed project's catalogs.
+   *
+   * Absent walks this package's own English, which is what keeps the i18n capability optional. The
+   * email capability fills it from a composed `i18n` at assembly; nothing here imports that package.
+   */
+  layersFor?: EmailMessageLayers;
+  /** The send Workflow binding. When present, an immediate job is dispatched now; absent, the scheduler takes it. */
+  sender?: SendWorkflowBinding;
+  /**
+   * The global suppression list. When present, a blocked recipient is recorded here and never queued.
+   *
+   * Optional for the same reason {@link EnqueueDeps.sender} is, and it is worth being exact about which
+   * reason: absence does not mean "send to blocked addresses". The capability declares
+   * `EMAIL_SUPPRESSIONS` a required binding, so a composed app worker always has one; and where a caller
+   * genuinely has none, `runSend` still refuses the recipient before anything leaves. Making it fatal
+   * here would mean refusing to *queue* a message because a list that will be consulted again before it
+   * goes could not be consulted yet, which is strictly worse than queueing it.
+   */
+  suppressionDb?: EmailSuppressionDatabase;
+  now: Date;
+  /** Generate a job id (a UUID in production). */
+  newId: () => string;
+  /**
+   * Mint the id of the batch this enqueue dispatches — **the send Workflow instance's id**
+   * (pithy-sh/pithy#342). Defaults to {@link mintBatchId}; injected only so a test can name it.
+   */
+  newBatchId?: () => string;
+}
+
+/** The result of enqueuing: the new job id and its initial status. */
+export interface EnqueueResult {
+  jobId: string;
+  /**
+   * What the row was born as — and, for the caller, whether anything is coming for it.
+   *
+   * `pending` and `scheduled` both mean a send is on its way. `suppressed` means the address is
+   * blocked. **`undispatched` means this composition binds no send Workflow**, so nothing was started
+   * and nothing is coming while it stays that way (pithy-sh/pithy#410): a caller that renders "check
+   * your inbox" off it is reporting a delivery that cannot happen. It is the one status here that
+   * describes the *deployment* rather than the message — and the scheduler drains those rows once a
+   * host exists, so it is not the end of the job.
+   */
+  status: EmailJobStatus;
+  /**
+   * Why nothing was queued, when the recipient is on the suppression list.
+   *
+   * The same field {@link import("./runSend").SendOutcome} carries and for the same reason: a caller
+   * that only saw a status other than `failed` would report a delivery that never happened. "Suppressed"
+   * alone is not enough either — whether the mailbox bounced, complained, or opted out is what an
+   * operator's next move depends on.
+   */
+  suppressionReason?: SuppressionReason;
+  /**
+   * The **enqueue-time** render — the sentence this call wrote to `pithy_email_jobs.subject`, in the
+   * recipient's language, and the value the row is born with (pithy-sh/pithy#443).
+   *
+   * **For the caller that has to say what it queued.** Enqueuing is what a surface does; auditing it is
+   * what a surface with an administrative trail also does. Without this, that caller had to render the
+   * same key a second time — restating the theme it configured and the layer stack it composed, then
+   * holding a test pinning its own copy against the kit's catalog to notice when the kit's wording
+   * moved. An audit row written at enqueue now reads the same string the job row was written with,
+   * rather than a second rendering free to disagree with it.
+   *
+   * **Locale is what makes it more than a convenience.** A caller that mirrored the English sentence by
+   * hand agreed with the row by coincidence, for as long as there was one language. Pass a `locale` and
+   * the template renders the recipient's catalog while the mirror keeps restating English, and the trail
+   * then claims a subject nobody was ever sent.
+   *
+   * **{@link import("./runSend").runSend} remains the authority on what was *delivered***, because it
+   * renders again — in the send Worker, at the moment the message leaves — and rewrites this column
+   * from that render. Three things part the two renders — the three `runSend` names at the line where
+   * it rewrites: a template corrected, a theme renamed, or a catalog sentence retranslated. A subject
+   * can interpolate the theme (`welcome`'s takes `theme.appName`), so a rename parts them with no
+   * catalog movement at all.
+   *
+   * **And the gap between the two is not only the wait in the queue.** Waiting sets one bound on it,
+   * seconds for an immediate send and days for a `scheduled` one. The other is that the send Workflow
+   * is its own deploy: it carries the kit's email copy in its own bundle, and the theme and any
+   * override sentences in vars stamped at provision (`docs/I18N.md`). So a send Worker whose copy has
+   * drifted from the Worker that enqueued is not a window a fast send outruns — it stands until the two
+   * are back in step, and an immediate send lands inside it like any other. This is a record of what
+   * was queued, never a promise about the delivered sentence — a trail that must reflect delivery reads
+   * the row back after the send.
+   *
+   * Present on every result, including a `suppressed` one: the withheld row carries a rendered subject
+   * like any other, no send will ever rewrite it, and a message that reached nobody is the one an
+   * operator most needs on the record.
+   *
+   * **Deliberately not the body.** A body is large, it is the thing this capability is careful never to
+   * log, and no caller has a reason to hold one — `runSend` renders it inside the Workflow, at the
+   * moment it leaves, and that is the only place it exists.
+   */
+  subject: string;
+}
+
+/** Resolve the absolute send time and initial status from the requested mode. */
+function resolveSchedule(input: EnqueueInput, now: Date): { mode: SendMode; sendAt: Date; status: EmailJobStatus } {
+  const mode = input.mode ?? "immediate";
+  if (mode === "immediate") return { mode, sendAt: now, status: "pending" };
+  if (mode === "scheduled") {
+    if (!input.sendAt) throw new EmailInvalidPayloadError({ detail: "scheduled mode requires an absolute sendAt" });
+    return { mode, sendAt: input.sendAt, status: "scheduled" };
+  }
+  if (!input.localTime || !input.timezone) {
+    throw new EmailInvalidPayloadError({ detail: "timezone mode requires localTime and timezone" });
+  }
+  return { mode, sendAt: resolveTimezoneSendAt(input.localTime, input.timezone, now), status: "scheduled" };
+}
+
+/** Enqueue an email job, dispatching the send Workflow immediately when the mode is `immediate`. */
+export async function enqueueEmail(deps: EnqueueDeps, input: EnqueueInput): Promise<EnqueueResult> {
+  const template = getTemplate(input.template);
+  // Validates the payload against the template schema and computes the stored subject — in the
+  // recipient's language, which is also what the row records so the body can be rendered in it later.
+  const translator = emailTranslator(input.locale, deps.layersFor ?? kitEmailLayers);
+  const subject = renderSubject(input.template, input.payload, deps.theme, translator);
+  const { mode, sendAt, status: scheduled } = resolveSchedule(input, deps.now);
+
+  /**
+   * Whether the suppression list withholds *this* message from *this* address.
+   *
+   * `templateKind(input.template)` and never a literal — `runSend` reads the same accessor, and the two
+   * agreeing is what makes a hard bounce withhold an invitation while an unsubscribe does not. A caller
+   * cannot influence this and is not asked to: it is the template's own declaration.
+   */
+  const blocked: SuppressionReason | null = deps.suppressionDb
+    ? await blockingSuppression(deps.suppressionDb, input.to, deps.now, templateKind(input.template))
+    : null;
+  // The match key, on the same normalization the suppression list is written and read under. The row
+  // keeps the address as the caller typed it in `toAddress` — an operator diagnosing a send needs the
+  // string that was actually addressed — and carries this beside it as `recipientKey`, which is what
+  // the events table is keyed on and what `sentSince` matches. One value, computed once, so a job and
+  // its events cannot disagree about who the person is.
+  const recipient = normalizeAddress(input.to);
+
+  // Whether this call starts a send Workflow at all: only an immediate job does, only where a binding
+  // exists to start one on, and never for a recipient the list withholds this message from. Everything
+  // else is left for the scheduler to claim.
+  const sender = !blocked && mode === "immediate" ? deps.sender : undefined;
+  /**
+   * An immediate job with nothing to dispatch it on (pithy-sh/pithy#410).
+   *
+   * A missing binding is a **configuration fact known at compose time**, not a transient failure, and
+   * the two used to be recorded identically: both left the row `pending` and told the caller "on its
+   * way". That reads as deferral because of the scheduler's safety net — but the net is the
+   * every-minute cron on the host worker, and a composition with no send Workflow binding has no host
+   * worker either. So there is nothing to defer to *yet*, and `pending` was a promise the deployment
+   * could not keep. A magic link enqueued under `pithy dev` sat in that state forever while the sign-in
+   * screen said "check your inbox".
+   *
+   * It is a truthful status, never a grave. The day a host is deployed, its first tick claims these
+   * rows exactly as it claims a stranded `pending` one — a tick running at all is the host existing —
+   * so mail enqueued before `pithy email provision` is delayed and not lost.
+   *
+   * A `scheduled` or `timezone` job is deliberately not this: the scheduler claims it by `sendAt` and
+   * never needed a binding at enqueue. Nor is a suppressed recipient, which has its own status and its
+   * own event. This is only the case where the caller asked for a send now and nothing exists to make
+   * one.
+   */
+  const undispatchable = !blocked && mode === "immediate" && !deps.sender;
+  const status: EmailJobStatus = blocked ? "suppressed" : undispatchable ? "undispatched" : scheduled;
+  /**
+   * The batch this enqueue is about to start — named here, before the row exists, because the row has to
+   * carry it (pithy-sh/pithy#342).
+   *
+   * Without it the row is born naming nobody, and a row naming nobody is stranded by definition: the
+   * scheduler's safety net claims any `pending` job older than `graceMs` and starts a *second* send
+   * Workflow for it. That is not a hypothetical race with a slow enqueue — it is the ordinary shape of a
+   * transient send failure. `runSend` throws on a retryable error so the Workflow step backs off, and a
+   * backoff writes nothing at all, so the very first retry leaves the row looking exactly like a dispatch
+   * that died. `runSend` short-circuits only a job already `sent`, so both instances would render and
+   * both would call the Email Service. One person, two emails.
+   *
+   * Null for a `scheduled` or `timezone` job, and for an immediate one with no binding, because in those
+   * cases nothing is coming for the row and saying otherwise would hold it against a batch that does not
+   * exist.
+   */
+  const batchId = sender ? (deps.newBatchId ?? mintBatchId)() : null;
+
+  const marketing = template.category === "marketing";
+  const job: EmailJob = {
+    id: deps.newId(),
+    toAddress: input.to,
+    recipientKey: recipient,
+    fromAddress: deps.fromAddress,
+    fromName: deps.fromName,
+    subject,
+    template: input.template,
+    category: template.category,
+    payload: input.payload as Record<string, unknown>,
+    payloadRedactedAt: null,
+    status,
+    mode,
+    attempts: 0,
+    batchId,
+    sendAt,
+    timezone: input.timezone ?? null,
+    localTime: input.localTime ?? null,
+    campaignId: input.campaignId ?? null,
+    // Normalized, never taken on trust. `EmailJob.encode` below enforces `Locale` — the BCP-47 shape
+    // and an `Intl` refinement — so a tag that fails it throws a raw `ZodError` at the insert, and the
+    // caller sees `core/internal` with nothing an operator can act on. `en_US` is not a hypothetical
+    // shape either: it is exactly what Android, iOS and Java `Locale.toString()` produce, so a mobile
+    // client reporting its own locale sends one.
+    //
+    // Callers that already validate lose nothing (every kit feeder is a `Locale` column or the
+    // negotiated `LocaleContext`), and a caller that does not gets the kit's English rather than a 500.
+    // The same shape as `renderLocale` on the send side, and for the same reason.
+    locale: isLocale(input.locale ?? "") ? (input.locale ?? null) : null,
+    correlation: input.correlation ?? null,
+    openTracking: input.openTracking ?? marketing,
+    clickTracking: input.clickTracking ?? marketing,
+    messageId: null,
+    // The same sentence `runSend` writes when it skips one, so the send log reads the same whichever
+    // pass caught it — and, for the undispatchable row, the one sentence that says why it stopped
+    // here. The status is the state; this column is what an operator reads next to it.
+    error: blocked
+      ? `recipient suppressed: ${blocked}`
+      : undispatchable
+        ? "no EMAIL_SENDER binding: this composition can start no send Workflow"
+        : null,
+    bounceCode: null,
+    bounceType: null,
+    replyTo: input.replyTo ?? null,
+    inReplyTo: input.inReplyTo ?? null,
+    references: input.references ?? null,
+    createdAt: deps.now,
+    updatedAt: deps.now,
+    sentAt: null,
+  };
+
+  await deps.db.insertInto("pithyEmailJobs").values(EmailJobSchema.encode(job)).execute();
+
+  // A withheld message is on the record as an event, not merely as a status — the send log's history is
+  // what an operator reads to find out that an advisory reached nobody, and a row with no event in it
+  // looks exactly like a job still waiting its turn.
+  if (blocked) {
+    await recordEvent(deps.db, { jobId: job.id, recipient, type: "suppressed", detail: blocked }, deps.now);
+    return { jobId: job.id, status, subject, suppressionReason: blocked };
+  }
+
+  // Immediate sends start the Workflow now for lowest latency, under the id the row already carries —
+  // the row is written first so the instance can never be alive before the row can name it.
+  //
+  // If the dispatch fails, the row stays `pending` naming an instance the runtime has never heard of.
+  // `batchIsAlive` turns that into "not alive", so the scheduler re-drives it on the next tick exactly
+  // as it did before batch ids existed — a failed dispatch still never loses an email. And if the
+  // failure was only the *answer* going missing, the instance is there and alive, the row names it, and
+  // the tick holds off: the case that used to be a double-send is now the case the id was minted for.
+  if (sender && batchId) {
+    try {
+      await sender.create({ id: batchId, params: { jobIds: [job.id] } });
+    } catch {
+      // Swallowed deliberately: the scheduler's safety net owns recovery.
+    }
+  }
+
+  return { jobId: job.id, status, subject };
+}

package/src/send/errorMapping.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { EmailRateLimitedError, EmailSendFailedError, EmailSuppressedError } from "../error/errors";
+
+/**
+ * Map a Cloudflare Email Service binding error (thrown with an `E_*` `.code`) to a Pithy error and a
+ * retry decision. The codes are documented at
+ * https://developers.cloudflare.com/email-service/api/send-emails/rest-api/ and in the binding's error
+ * table. Retryable codes (rate/quota/transient delivery) are surfaced so the send Workflow re-drives
+ * them with backoff; validation/sender/content codes are terminal — retrying cannot help.
+ */
+
+/** How a given send error is handled: which Pithy error to raise, and whether the send Workflow retries. */
+export interface ClassifiedSendError {
+  /** The `E_*` code reported by the binding, or `E_UNKNOWN` when none was present. */
+  code: string;
+  /** Whether the send should be retried with backoff. */
+  retryable: boolean;
+  /** Whether the failure means the recipient is suppressed (so the address should be locally suppressed). */
+  suppressed: boolean;
+  /** The Pithy error carrying the public-safe message and the code/detail for logs. */
+  error: PithyError;
+}
+
+/** Codes the Email Service retries past — rate, daily quota, and transient delivery/server faults. */
+const RETRYABLE = new Set([
+  "E_RATE_LIMIT_EXCEEDED",
+  "E_DAILY_LIMIT_EXCEEDED",
+  "E_DELIVERY_FAILED",
+  "E_INTERNAL_SERVER_ERROR",
+]);
+
+/** Rate/quota codes map to the dedicated 429 error so the cause reads clearly in logs. */
+const RATE_LIMITED = new Set(["E_RATE_LIMIT_EXCEEDED", "E_DAILY_LIMIT_EXCEEDED"]);
+
+/** Read a thrown value's `.code`/`.message` without assuming its shape. */
+function readError(err: unknown): { code: string; message: string } {
+  if (err && typeof err === "object") {
+    const code = "code" in err && typeof err.code === "string" ? err.code : "E_UNKNOWN";
+    const message = "message" in err && typeof err.message === "string" ? err.message : "";
+    return { code, message };
+  }
+  return { code: "E_UNKNOWN", message: typeof err === "string" ? err : "" };
+}
+
+/**
+ * Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
+ * suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
+ * (validation, sender, content, headers) is terminal. An unknown code is treated as a transient
+ * failure so a momentary fault gets one bounded retry rather than failing the job outright.
+ */
+export function classifySendError(err: unknown): ClassifiedSendError {
+  const { code, message } = readError(err);
+  const detail = `email send failed: ${code}${message ? ` — ${message}` : ""}`;
+
+  if (code === "E_RECIPIENT_SUPPRESSED") {
+    return {
+      code,
+      retryable: false,
+      suppressed: true,
+      error: new EmailSuppressedError({ detail }, { cause: err }),
+    };
+  }
+
+  if (RATE_LIMITED.has(code)) {
+    return { code, retryable: true, suppressed: false, error: new EmailRateLimitedError({ detail }, { cause: err }) };
+  }
+
+  const retryable = RETRYABLE.has(code) || code === "E_UNKNOWN";
+  return { code, retryable, suppressed: false, error: new EmailSendFailedError({ detail }, { cause: err }) };
+}

package/src/send/events.ts

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import type { EmailEventType } from "../data/enums";
+import type { EmailDatabase } from "../data/tables";
+
+/** A per-recipient event to append to `pithy_email_events`. */
+export interface EventInput {
+  jobId: string;
+  recipient: string;
+  type: EmailEventType;
+  linkLabel?: string | null;
+  linkUrl?: string | null;
+  campaignId?: string | null;
+  detail?: string | null;
+}
+
+/** Append one event row. The history/attribution log written by the send path, callbacks, and bounce handler. */
+export async function recordEvent(db: EmailDatabase, event: EventInput, now: Date): Promise<void> {
+  await db
+    .insertInto("pithyEmailEvents")
+    .values({
+      jobId: event.jobId,
+      recipient: event.recipient,
+      type: event.type,
+      linkLabel: event.linkLabel ?? null,
+      linkUrl: event.linkUrl ?? null,
+      campaignId: event.campaignId ?? null,
+      detail: event.detail ?? null,
+      createdAt: SQLiteDate.encode(now),
+    })
+    .execute();
+}

package/src/send/fromComposition.ts

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { composedCapability } from "@pithy-sh/core/src/capability/composition";
+import { type EmailCapability, type EmailEnqueueEnv, isEmailCapability } from "../capability";
+import type { EnqueueInput, EnqueueResult } from "./enqueue";
+
+/**
+ * Sending mail from a Workflow (pithy-sh/pithy#356).
+ *
+ * A route reaches `enqueue` through the `compose` hook, and should keep doing that — it is typed, it is
+ * explicit, and it does not depend on module load order. **A Workflow class has no such route.** The
+ * runtime constructs it with the worker `env` and nothing else, `enqueue` is a closure rather than a
+ * binding, and Workflow params are serialized so a closure cannot travel in one either. Until this
+ * existed, a durable job could not send mail without rebuilding the sending identity from `env` — the
+ * same from-address in a second place, free to drift from `pithy.config.ts` — which is exactly what this
+ * capability's own doc asks consumers not to do.
+ *
+ * So: one function, taking the env a Workflow already has, restating nothing.
+ *
+ * ```ts
+ * export class RotationWorkflow extends WorkflowEntrypoint<Env, RotationParams> {
+ *   override async run(event: WorkflowEvent<RotationParams>, step: WorkflowStep) {
+ *     await step.do("notify", async () => {
+ *       await enqueueFromEnv(this.env, { to, template: "operationalNotice", payload });
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * The Workflow class must be exported from the same worker entrypoint that calls `createBackend` —
+ * which Cloudflare requires anyway — so the composition has already happened in this isolate by the time
+ * a step body runs. Where it has not, this raises a wiring fault naming what to compose rather than
+ * sending mail as some invented identity.
+ */
+
+/**
+ * The composed email capability, or a raised wiring fault.
+ *
+ * Narrowed by `isEmailCapability`, the capability's own guard, so a capability composed under the name
+ * `email` but carrying no seams is caught here rather than at a call site whose `enqueue` is undefined.
+ */
+export function composedEmail(): EmailCapability {
+  return composedCapability<EmailCapability>("email", isEmailCapability);
+}
+
+/**
+ * Enqueue an email from a worker env alone — the seam a Workflow step uses.
+ *
+ * Identical in every respect to `EmailCapability.enqueue`, because it *is* that function: the
+ * from-identity, the theme, the bindings and the automatic suppression check (pithy-sh/pithy#355) all
+ * come from the one composed capability. Nothing about a durable send differs from a request-time one
+ * except how the caller got here.
+ */
+export function enqueueFromEnv(env: EmailEnqueueEnv, input: EnqueueInput): Promise<EnqueueResult> {
+  return composedEmail().enqueue(env, input);
+}

package/src/send/retryPolicy.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What a send retries, and what it refuses to.**
+ *
+ * Email already classified the *provider's* vocabulary — `errorMapping.ts` maps every `E_*` code the
+ * Email Service returns to retryable or terminal, and says why. This is the other half: the same
+ * decision in the form the durable step reads, covering the faults that never came from the binding at
+ * all (pithy-sh/pithy#338).
+ *
+ * ## Retryable
+ *
+ * - **`email/rate_limited`** — the per-second or daily quota. The next window is a different answer.
+ * - **`email/send_failed`** — raised by `runSend` **only** when `classifySendError` judged the code
+ *   transient (`E_DELIVERY_FAILED`, `E_INTERNAL_SERVER_ERROR`, or an unknown code getting its one
+ *   bounded retry). A validation, sender, or content code takes the terminal branch there and never
+ *   reaches a throw, which is why this entry is not the hole it looks like — and `retryPolicy.test.ts`
+ *   holds the two classifications to each other rather than trusting this sentence.
+ * - **A transient D1 fault** — the jobs, events and suppression tables. Classified in core.
+ *
+ * ## Terminal
+ *
+ * - **`core/not_found`** — the job row is gone. A send cannot invent the message it was asked to send,
+ *   and a deleted row does not come back over a backoff.
+ * - **`email/template_not_found`, `email/invalid_payload`** — a render that cannot be attempted twice
+ *   with a different result.
+ * - **Anything unclassified**, including a payload that will not parse.
+ *
+ * A suppressed recipient is neither: `runSend` records it and returns, because a person who asked not to
+ * be mailed is an outcome rather than a failure.
+ */
+export const emailWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "email",
+  retryable: {
+    "email/rate_limited": "The send was over a rate or daily quota; the next window admits it.",
+    "email/send_failed":
+      "Only thrown for a code classifySendError judged transient — delivery, an upstream 5xx, or one bounded retry of an unknown code.",
+  },
+};