@pithy-sh/email 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/email
+
+D1-backed email for Cloudflare. Every send is a durable job: scheduled, retried, tracked.
+
+Themeable templates, click, open and unsubscribe tracking, and bounce-driven suppression. No mail is ever sent inline.
+
+```sh
+pithy add email
+```
+
+**Documentation: [pithy.sh/docs/capabilities/email](https://pithy.sh/docs/capabilities/email).** Overview, adding it, using it, and the reference: the job model, send modes, templates.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pithy-sh/email",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/email"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "precompile": "bun scripts/precompile.ts",
+    "build": "bun run precompile && tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "bun run precompile && vitest run",
+    "test:node": "bun run precompile && vitest run --project=node",
+    "test:workers": "bun run precompile && vitest run --project=workers",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "handlebars": "^4.7.9",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "postal-mime": "^3.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,73 @@
+{
+  "name": "email",
+  "package": "@pithy-sh/email",
+  "requiredBindings": [
+    { "type": "d1", "name": "DB" },
+    { "type": "d1", "name": "EMAIL_SUPPRESSIONS" },
+    { "type": "workflow", "name": "EMAIL_SENDER", "job": "send", "className": "EmailSendWorkflow" }
+  ],
+  "peerCapabilities": ["secrets"],
+  "migrationNamespace": "email",
+  "devSecrets": [{ "name": "email-link-signing-key", "devValue": "random" }],
+  "secrets": [
+    {
+      "name": "email-link-signing-key",
+      "origin": {
+        "kind": "minted",
+        "recipe": {
+          "kind": "random",
+          "bytes": 32,
+          "encoding": "base64url"
+        }
+      },
+      "rotation": {
+        "kind": "local"
+      }
+    }
+  ],
+  "whenToEnable": "Transactional and lifecycle email — magic link, OTP, welcome, security alerts, invites, plus newsletters and campaigns. Every send is a durable job: scheduled, retried, and tracked. Auth needs it for magic-link and OTP delivery.",
+  "scaffold": [
+    "Onboard the sending domain onto Cloudflare Email Service (SPF/DKIM/DMARC are configured automatically for a Cloudflare-hosted zone). The from address must use that domain. See the package README.",
+    "Create the link-signing key: `pithy secrets create email-link-signing-key`.",
+    "Run `pithy email provision` — it creates the shared suppression database, migrates it, and deploys the per-environment email worker (send + scheduler Workflows, every-minute cron, send binding).",
+    "To capture bounces in your own worker, enable Email Routing on a subdomain (never the apex — that would move your receiving MX) and pass `--routing-zone <id> --inbound-address <addr> --app-worker <name>` to `pithy email provision`; it creates the one routing rule that delivers bounce/complaint mail to the production app worker's inbound email() handler. Cloudflare also auto-suppresses hard bounces account-wide regardless."
+  ],
+  "configOptions": [
+    {
+      "key": "fromAddress",
+      "default": "noreply@example.com",
+      "describe": "The address every email is sent from. Must use a domain onboarded onto Cloudflare Email Service."
+    },
+    {
+      "key": "fromName",
+      "default": "Pithy",
+      "describe": "The sender display name recipients see. A recognizable name improves deliverability."
+    },
+    {
+      "key": "baseUrl",
+      "default": "https://api.example.com",
+      "constant": "publicOrigin",
+      "describe": "The public base URL of your app worker. Tracking and unsubscribe links are built against it, so it must be reachable from a recipient's inbox."
+    },
+    {
+      "key": "basePath",
+      "default": "/email",
+      "describe": "Where the management routes mount — the send log (`<basePath>/jobs`) and the suppression list (`<basePath>/suppressions`). Every one is control-plane and default-denied: they answer a connected management client, never an end user. The recipient callbacks (click, open, unsubscribe) are not affected and keep their fixed `/_pithy/email` prefix, because those URLs are already minted into mail nobody can recall."
+    },
+    {
+      "key": "theme",
+      "default": "saffron",
+      "describe": "An off-the-shelf theme to bootstrap from: `saffron` (Pithy default), `midnight` (blue), `forest` (green), or `rose` (warm). Fine-tune it with a `customTheme` object in pithy.config.ts (accent, logo URLs, palette colors); body width is per-template, not a theme setting."
+    },
+    {
+      "key": "schedulerEnabled",
+      "default": true,
+      "describe": "Whether the every-minute scheduler Workflow runs. It finds due scheduled and per-timezone sends and fans them out. Disable only if you send exclusively immediate email."
+    },
+    {
+      "key": "devDelivery",
+      "default": "remote",
+      "describe": "What the prebuilt email worker does with a message under `pithy dev`. The default, `remote`, SENDS REAL MAIL from your machine: the Worker runs locally and delivers through Cloudflare Email Service, so a magic link you trigger from localhost arrives in the real inbox — same DKIM, same delivery logs as production. It needs a Cloudflare login `wrangler dev` can use and a sending domain already onboarded. Set `simulator` to send nothing: wrangler logs the sender, recipient and subject and writes the rendered bodies to disk, which is what an offline machine and CI want. Local development only — every deployed environment always sends for real."
+    }
+  ]
+}

package/src/analytics.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EmailEventType } from "./data/enums";
+import type { EmailDatabase } from "./data/tables";
+
+/**
+ * Per-batch email analytics, read from `pithy_email_events` in the app database. A "batch" is a
+ * `campaignId` (set on marketing sends and any send that passes one), so a single grouped query yields
+ * how many were sent, opened, clicked, bounced, complained, and unsubscribed.
+ *
+ * Events live in the **per-environment** app DB and are written where the action happens: `sent` by the
+ * send Workflow, `open`/`click`/`unsubscribe` by the callbacks (whose links point at the sending
+ * environment's worker), and `bounce`/`complaint` by the inbound handler. So a production campaign's
+ * full funnel lands in production's app DB; cross-environment bounce attribution is platform-limited
+ * (one inbound worker per domain), so feature/staging see their own opens/clicks/unsubscribes but not
+ * asynchronously-routed bounces.
+ */
+
+/** Event counts for a campaign, one per `EmailEventType`. Types with no events are `0`. */
+export type CampaignStats = Record<EmailEventType, number>;
+
+/** Every event type at zero — derived from the enum so a new `EmailEventType` can't be forgotten here. */
+const ZERO: CampaignStats = Object.fromEntries(EmailEventType.options.map((type) => [type, 0])) as CampaignStats;
+
+/** Aggregate the events recorded for one campaign into per-type counts. */
+export async function campaignStats(db: EmailDatabase, campaignId: string): Promise<CampaignStats> {
+  const rows = await db
+    .selectFrom("pithyEmailEvents")
+    .select(["type"])
+    .select((eb) => eb.fn.countAll<number>().as("count"))
+    .where("campaignId", "=", campaignId)
+    .groupBy("type")
+    .execute();
+
+  const stats: CampaignStats = { ...ZERO };
+  for (const row of rows) stats[row.type as EmailEventType] = Number(row.count);
+  return stats;
+}

package/src/audit/actions.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The audit actions this capability emits, through the core `emit()` seam.
+ *
+ * **Reads are audited here, not only writes.** The job log is a list of who was mailed what and when,
+ * and the suppression list is every address in the project that ever bounced, complained, or opted
+ * out — reading either is a disclosure of other people's personal data, and a management credential
+ * quietly paging through one of them at three in the morning is exactly the event an adopter needs to
+ * be able to find afterwards. "Which operator read the suppression list on the twelfth" is a question
+ * with an answer, and these are what make it one.
+ *
+ * Emitted with `c.var.emit`, never by importing `@pithy-sh/audit` — the seam is always present
+ * (`noopEmit` when no audit capability is composed), so there is no null check and no hard dependency.
+ * Identifiers, counts, and filters in metadata: never a rendered subject, never a template payload.
+ */
+export const EmailAuditActions = {
+  /**
+   * A page of the job log was read. Recorded with the filter and the page size, not the rows — the
+   * point is that somebody read *some* of it, and how much.
+   */
+  jobsRead: "email/jobs_read",
+  /** One job was opened in full, which is where a recipient's whole address is disclosed. */
+  jobRead: "email/job_read",
+  /**
+   * A failed job was put back in the queue.
+   *
+   * The one operation here that sends mail to a real person, so it is recorded at `warning` with the
+   * job id and the status it came from.
+   */
+  jobRetried: "email/job_retried",
+  /** A page of the global suppression list was read — addresses, in bulk, across every environment. */
+  suppressionsRead: "email/suppressions_read",
+  /** An address was blocked by hand. Silent to the recipient, so the trail is the only record. */
+  suppressionAdded: "email/suppression_added",
+  /**
+   * An address was unblocked.
+   *
+   * The most dangerous line in this file: it re-opens sending to somebody who hard-bounced, reported
+   * spam, or asked to be left alone. Recorded at `warning` with the reason the row carried, so the
+   * trail says what was undone and not merely that something was.
+   */
+  suppressionRemoved: "email/suppression_removed",
+} as const;
+
+/** One of the email capability's audit actions. */
+export type EmailAuditAction = (typeof EmailAuditActions)[keyof typeof EmailAuditActions];

package/src/bounce/classify.ts

@@ -0,0 +1,103 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BounceType } from "../data/enums";
+
+/**
+ * Classify an inbound message as a bounce, complaint, auto-reply, or something to ignore. With the
+ * modern Email Service, hard bounces are auto-suppressed at the platform and surfaced synchronously on
+ * send; this handles delivery-status notifications (DSNs) and feedback-loop complaints (ARF) that are
+ * *routed back* to the worker, plus vacation auto-replies (a deliberate no-op).
+ *
+ * The classifier is pure and works on the already-parsed pieces of the message — its headers and the
+ * raw body text — so it is unit-testable without the Workers runtime. Identification is best-effort:
+ * the failed recipient comes from the DSN's `Final-Recipient`, and the originating job is matched later
+ * by the original `Message-ID` against the stored send `messageId` (no custom VERP return path, which
+ * the simple send binding cannot set).
+ */
+
+/** What an inbound message turned out to be. `ignore` and `auto_reply` produce no side effects. */
+export interface InboundClassification {
+  /** The classification — `ignore` for anything that isn't a recognized bounce/complaint/auto-reply. */
+  type: BounceType | "ignore";
+  /** The affected recipient address, when the message identifies one. */
+  recipient?: string;
+  /** The SMTP/DSN status or diagnostic code, for the row and the event detail. */
+  code?: string;
+  /** The original message's `Message-ID`, used to match the job that bounced. */
+  originalMessageId?: string;
+}
+
+/** Read a header-style field (`Name: value`) from a block of text, case-insensitively. */
+function field(text: string, name: string): string | undefined {
+  const match = new RegExp(`^${name}:\\s*(.+)$`, "im").exec(text);
+  return match?.[1]?.trim();
+}
+
+/** Extract the address from an RFC822 recipient line like `rfc822;user@example.com` or `<user@x>`. */
+function extractAddress(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const afterSemicolon = value.includes(";") ? value.slice(value.indexOf(";") + 1) : value;
+  const angle = /<([^>]+)>/.exec(afterSemicolon);
+  const addr = (angle?.[1] ?? afterSemicolon).trim();
+  return addr.includes("@") ? addr : undefined;
+}
+
+/** The original message id — the explicit DSN field, else the last `Message-ID` (the embedded original). */
+function originalMessageId(raw: string): string | undefined {
+  const explicit = field(raw, "Original-Message-ID");
+  if (explicit) return explicit.replace(/^<|>$/g, "");
+  const ids = [...raw.matchAll(/^Message-ID:\s*<([^>]+)>/gim)].map((m) => m[1]);
+  return ids.length > 0 ? ids[ids.length - 1] : undefined;
+}
+
+/** The inbound message's parsed pieces the classifier needs. */
+export interface InboundMessage {
+  /** The top-level `Content-Type` header value (carries `report-type` for DSN/ARF). */
+  contentType?: string;
+  /** The `Auto-Submitted` header value, if present. */
+  autoSubmitted?: string;
+  /** Whether any auto-responder header (`X-Autoreply`, `X-Autorespond`) is present. */
+  autoReplyHeader?: boolean;
+  /** The raw message body text — DSN/ARF fields are line-structured within it. */
+  raw: string;
+}
+
+/** Classify an inbound message. */
+export function classifyInbound(message: InboundMessage): InboundClassification {
+  const contentType = (message.contentType ?? "").toLowerCase();
+  const raw = message.raw;
+
+  // A delivery-status notification (DSN): a hard or soft bounce.
+  if (contentType.includes("report-type=delivery-status") || /^Action:\s*failed/im.test(raw)) {
+    const status = field(raw, "Status");
+    const diagnostic = field(raw, "Diagnostic-Code");
+    const recipient = extractAddress(field(raw, "Final-Recipient") ?? field(raw, "Original-Recipient"));
+    const soft = status?.startsWith("4") ?? false;
+    return {
+      type: soft ? "soft" : "hard",
+      recipient,
+      code: status ?? diagnostic,
+      originalMessageId: originalMessageId(raw),
+    };
+  }
+
+  // A feedback-loop complaint (ARF): the recipient reported the message as spam.
+  if (contentType.includes("report-type=feedback-report") || /^Feedback-Type:/im.test(raw)) {
+    const recipient = extractAddress(field(raw, "Original-Rcpt-To") ?? field(raw, "Removal-Recipient"));
+    return {
+      type: "complaint",
+      recipient,
+      code: field(raw, "Feedback-Type") ?? "complaint",
+      originalMessageId: originalMessageId(raw),
+    };
+  }
+
+  // A vacation/auto-responder reply: explicitly a no-op so it never suppresses a real recipient.
+  const autoSubmitted = (message.autoSubmitted ?? "").toLowerCase();
+  if (message.autoReplyHeader || (autoSubmitted && autoSubmitted !== "no")) {
+    return { type: "auto_reply" };
+  }
+
+  return { type: "ignore" };
+}

package/src/bounce/handler.ts

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import type { CapabilityEmailHandler } from "@pithy-sh/core/src/capability/capability";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import PostalMime from "postal-mime";
+import {
+  type EmailDatabase,
+  type EmailSuppressionDatabase,
+  emailDatabase,
+  emailSuppressionDatabase,
+} from "../data/tables";
+import { recordEvent } from "../send/events";
+import { suppress } from "../send/suppression";
+import { classifyInbound, type InboundClassification } from "./classify";
+
+/**
+ * The inbound bounce/complaint handler — the capability's `email()` seam. The Worker entrypoint fans
+ * incoming mail to it; it parses the message, classifies it, and applies the result: a hard bounce or
+ * complaint suppresses the address and marks the originating job bounced; a soft bounce records the
+ * event but does not suppress (Cloudflare auto-retries those); an auto-reply or anything unrecognized is
+ * a no-op. The job is matched by the original `Message-ID` against the stored send `messageId`.
+ */
+
+/** What `applyInbound` did, for logging and tests. */
+export interface InboundOutcome {
+  /** Whether any side effect was applied (false for auto-reply / ignore). */
+  acted: boolean;
+  /** The classification type. */
+  type: InboundClassification["type"];
+  /** The job id matched by original Message-ID, if any. */
+  jobId?: string;
+  /** Whether the address was added to the suppression list. */
+  suppressed: boolean;
+}
+
+/**
+ * Apply a classification's side effects. Suppression is written to the **shared** suppression database
+ * (so it applies in every environment); the job lookup and the bounce/complaint event use the app
+ * database. Pure of any MIME parsing — unit-testable. Note the single inbound worker only reaches its
+ * own app DB, so a job-row update is best-effort (the originating job may live in another environment),
+ * whereas the suppression — the safety-critical part — is always global.
+ */
+export async function applyInbound(
+  db: EmailDatabase,
+  suppressionDb: EmailSuppressionDatabase,
+  c: InboundClassification,
+  now: Date,
+  environment?: string,
+): Promise<InboundOutcome> {
+  if (c.type === "ignore" || c.type === "auto_reply") return { acted: false, type: c.type, suppressed: false };
+
+  // Match the originating job by the original Message-ID against the stored send messageId.
+  const job = c.originalMessageId
+    ? await db
+        .selectFrom("pithyEmailJobs")
+        .select(["id", "toAddress", "status", "campaignId"])
+        .where("messageId", "=", c.originalMessageId)
+        .executeTakeFirst()
+    : undefined;
+
+  const recipient = c.recipient ? normalizeAddress(c.recipient) : job ? normalizeAddress(job.toAddress) : undefined;
+  const isSuppressing = c.type === "hard" || c.type === "complaint";
+  let suppressed = false;
+
+  if (recipient && isSuppressing) {
+    await suppress(
+      suppressionDb,
+      {
+        email: recipient,
+        reason: c.type === "complaint" ? "complaint" : "hard_bounce",
+        jobId: job?.id ?? null,
+        environment,
+        detail: c.code ?? null,
+      },
+      now,
+    );
+    suppressed = true;
+  }
+
+  if (job) {
+    await db
+      .updateTable("pithyEmailJobs")
+      .set({
+        bounceCode: c.code ?? null,
+        bounceType: c.type,
+        status: isSuppressing ? "bounced" : job.status,
+        updatedAt: SQLiteDate.encode(now),
+      })
+      .where("id", "=", job.id)
+      .execute();
+    // Record the event with the job's campaign so batch analytics (opens/clicks/bounces/unsubscribes
+    // per campaign) see bounces alongside the rest.
+    await recordEvent(
+      db,
+      {
+        jobId: job.id,
+        recipient: recipient ?? normalizeAddress(job.toAddress),
+        type: c.type === "complaint" ? "complaint" : "bounce",
+        campaignId: job.campaignId ?? null,
+        detail: c.code ?? null,
+      },
+      now,
+    );
+  }
+
+  return { acted: suppressed || Boolean(job), type: c.type, jobId: job?.id, suppressed };
+}
+
+/** Build the inbound-email handler for the `Capability.email` seam. Reads `DB` + `EMAIL_SUPPRESSIONS` from env. */
+export function createBounceHandler(): CapabilityEmailHandler {
+  return async (message, env) => {
+    const raw = await new Response(message.raw).text();
+    const parsed = await PostalMime.parse(raw);
+    const headers: Record<string, string> = {};
+    for (const header of parsed.headers) headers[header.key.toLowerCase()] = header.value;
+
+    const classification = classifyInbound({
+      contentType: headers["content-type"],
+      autoSubmitted: headers["auto-submitted"],
+      autoReplyHeader: "x-autoreply" in headers || "x-autorespond" in headers,
+      raw,
+    });
+
+    const bindings = env as unknown as { DB: D1Database; EMAIL_SUPPRESSIONS: D1Database; ENVIRONMENT?: string };
+    await applyInbound(
+      emailDatabase(bindings.DB),
+      emailSuppressionDatabase(bindings.EMAIL_SUPPRESSIONS),
+      classification,
+      new Date(),
+      bindings.ENVIRONMENT,
+    );
+  };
+}