@volter/twin-postmark 0.1.0

package/src/postmark-twin.ts

@@ -0,0 +1,1520 @@
+// Postmark API twin REQUEST HANDLER — the canonical api.postmarkapp.com surface for the twin,
+// backed by the event/action-log kernel. Contract:
+// handlePostmarkTwinRequest({method, path, body}) -> {status, body}. Response SHAPES mirror
+// real Postmark (PascalCase fields, `{ErrorCode, Message}` on every response, UUID MessageIDs,
+// integer resource ids, `{TotalCount, <Collection>}` list envelopes) so the real `postmark`
+// SDK works unmodified. HTTP wrapper: postmark-server.ts → createPostmarkTwinServer.
+//
+// State lives in the action log: writes are local actions, reads are the projection. No real
+// Postmark is ever called.
+//
+// ── GROUNDING (where every shape below comes from) ────────────────────────────────────
+// 1. The OFFICIAL `postmark` npm SDK's own compiled route map + TypeScript models
+//    (node_modules/postmark/dist/client/{ServerClient,AccountClient}.js and
+//    dist/client/models/**/*.d.ts) — a first-party artifact, read during this pack's build.
+//    That is the source for every path, HTTP verb, field name, casing and list envelope.
+// 2. developer.postmarkapp.com's published API-error-code table (163 rows) — the source for
+//    every `ErrorCode` number + its HTTP status below.
+// 3. LIVE read-only probes of api.postmarkapp.com made during this pack's build with the
+//    documented public test token `POSTMARK_API_TEST` (and unauthenticated) — marked [WIRE].
+//    These corrected three things the docs alone got wrong, all encoded below:
+//      · `Subject` is NOT a required field on POST /email (a send without one succeeds);
+//      · the 401 Message text is endpoint-scoped ("valid Server token" vs "valid Account
+//        token"), not the merged generic string the docs table shows;
+//      · `POSTMARK_API_TEST` is /email-ONLY — anywhere else it is 403 + ErrorCode 10 — and a
+//        send made with it answers "Test job accepted" rather than "OK".
+// Anything NOT grounded in (1)-(3) is marked `⚠ doc-unverified` in a comment and never
+// asserted beyond what a verify() actually proves. Human-readable `Message` strings are the
+// vendor's published text where the table gives it, and descriptive twin text otherwise.
+//
+// AUTH. Postmark authenticates with `X-Postmark-Server-Token` on server-scoped endpoints and
+// `X-Postmark-Account-Token` on account-scoped ones (SDK: ClientOptions.AuthHeaderNames) —
+// NOT a bearer token. A twin fakes auth locally, so any non-empty token is accepted; a
+// missing or empty token fails like the vendor: 401 `{ErrorCode: 10, Message}`.
+//
+// THE meaty part: a SENT EMAIL is STORED (twin state, never SMTP-delivered) and progresses
+// through a DETERMINISTIC OFFLINE delivery lifecycle that writes real `MessageEvents` onto the
+// stored message, mints Bounce records + suppressions on a bounce, and POSTs Postmark's real
+// webhook payloads (RecordType: Delivery/Open/Click/Bounce/SpamComplaint) to registered
+// webhooks (postmark-events.ts).
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { deliveryPlan, emitPostmarkInboundHook, emitPostmarkWebhook, type PostmarkWebhookDelivery } from './postmark-events.ts';
+
+const SERVICE = 'postmark';
+
+export type PostmarkRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** Injected webhook deliverer (fake in tests, HTTP live). Keeps verify() offline. */
+  deliver?: PostmarkWebhookDelivery;
+  /**
+   * Request headers (case-insensitive). When PRESENT (the HTTP server always supplies them),
+   * the twin enforces Postmark's token auth: a missing/empty `X-Postmark-Server-Token` (or
+   * `X-Postmark-Account-Token` on account routes) → 401 `{ErrorCode:10}`. When the whole
+   * object is ABSENT, auth is not exercised — the in-process verify()/mirror path is a
+   * trusted local call, mirroring the resend pack's convention.
+   */
+  headers?: Record<string, string>;
+};
+export type PostmarkResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+/**
+ * The Postmark `ErrorCode` values this twin emits, each with the HTTP status the vendor
+ * pairs it with. Every number + status here is transcribed from developer.postmarkapp.com's
+ * published API-error-codes table (see the GROUNDING note above). Note how few of these are
+ * 404: Postmark answers "not found" for a KNOWN route with 422 + a per-domain code, and
+ * reserves 404 for a route that does not exist at all.
+ */
+export const POSTMARK_ERRORS = {
+  ok: 0,
+  badToken: 10, //                  401 — bad or missing API token (or wrong token type)
+  bulkNotApproved: 14, //           422 — Bulk API requires approval
+  invalidEmailRequest: 300, //      422 — send validation (From, recipients, body, limits)
+  invalidJson: 402, //              422 — Invalid JSON
+  invalidRequestField: 403, //      422 — Invalid request field(s)
+  inactiveRecipient: 406, //        422 — recipient suppressed (hard bounce / spam complaint)
+  tooManyBatchMessages: 410, //     422 — over the 500-message batch cap
+  signatureNotFound: 501, //        422 — sender signature not found
+  signatureNoData: 502, //          422 — no update data or signature data received
+  publicDomainSignature: 503, //    422 — can't use a public-domain address
+  signatureExists: 504, //          422 — signature already exists
+  domainNotFound: 510, //           422 — domain not found
+  domainExists: 512, //             422 — domain already exists
+  domainNameRequired: 514, //       422 — Name required to create a domain
+  fromEmailRequired: 520, //        422 — FromEmail required to create a signature
+  invalidEmailValue: 522, //        422 — not a valid email address / domain
+  serverInboundDomainInUse: 602, // 422 — inbound domain already in use
+  serverNameExists: 603, //         422 — server name already exists
+  serverNameInvalid: 608, //        422 — server name invalid or missing
+  serverNoData: 609, //             422 — no server data received
+  serverNotFound: 1453, //          422 — this server was not found. NB the published table
+  //                                       files this under its SMTP-Tokens block, but it is
+  //                                       the only "server was not found" code Postmark
+  //                                       publishes, so it is what a server-id miss returns.
+  messageNotFound: 701, //          422 — message not found / can't be bypassed or retried
+  inboundRuleNoData: 809, //        422 — no trigger data received
+  inboundRuleExists: 810, //        422 — this inbound rule already exists
+  inboundRuleNotFound: 812, //      422 — this inbound rule was not found
+  bounceNotFound: 1001, //          422 — bounce not found / dump no longer available
+  bounceCannotActivate: 1003, //    422 — this bounce type cannot be reactivated
+  templateNotFound: 1101, //        422 — no TemplateId/TemplateAlias, or it did not resolve
+  templateNoData: 1109, //          422 — no template data received
+  streamTypeInvalid: 1221, //       422 — invalid MessageStreamType
+  streamNameRequired: 1223, //      422 — a valid Name must be provided
+  streamNotFound: 1226, //          422 — message stream for the provided ID was not found
+  streamIdInvalid: 1227, //         422 — ID must start with a letter, ≤30 chars
+  streamCannotArchiveDefault: 1229, // 422 — can't archive the default transactional/inbound stream
+  streamIdExists: 1230, //          422 — the ID already exists on this server
+  streamCannotArchive: 1241, //     422 — stream is unable to be archived at this time
+  streamCannotUnarchive: 1232, //   422 — this stream can no longer be unarchived
+  streamIdReservedPrefix: 1233, //  422 — the ID must not start with `pm-`
+  sendStreamNotFound: 1235, //      422 — the stream provided does not exist on this server
+  dataRemovalIdInvalid: 1301, //    422 — missing or incorrect data-removal request ID
+  webhookArchivedStream: 1350, //   422 — cannot create a webhook on an archived stream
+  webhookNotFound: 1352, //         422 — webhook for the provided ID was not found
+  webhookUrlRequired: 1354, //      422 — the request must contain a valid Url field
+  suppressionAuthority: 1406, //    200 (per-item) — not allowed to change this suppression
+  suppressionInvalidEmail: 1408, // 422 / per-item — an invalid email address was provided
+  suppressionNoBody: 1409, //       422 — a proper request body must be provided
+} as const;
+
+/** Postmark's failure envelope: `{ ErrorCode, Message }` at the given HTTP status. */
+function err(message: string, status: number, errorCode: number): PostmarkResponse {
+  return { status, body: { ErrorCode: errorCode, Message: message } };
+}
+/** The overwhelmingly common Postmark failure: HTTP 422 + a per-domain ErrorCode. */
+function fail(errorCode: number, message: string): PostmarkResponse {
+  return err(message, 422, errorCode);
+}
+/** Postmark's plain success acknowledgement: `{ ErrorCode: 0, Message: '…' }`. */
+function ack(message: string): PostmarkResponse {
+  return { status: 200, body: { ErrorCode: POSTMARK_ERRORS.ok, Message: message } };
+}
+
+// The documented batch cap, live-confirmed by the vendor's own 410 message text.
+const MAX_BATCH = 500;
+// Postmark's documented public test token. [WIRE] It is accepted ONLY on /email; every other
+// path answers 403 + ErrorCode 10, and a send made with it says "Test job accepted".
+const TEST_TOKEN = 'POSTMARK_API_TEST';
+
+// Case-insensitive header lookup (Postmark's own header names are case-insensitive).
+function header(headers: Record<string, string> | undefined, name: string): string | undefined {
+  if (!headers) return undefined;
+  const want = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === want) return v;
+  return undefined;
+}
+
+/**
+ * Postmark token auth. `scope` picks the header the vendor requires for that route family.
+ * Absent `headers` ⇒ auth not exercised (trusted in-process call). Present ⇒ the token must
+ * be there and non-empty, else the vendor's 401 `{ErrorCode: 10}` with the ENDPOINT-SCOPED
+ * message text [WIRE]. A twin fakes auth, so the token's VALUE is never checked against a
+ * real account — except for the documented test token, whose /email-only restriction IS
+ * modeled (403 + ErrorCode 10 anywhere else) because a caller can trip it for real.
+ */
+function authError(req: PostmarkRequest, scope: 'server' | 'account', isEmailRoute: boolean): PostmarkResponse | null {
+  if (req.headers === undefined) return null;
+  const name = scope === 'account' ? 'x-postmark-account-token' : 'x-postmark-server-token';
+  const token = (header(req.headers, name) ?? '').trim();
+  if (token === '') {
+    return err(
+      `Request does not contain a valid ${scope === 'account' ? 'Account' : 'Server'} token.`,
+      401,
+      POSTMARK_ERRORS.badToken,
+    );
+  }
+  if (token === TEST_TOKEN && !isEmailRoute) {
+    return err('The Postmark Test API Token may only be used on the /email endpoint.', 403, POSTMARK_ERRORS.badToken);
+  }
+  return null;
+}
+/** True when the caller authenticated with Postmark's public test token. */
+function usingTestToken(req: PostmarkRequest): boolean {
+  return (header(req.headers, 'x-postmark-server-token') ?? '').trim() === TEST_TOKEN;
+}
+
+function asObject(v: unknown): Record<string, unknown> {
+  return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+function nowIso(occurredAt?: string): string {
+  return occurredAt ?? new Date().toISOString();
+}
+
+// ── projection helpers ──────────────────────────────────────────────────────────────
+/** ALL rows of a type, INCLUDING soft-deleted ones (the id ratchet must see tombstones). */
+function allRows(type: string, root?: string) {
+  return projectResources(SERVICE, root).filter((r) => r.type === type && !r.id.startsWith('_'));
+}
+/** Live (non-soft-deleted) rows of a type. */
+function rows(type: string, root?: string) {
+  return allRows(type, root).filter((r) => (r as Record<string, unknown>).deleted !== true);
+}
+/** The emitted body: drop kernel meta + twin-internal `_`-prefixed fields. */
+function view(r: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(r)) {
+    if (k === 'type' || k === 'id' || k === 'updatedAt' || k.startsWith('_')) continue;
+    out[k] = v;
+  }
+  return out;
+}
+function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+
+/**
+ * Mint the next INTEGER id for a type (Postmark's TemplateId / Bounce ID / Webhook ID /
+ * Domain ID … are integers). Ratchets over EVERY row of the type INCLUDING soft-deleted
+ * tombstones, so a delete→recreate can never re-issue a retired id — the dirty-state bug
+ * class ADDING_A_TWIN §6 calls out (gcs generations, supermemory re-add). Deterministic
+ * from a fresh root.
+ */
+function nextIntId(type: string, root?: string): number {
+  let max = 0;
+  for (const r of allRows(type, root)) {
+    const n = Number(r.id);
+    if (Number.isFinite(n) && n > max) max = n;
+  }
+  return max + 1;
+}
+
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist. */
+function stableHex(seed: string, n: number): string {
+  let out = '';
+  for (let round = 0; out.length < n; round += 1) {
+    let h = 0x811c9dc5;
+    const s = `${round}:${seed}`;
+    for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+    out += h.toString(16).padStart(8, '0');
+  }
+  return out.slice(0, n);
+}
+
+/**
+ * A Postmark MessageID: a plain UUID, no vendor prefix (SDK: MessageSendingResponse).
+ *
+ * DETERMINISTIC (R9): the shape stays the vendor's 8-4-4-4-12 hex, but the bytes come from
+ * the WORLD instant plus the count of rows the type already holds — never `crypto.randomUUID`.
+ * Two identical worlds therefore mint identical MessageIDs and a resource-level replay
+ * (`GET /messages/outbound` after a `POST /email`) is byte-identical across roots. The row
+ * count is part of the seed, so several sends at one frozen instant still get distinct ids.
+ */
+function newMessageId(type: 'message' | 'inbound_message', req: PostmarkRequest): string {
+  const seed = `${type}:${req.occurredAt ?? ''}:${allRows(type, req.root).length}`;
+  const hex = stableHex(seed, 32);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/**
+ * Monotonic per-process write counter, threaded onto every write as the twin-internal `_seq`.
+ *
+ * WHY THIS EXISTS (do not remove it). The kernel dedupes an action by
+ * `operation:subjectId:occurredAt:contentHash` where `occurredAt` has MILLISECOND resolution
+ * (control-plane/src/serve.ts `applyTwinWrite`). That is the right behavior for a genuinely
+ * re-issued identical write — but a REST twin's repeated identical STATE TRANSITIONS are not
+ * replays, they are separate API calls that must each apply. Postmark has no idempotency key
+ * on any of these endpoints, so `PUT /domains/1/verifyDKIM` → `POST …/rotateDKIM` →
+ * `PUT …/verifyDKIM` is three real calls; when the two verifyDKIM calls landed in the same
+ * millisecond with byte-identical fields, the kernel swallowed the second and the domain
+ * stayed stuck at `DKIMUpdateStatus: 'Pending'`. The same bug silently dropped a re-created
+ * suppression after a bounce reactivation. `_seq` makes each call's content genuinely
+ * distinct, so nothing is ever lost; it is `_`-prefixed, so `view()`/the conformance
+ * `emitted()` strip it and it never reaches the wire.
+ */
+// PROTOCOL 2: the ordinal comes from the TREE, not the process — a per-subject `_seq` read off the row
+// this write lands on. A module counter drifted with process uptime, so two identical worlds stamped the
+// same call differently; the tree's own count is the same in both.
+/** The next per-subject ordinal, read off the row this write lands on. */
+function nextSeqFor(type: string, id: string, root?: string): number {
+  const current = projectResources(SERVICE, root).find((r) => r.type === type && r.id === id) as { _seq?: unknown } | undefined;
+  return (typeof current?._seq === 'number' ? current._seq : 0) + 1;
+}
+
+async function writeResource(
+  type: string,
+  id: string,
+  fields: Record<string, unknown>,
+  op: string,
+  req: PostmarkRequest,
+): Promise<Record<string, unknown>> {
+  const { resource } = await applyTwinWrite(
+    SERVICE,
+    {
+      operation: op,
+      subjectType: type,
+      subjectId: id,
+      fields: { ...fields, _seq: nextSeqFor(type, id, req.root) },
+      ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+      actor: { kind: 'agent' },
+    },
+    req.root,
+  );
+  return view(resource as unknown as Record<string, unknown>);
+}
+
+// ── bootstrap: a Postmark server always has its default message streams ──────────────
+// A real Postmark server is created with three streams — `outbound` (transactional),
+// `broadcast`, and `inbound` — so `GET /message-streams` is never empty on a live account.
+// The twin materializes them lazily on first touch (idempotent; no-op once present).
+const DEFAULT_STREAMS = [
+  { ID: 'outbound', Name: 'Transactional Stream', MessageStreamType: 'Transactional', Description: 'Default Transactional Stream' },
+  { ID: 'broadcast', Name: 'Broadcast Stream', MessageStreamType: 'Broadcast', Description: 'Default Broadcast Stream' },
+  { ID: 'inbound', Name: 'Inbound Stream', MessageStreamType: 'Inbound', Description: 'Default Inbound Stream' },
+] as const;
+/** Postmark refuses to archive the default transactional + inbound streams (ErrorCode 1229). */
+const UNARCHIVABLE_STREAMS = new Set(['outbound', 'inbound']);
+const DEFAULT_SERVER_ID = 1;
+
+async function bootstrap(req: PostmarkRequest): Promise<void> {
+  if (req.readOnly) return; // a read-only mirror serves what was pulled; it never writes
+  const at = nowIso(req.occurredAt);
+  // Materialize each default INDIVIDUALLY, keyed on its own id.
+  //
+  // §9 found a real dirty-state bug here: these guards used to be `allRows(type).length === 0`,
+  // i.e. "has this type any rows at all?". After `syncPostmarkFromReal` pulled a SINGLE
+  // real stream (or a single real server), the type was non-empty and the defaults were
+  // never created — so on a pulled twin `GET /server` answered "server not found" and a
+  // plain `POST /email` (which defaults to the `outbound` stream) died with ErrorCode 1235.
+  // Per-id checks make bootstrap correct over prior state, not just from empty.
+  for (const s of DEFAULT_STREAMS) {
+    if (getRow('message_stream', s.ID, req.root)) continue;
+    await writeResource('message_stream', s.ID, {
+      ID: s.ID, ServerID: DEFAULT_SERVER_ID, Name: s.Name, Description: s.Description,
+      MessageStreamType: s.MessageStreamType, CreatedAt: at, UpdatedAt: null, ArchivedAt: null,
+      SubscriptionManagementConfiguration: { UnsubscribeHandlingType: s.MessageStreamType === 'Broadcast' ? 'Postmark' : 'None' },
+    }, 'message_stream.bootstrap', req);
+  }
+  if (!getRow('server', String(DEFAULT_SERVER_ID), req.root)) {
+    await writeResource('server', String(DEFAULT_SERVER_ID), serverRecord(DEFAULT_SERVER_ID, 'Twin Server', {}), 'server.bootstrap', req);
+  }
+}
+
+/** The Server object shape Postmark returns (SDK: models/server/Server.d.ts). */
+function serverRecord(id: number, name: string, over: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ID: id, Name: name, ApiTokens: [`postmark-twin-server-token-${id}`],
+    ServerLink: `https://account.postmarkapp.com/servers/${id}/streams`,
+    Color: 'blue', SmtpApiActivated: true, RawEmailEnabled: false, DeliveryType: 'Live',
+    InboundAddress: `twin${id}inbound@inbound.postmarkapp.com`,
+    InboundHookUrl: '', BounceHookUrl: '', OpenHookUrl: '', DeliveryHookUrl: '', ClickHookUrl: '',
+    PostFirstOpenOnly: false, InboundDomain: '', InboundHash: `twinhash${id}`, InboundSpamThreshold: 5,
+    TrackOpens: false, TrackLinks: 'None', IncludeBounceContentInHook: false, EnableSmtpApiErrorHooks: false,
+    ...pickServerFields(over),
+  };
+}
+
+// ── recipient parsing ───────────────────────────────────────────────────────────────
+/** Postmark takes recipients as a COMMA-SEPARATED STRING (`To: "a@b.dev, Name <c@d.dev>"`). */
+function parseRecipients(v: unknown): Array<{ Email: string; Name: string }> {
+  if (typeof v !== 'string' || v.trim() === '') return [];
+  return v.split(',').map((raw) => {
+    const s = raw.trim();
+    const m = /^(.*)<([^>]+)>$/.exec(s);
+    if (m) return { Email: m[2]!.trim(), Name: m[1]!.trim().replace(/^"|"$/g, '') };
+    return { Email: s, Name: '' };
+  }).filter((r) => r.Email !== '');
+}
+function emailsOf(list: Array<{ Email: string }>): string[] {
+  return list.map((r) => r.Email);
+}
+/** The bare address of a `From`-style value (which may be `Name <addr>`). */
+function bareAddress(v: unknown): string {
+  return parseRecipients(typeof v === 'string' ? v : '')[0]?.Email ?? '';
+}
+const looksLikeEmail = (s: string) => /^[^@\s,]+@[^@\s,]+\.[^@\s,]+$/.test(s);
+
+// ── suppressions ────────────────────────────────────────────────────────────────────
+const suppressionId = (stream: string, email: string) => `${stream}::${email.toLowerCase()}`;
+
+function isSuppressed(stream: string, email: string, root?: string): boolean {
+  return getRow('suppression', suppressionId(stream, email), root) !== undefined;
+}
+async function suppress(stream: string, email: string, reason: string, origin: string, req: PostmarkRequest): Promise<void> {
+  await writeResource('suppression', suppressionId(stream, email), {
+    EmailAddress: email, SuppressionReason: reason, Origin: origin,
+    CreatedAt: nowIso(req.occurredAt), MessageStream: stream, deleted: false,
+  }, 'suppression.create', req);
+}
+
+// ── send validation ─────────────────────────────────────────────────────────────────
+/**
+ * Validate a send payload the way Postmark really does [WIRE, probed against the live API
+ * with the public test token]:
+ *   · `From` is validated FIRST — an empty body answers "Invalid 'From' value.", not a
+ *     recipient error;
+ *   · zero recipients across To/Cc/Bcc → "Zero recipients specified.";
+ *   · a non-templated send needs HtmlBody or TextBody;
+ *   · `Subject` is NOT required — a send with no Subject SUCCEEDS on the real API. (This is
+ *     the single most commonly-assumed-wrong field on this endpoint; do not "fix" it.)
+ * Every failure is 422 `{ErrorCode: 300}`.
+ */
+function validateSend(p: Record<string, unknown>, templated: boolean): PostmarkResponse | null {
+  if (typeof p.From !== 'string' || !looksLikeEmail(bareAddress(p.From))) {
+    return fail(POSTMARK_ERRORS.invalidEmailRequest, "Invalid 'From' value.");
+  }
+  const recipients = [...parseRecipients(p.To), ...parseRecipients(p.Cc), ...parseRecipients(p.Bcc)];
+  if (recipients.length === 0) return fail(POSTMARK_ERRORS.invalidEmailRequest, 'Zero recipients specified.');
+  const bad = recipients.find((r) => !looksLikeEmail(r.Email));
+  if (bad) return fail(POSTMARK_ERRORS.invalidEmailRequest, `Error parsing 'To': Illegal email address '${bad.Email}'.`);
+  // Postmark caps each of To/Cc/Bcc at 50 recipients.
+  for (const [field, list] of [['To', p.To], ['Cc', p.Cc], ['Bcc', p.Bcc]] as const) {
+    if (parseRecipients(list).length > 50) {
+      return fail(POSTMARK_ERRORS.invalidEmailRequest, `Error parsing '${field}': you may only send to 50 recipients per field.`);
+    }
+  }
+  if (!templated) {
+    const hasHtml = typeof p.HtmlBody === 'string' && p.HtmlBody !== '';
+    const hasText = typeof p.TextBody === 'string' && p.TextBody !== '';
+    if (!hasHtml && !hasText) return fail(POSTMARK_ERRORS.invalidEmailRequest, 'Provide either email TextBody or HtmlBody or both.');
+  }
+  if (p.Attachments !== undefined) {
+    if (!Array.isArray(p.Attachments)) return fail(POSTMARK_ERRORS.invalidEmailRequest, "Error parsing 'Attachments': expected an array.");
+    for (const raw of p.Attachments) {
+      const a = asObject(raw);
+      if (typeof a.Name !== 'string' || a.Name === '') return fail(POSTMARK_ERRORS.invalidEmailRequest, "Error parsing 'Attachments': each attachment requires a Name.");
+      if (typeof a.Content !== 'string' || a.Content === '') return fail(POSTMARK_ERRORS.invalidEmailRequest, "Error parsing 'Attachments': each attachment requires base64 Content.");
+      if (typeof a.ContentType !== 'string' || a.ContentType === '') return fail(POSTMARK_ERRORS.invalidEmailRequest, "Error parsing 'Attachments': each attachment requires a ContentType.");
+    }
+  }
+  return null;
+}
+
+// ── template resolution + rendering ─────────────────────────────────────────────────
+/** Postmark resolves a template by numeric TemplateId OR by string Alias. */
+function resolveTemplate(idOrAlias: unknown, root?: string): Record<string, unknown> | undefined {
+  const key = String(idOrAlias ?? '');
+  if (key === '') return undefined;
+  const list = rows('template', root);
+  return list.find((t) => String(t.TemplateId) === key) ?? list.find((t) => t.Alias != null && String(t.Alias) === key);
+}
+
+/**
+ * Postmark's Mustachio rendering, modeled for the `{{ token }}` interpolation a transactional
+ * template actually uses (dotted paths included). An unknown key renders EMPTY — Postmark's
+ * rendering is non-strict, so a missing model key is not an error.
+ */
+function renderTemplate(source: unknown, model: Record<string, unknown>): string {
+  if (typeof source !== 'string') return '';
+  return source.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_m, path: string) => {
+    let cur: unknown = model;
+    for (const seg of path.split('.')) {
+      if (cur && typeof cur === 'object' && seg in (cur as Record<string, unknown>)) cur = (cur as Record<string, unknown>)[seg];
+      else return '';
+    }
+    return cur === null || cur === undefined ? '' : String(cur);
+  });
+}
+/** Every `{{ token }}` a template's content references — Postmark's SuggestedTemplateModel. */
+function suggestedModel(...sources: unknown[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const s of sources) {
+    if (typeof s !== 'string') continue;
+    for (const m of s.matchAll(/\{\{\s*([\w.]+)\s*\}\}/g)) {
+      const key = m[1]!.split('.')[0]!;
+      if (!(key in out)) out[key] = `${key}_Value`;
+    }
+  }
+  return out;
+}
+
+// ── the send path ───────────────────────────────────────────────────────────────────
+/**
+ * Send ONE email: store it as twin state, then run its DETERMINISTIC OFFLINE delivery
+ * lifecycle — appending real `MessageEvents` to the stored message, minting a Bounce record
+ * + suppression on a bounce, and POSTing Postmark's real webhook payloads. Returns the
+ * vendor's `MessageSendingResponse`.
+ */
+async function sendOne(p: Record<string, unknown>, req: PostmarkRequest): Promise<PostmarkResponse> {
+  const stream = typeof p.MessageStream === 'string' && p.MessageStream !== '' ? p.MessageStream : 'outbound';
+  if (!getRow('message_stream', stream, req.root)) {
+    return fail(POSTMARK_ERRORS.sendStreamNotFound, 'The stream provided does not exist on this server.');
+  }
+  const to = parseRecipients(p.To);
+  const cc = parseRecipients(p.Cc);
+  const bcc = parseRecipients(p.Bcc);
+  const recipients = [...emailsOf(to), ...emailsOf(cc), ...emailsOf(bcc)];
+
+  // Postmark refuses to send to a SUPPRESSED (inactive) recipient: 422 `{ErrorCode: 406}`.
+  // Genuinely stateful — it only fires over PRIOR state (an earlier hard bounce/spam
+  // complaint, or an explicit suppression POST), so a fresh-root-only test cannot reach it.
+  const blocked = recipients.filter((e) => isSuppressed(stream, e, req.root));
+  if (blocked.length) {
+    return fail(
+      POSTMARK_ERRORS.inactiveRecipient,
+      `You tried to send to recipient(s) that have been marked as inactive. Found inactive addresses: ${blocked.join(', ')}. Inactive recipients are ones that have generated a hard bounce or a spam complaint.`,
+    );
+  }
+
+  const at = nowIso(req.occurredAt);
+  const messageId = newMessageId('message', req);
+  await writeResource('message', messageId, {
+    MessageID: messageId,
+    Tag: typeof p.Tag === 'string' ? p.Tag : '',
+    To: to, Cc: cc, Bcc: bcc, Recipients: recipients,
+    ReceivedAt: at,
+    From: String(p.From ?? ''),
+    Subject: typeof p.Subject === 'string' ? p.Subject : '',
+    Attachments: Array.isArray(p.Attachments) ? p.Attachments.map((a) => String(asObject(a).Name ?? '')) : [],
+    Status: 'Sent',
+    TrackOpens: p.TrackOpens === true,
+    TrackLinks: typeof p.TrackLinks === 'string' && p.TrackLinks !== '' ? p.TrackLinks : 'None',
+    Metadata: asObject(p.Metadata),
+    MessageStream: stream,
+    Sandboxed: false,
+    HtmlBody: typeof p.HtmlBody === 'string' ? p.HtmlBody : null,
+    TextBody: typeof p.TextBody === 'string' ? p.TextBody : null,
+    ReplyTo: typeof p.ReplyTo === 'string' ? p.ReplyTo : '',
+    Headers: Array.isArray(p.Headers) ? p.Headers : [],
+    MessageEvents: [],
+  }, 'message.send', req);
+
+  await runDelivery(messageId, req);
+
+  const body: Record<string, unknown> = {
+    To: emailsOf(to).join(', '),
+    SubmittedAt: at,
+    MessageID: messageId,
+    ErrorCode: POSTMARK_ERRORS.ok,
+    // [WIRE] the real API answers "Test job accepted" for a test-token send, "OK" otherwise.
+    Message: usingTestToken(req) ? 'Test job accepted' : 'OK',
+  };
+  if (cc.length) body.Cc = emailsOf(cc).join(', ');
+  if (bcc.length) body.Bcc = emailsOf(bcc).join(', ');
+  return { status: 200, body };
+}
+
+/**
+ * Drive the stored message through its deterministic OFFLINE delivery outcome: append the
+ * vendor's `MessageEvents`, flip `Status`, mint a Bounce row + suppression for a bounce or
+ * spam complaint, and POST each event as Postmark's real webhook payload.
+ */
+async function runDelivery(messageId: string, req: PostmarkRequest): Promise<void> {
+  const msg = getRow('message', messageId, req.root);
+  if (!msg) return;
+  const at = nowIso(req.occurredAt);
+  const stream = String(msg.MessageStream ?? 'outbound');
+  const recipient = (msg.Recipients as string[] | undefined)?.[0] ?? '';
+  const plan = deliveryPlan({
+    recipient,
+    trackOpens: msg.TrackOpens === true,
+    trackLinks: String(msg.TrackLinks ?? 'None'),
+  });
+  const client = { Name: 'Twin Mail', Company: 'Volter', Family: 'Twin' };
+  const geo = { CountryISOCode: 'US', Country: 'United States' };
+
+  const events: Array<Record<string, unknown>> = [];
+  for (const kind of plan.events) {
+    if (kind === 'Delivered') {
+      events.push({ Recipient: recipient, Type: 'Delivered', ReceivedAt: at, Details: { DeliveryMessage: 'smtp;250 2.0.0 OK', DestinationServer: 'twin.local (127.0.0.1)', DestinationIP: '127.0.0.1' } });
+      await emitPostmarkWebhook(stream, 'Delivery', {
+        RecordType: 'Delivery', ServerID: DEFAULT_SERVER_ID, MessageStream: stream,
+        MessageID: messageId, Recipient: recipient, Tag: msg.Tag ?? '', DeliveredAt: at,
+        Details: 'smtp;250 2.0.0 OK', Metadata: msg.Metadata ?? {},
+      }, req);
+    } else if (kind === 'Opened') {
+      events.push({ Recipient: recipient, Type: 'Opened', ReceivedAt: at, Details: { Summary: 'Opened by the twin recipient' } });
+      await emitPostmarkWebhook(stream, 'Open', {
+        RecordType: 'Open', MessageStream: stream, FirstOpen: true, MessageID: messageId,
+        Recipient: recipient, Tag: msg.Tag ?? '', ReceivedAt: at, Platform: 'WebMail',
+        ReadSeconds: 5, UserAgent: 'postmark-twin', Client: client, OS: client, Geo: geo,
+        Metadata: msg.Metadata ?? {},
+      }, req);
+    } else if (kind === 'LinkClicked') {
+      events.push({ Recipient: recipient, Type: 'LinkClicked', ReceivedAt: at, Details: { Summary: 'Clicked by the twin recipient', Link: 'https://twin.test/link', ClickLocation: 'HTML' } });
+      await emitPostmarkWebhook(stream, 'Click', {
+        RecordType: 'Click', MessageStream: stream, MessageID: messageId, Recipient: recipient,
+        Tag: msg.Tag ?? '', ReceivedAt: at, ClickLocation: 'HTML', OriginalLink: 'https://twin.test/link',
+        Platform: 'Desktop', UserAgent: 'postmark-twin', Client: client, OS: client, Geo: geo,
+        Metadata: msg.Metadata ?? {},
+      }, req);
+    } else if (kind === 'Bounced' || kind === 'SpamComplaint') {
+      const isSpam = kind === 'SpamComplaint';
+      const bounceId = nextIntId('bounce', req.root);
+      const bounce = {
+        RecordType: 'Bounce',
+        ID: bounceId,
+        Type: isSpam ? 'SpamComplaint' : 'HardBounce',
+        TypeCode: isSpam ? 100001 : 1, // SDK: BounceTypeCode.SpamComplaint / .HardBounce
+        Name: isSpam ? 'Spam complaint' : 'Hard bounce',
+        Tag: msg.Tag ?? '',
+        MessageID: messageId,
+        ServerID: DEFAULT_SERVER_ID,
+        Description: isSpam
+          ? 'The subscriber explicitly marked this message as spam.'
+          : 'The server was unable to deliver your message (ex: unknown user, mailbox not found).',
+        Details: isSpam ? 'Test spam complaint' : 'Test bounce',
+        Email: recipient,
+        From: bareAddress(msg.From),
+        BouncedAt: at,
+        DumpAvailable: true,
+        Inactive: true,
+        CanActivate: !isSpam, // Postmark cannot reactivate a spam complaint (ErrorCode 1003)
+        Subject: String(msg.Subject ?? ''),
+        MessageStream: stream,
+      };
+      await writeResource('bounce', String(bounceId), bounce, 'bounce.record', req);
+      await suppress(stream, recipient, isSpam ? 'SpamComplaint' : 'HardBounce', 'Recipient', req);
+      events.push({ Recipient: recipient, Type: isSpam ? 'SpamComplaint' : 'Bounced', ReceivedAt: at, Details: { Summary: bounce.Description, BounceID: bounceId } });
+      await emitPostmarkWebhook(stream, isSpam ? 'SpamComplaint' : 'Bounce', { ...bounce, RecordType: isSpam ? 'SpamComplaint' : 'Bounce' }, req);
+    }
+  }
+  await writeResource('message', messageId, { MessageEvents: events, Status: plan.status }, 'message.deliver', req);
+}
+
+// ── stats ───────────────────────────────────────────────────────────────────────────
+function eventsOf(m: Record<string, unknown>): Array<Record<string, unknown>> {
+  return Array.isArray(m.MessageEvents) ? m.MessageEvents as Array<Record<string, unknown>> : [];
+}
+function messageEvents(m: Record<string, unknown>, type: string): number {
+  return eventsOf(m).filter((e) => e.Type === type).length;
+}
+function eventCount(root: string | undefined, type: string): number {
+  return rows('message', root).reduce((n, m) => n + messageEvents(m, type), 0);
+}
+
+/** `GET /stats/outbound` — computed from the SAME projected messages the Messages API serves. */
+function outboundStatistics(root?: string): Record<string, unknown> {
+  const msgs = rows('message', root);
+  const sent = msgs.length;
+  const bounced = eventCount(root, 'Bounced');
+  const spam = eventCount(root, 'SpamComplaint');
+  const opens = eventCount(root, 'Opened');
+  const clicks = eventCount(root, 'LinkClicked');
+  const withOpenTracking = msgs.filter((m) => m.TrackOpens === true).length;
+  const withLinkTracking = msgs.filter((m) => m.TrackLinks !== 'None').length;
+  const rate = (n: number) => (sent === 0 ? 0 : Number(((n / sent) * 100).toFixed(3)));
+  return {
+    Sent: sent,
+    Bounced: bounced,
+    SMTPApiErrors: 0,
+    BounceRate: rate(bounced),
+    SpamComplaints: spam,
+    SpamComplaintsRate: rate(spam),
+    Opens: opens,
+    UniqueOpens: msgs.filter((m) => messageEvents(m, 'Opened') > 0).length,
+    Tracked: withOpenTracking + withLinkTracking,
+    WithLinkTracking: withLinkTracking,
+    WithOpenTracking: withOpenTracking,
+    TotalTrackedLinksSent: withLinkTracking,
+    UniqueLinksClicked: msgs.filter((m) => messageEvents(m, 'LinkClicked') > 0).length,
+    TotalClicks: clicks,
+    WithClientRecorded: opens,
+    WithPlatformRecorded: opens,
+    WithReadTimeRecorded: opens,
+  };
+}
+
+/** The `{ Days: [{Date, …}], <totals> }` envelope every per-day stats endpoint returns. */
+function dayCounts(root: string | undefined, totals: Record<string, number>, perDay: (m: Record<string, unknown>) => Record<string, number>): Record<string, unknown> {
+  const byDay = new Map<string, Record<string, number>>();
+  for (const m of rows('message', root)) {
+    const day = String(m.ReceivedAt ?? '').slice(0, 10) || '1970-01-01';
+    const acc = byDay.get(day) ?? {};
+    for (const [k, v] of Object.entries(perDay(m))) acc[k] = (acc[k] ?? 0) + v;
+    byDay.set(day, acc);
+  }
+  const Days = [...byDay.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([date, counts]) => ({ Date: date, ...counts }));
+  return { Days, ...totals };
+}
+
+// ── tracking events (opens / clicks) ────────────────────────────────────────────────
+function trackingRows(root: string | undefined, type: 'Opened' | 'LinkClicked'): Array<Record<string, unknown>> {
+  const client = { Name: 'Twin Mail', Company: 'Volter', Family: 'Twin' };
+  const out: Array<Record<string, unknown>> = [];
+  for (const m of rows('message', root)) {
+    for (const e of eventsOf(m)) {
+      if (e.Type !== type) continue;
+      const base = {
+        MessageID: m.MessageID, MessageStream: m.MessageStream, Recipient: e.Recipient,
+        Tag: m.Tag ?? '', ReceivedAt: e.ReceivedAt, UserAgent: 'postmark-twin',
+        Client: client, OS: client, Geo: { CountryISOCode: 'US', Country: 'United States' },
+      };
+      out.push(type === 'Opened'
+        ? { RecordType: 'Open', ...base, Platform: 'WebMail', FirstOpen: true, ReadSeconds: 5 }
+        : { RecordType: 'Click', ...base, Platform: 'Desktop', ClickLocation: 'HTML', OriginalLink: 'https://twin.test/link' });
+    }
+  }
+  return out;
+}
+
+// ── pagination ──────────────────────────────────────────────────────────────────────
+function paginate<T>(items: T[], query: Record<string, string>): T[] {
+  const offset = Number(query.offset ?? '0') || 0;
+  const raw = Number(query.count ?? '');
+  const count = Number.isFinite(raw) && raw > 0 ? raw : items.length;
+  return items.slice(offset, offset + count);
+}
+
+// ── route handler ───────────────────────────────────────────────────────────────────
+/** Route families that authenticate with the ACCOUNT token rather than the server token. */
+const ACCOUNT_ROUTES = new Set(['servers', 'domains', 'senders', 'data-removals']);
+
+export async function handlePostmarkTwinRequest(req: PostmarkRequest): Promise<PostmarkResponse> {
+  const method = req.method.toUpperCase();
+  const rawPath = req.path.split('?');
+  const path = rawPath[0]!.replace(/\/+$/, '') || '/';
+  const query = Object.fromEntries(new URLSearchParams(rawPath[1] ?? ''));
+  const seg = path.replace(/^\/+/, '').split('/');
+  // Postmark's own SDK spells some route families in camelCase (`/deliveryStats`,
+  // `/triggers/inboundRules`, `/domains/:id/verifyDKIM`) while its docs spell them lower —
+  // the real API accepts both, so the twin routes on a CASE-FOLDED family segment. Only the
+  // literal route words are folded; resource IDS keep their case (see `idAt`).
+  const family = (seg[0] ?? '').toLowerCase();
+  const idAt = (i: number) => decodeURIComponent(seg[i] ?? '');
+
+  if (req.readOnly && method !== 'GET') {
+    return err('twin is read-only; omit readOnly to accept writes', 405, 405);
+  }
+
+  // `PUT /templates/push` is an ACCOUNT-token route living under the `templates` prefix.
+  const accountScoped = ACCOUNT_ROUTES.has(family) || (family === 'templates' && (seg[1] ?? '').toLowerCase() === 'push');
+  const auth = authError(req, accountScoped ? 'account' : 'server', family === 'email');
+  if (auth) return auth;
+
+  // Postmark answers a malformed JSON body with 422 `{ErrorCode: 402, Message:'Invalid JSON'}`
+  // [WIRE — note the vendor's message has no trailing period].
+  let parsed: unknown = {};
+  if (req.body) {
+    try {
+      parsed = JSON.parse(req.body);
+    } catch {
+      return fail(POSTMARK_ERRORS.invalidJson, 'Invalid JSON');
+    }
+  }
+  const body = asObject(parsed);
+
+  if (path === '/' || path === '') {
+    return { status: 200, body: { ErrorCode: 0, Message: 'OK', Service: 'postmark', Object: 'twin' } };
+  }
+
+  await bootstrap(req);
+
+  // ── twin-only seed routes (NOT vendor surface; never counted as coverage) ─────────
+  // Postmark's inbound surface is fed by MX-routed real mail, which a local twin cannot
+  // receive. `POST /_twin/inbound` is the twin's seam for putting an inbound message into
+  // state so the real `/messages/inbound*` reads have something faithful to serve. Kept
+  // under a `_twin/` prefix a real client never calls (ADDING_A_TWIN §6 seed-route rule).
+  if (family === '_twin' && seg[1] === 'inbound' && method === 'POST') {
+    const id = newMessageId('inbound_message', req);
+    const from = String(body.From ?? 'sender@twin.test');
+    const to = String(body.To ?? 'twin1inbound@inbound.postmarkapp.com');
+    const at = nowIso(req.occurredAt);
+    const rec = (v: string) => ({ Email: v, Name: '', MailboxHash: '' });
+    const m = await writeResource('inbound_message', id, {
+      MessageID: id, From: from, FromName: String(body.FromName ?? ''), FromFull: rec(from),
+      To: to, ToFull: [rec(to)], Cc: '', CcFull: [], Bcc: '', BccFull: [], ReplyTo: '',
+      OriginalRecipient: to, Subject: String(body.Subject ?? ''), Date: at,
+      MailboxHash: String(body.MailboxHash ?? ''), Tag: String(body.Tag ?? ''),
+      Status: 'Processed', Attachments: [], MessageStream: 'inbound',
+      TextBody: String(body.TextBody ?? ''), HtmlBody: String(body.HtmlBody ?? ''),
+      StrippedTextReply: '', Headers: [], BlockedReason: '',
+    }, 'inbound_message.receive', req);
+    // A message in state is only half of what MX-routed mail does on the real vendor: the
+    // other half is the POST to the server's `InboundHookUrl`. Without it a consumer can
+    // only find an arrival by polling, which is precisely the behavior an inbound webhook
+    // exists to replace, so the seed route drives both.
+    await emitPostmarkInboundHook(m, req);
+    return { status: 200, body: m };
+  }
+
+  // ── EMAIL ────────────────────────────────────────────────────────────────────────
+  if (family === 'email') {
+    if (seg.length === 1 && method === 'POST') {
+      const v = validateSend(body, false);
+      return v ?? sendOne(body, req);
+    }
+    if (seg.length === 2 && seg[1] === 'withTemplate' && method === 'POST') {
+      return sendWithTemplate(body, req);
+    }
+    // POST /email/batch — a bare ARRAY in, a bare ARRAY out. [WIRE] Postmark answers 200 with
+    // PER-MESSAGE results: a bad entry becomes an `{ErrorCode, Message}` element rather than
+    // failing the whole batch. Only the >500 cap is a top-level 422.
+    if (seg.length === 2 && seg[1] === 'batch' && method === 'POST') {
+      const list = Array.isArray(parsed) ? parsed : [];
+      if (list.length === 0) return fail(POSTMARK_ERRORS.invalidEmailRequest, 'Provide a non-empty array of messages.');
+      if (list.length > MAX_BATCH) return fail(POSTMARK_ERRORS.tooManyBatchMessages, `You may only send up to ${MAX_BATCH} messages in a single batched request.`);
+      const out: unknown[] = [];
+      for (const item of list) {
+        const p = asObject(item);
+        const v = validateSend(p, false);
+        out.push(v ? v.body : (await sendOne(p, req)).body);
+      }
+      return { status: 200, body: out };
+    }
+    // POST /email/batchWithTemplates — `{ Messages: [...] }` in, a bare array out.
+    if (seg.length === 2 && seg[1] === 'batchWithTemplates' && method === 'POST') {
+      const list = Array.isArray(body.Messages) ? body.Messages : [];
+      if (list.length === 0) return fail(POSTMARK_ERRORS.invalidEmailRequest, "Provide a non-empty 'Messages' array.");
+      if (list.length > MAX_BATCH) return fail(POSTMARK_ERRORS.tooManyBatchMessages, `You may only send up to ${MAX_BATCH} messages in a single batched request.`);
+      const out: unknown[] = [];
+      for (const item of list) out.push((await sendWithTemplate(asObject(item), req)).body);
+      return { status: 200, body: out };
+    }
+    // The Bulk API is approval-gated on a real account, and this twin does not model it, so
+    // the vendor's own refusal (ErrorCode 14) is the faithful answer — but ONLY on the two
+    // routes the vendor actually publishes. §9 caught the earlier `seg[1] === 'bulk'` guard
+    // answering 422 for EVERY verb under the subtree, which meant an unmodeled route there
+    // could never 404 and quietly contradicted the unmodeled-ops-fail-like-the-vendor rule.
+    if ((seg.length === 2 && seg[1] === 'bulk' && method === 'POST')
+      || (seg.length === 3 && seg[1] === 'bulk' && method === 'GET')) {
+      return fail(POSTMARK_ERRORS.bulkNotApproved, 'This endpoint requires approval to access. Contact support to use the Bulk API.');
+    }
+  }
+
+  // ── MESSAGES ─────────────────────────────────────────────────────────────────────
+  if (family === 'messages' && seg[1] === 'outbound') {
+    if (seg[2] === 'opens' && method === 'GET') {
+      let items = trackingRows(req.root, 'Opened');
+      if (seg.length === 4) items = items.filter((o) => o.MessageID === idAt(3));
+      if (query.recipient) items = items.filter((o) => String(o.Recipient).includes(query.recipient!));
+      if (query.tag) items = items.filter((o) => o.Tag === query.tag);
+      return { status: 200, body: { TotalCount: items.length, Opens: paginate(items, query) } };
+    }
+    if (seg[2] === 'clicks' && method === 'GET') {
+      let items = trackingRows(req.root, 'LinkClicked');
+      if (seg.length === 4) items = items.filter((c) => c.MessageID === idAt(3));
+      if (query.recipient) items = items.filter((c) => String(c.Recipient).includes(query.recipient!));
+      if (query.tag) items = items.filter((c) => c.Tag === query.tag);
+      return { status: 200, body: { TotalCount: items.length, Clicks: paginate(items, query) } };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('message', req.root).map(view).sort((a, b) => String(b.ReceivedAt ?? '').localeCompare(String(a.ReceivedAt ?? '')));
+      if (query.recipient) items = items.filter((m) => (m.Recipients as string[]).some((r) => r.includes(query.recipient!)));
+      if (query.fromEmail) items = items.filter((m) => bareAddress(m.From).includes(query.fromEmail!));
+      if (query.tag) items = items.filter((m) => m.Tag === query.tag);
+      if (query.subject) items = items.filter((m) => String(m.Subject ?? '').includes(query.subject!));
+      if (query.status) items = items.filter((m) => String(m.Status ?? '').toLowerCase() === query.status!.toLowerCase());
+      if (query.messageStream) items = items.filter((m) => m.MessageStream === query.messageStream);
+      return { status: 200, body: { TotalCount: items.length, Messages: paginate(items, query).map(outboundSummary) } };
+    }
+    if (seg.length === 4 && seg[3] === 'details' && method === 'GET') {
+      const m = getRow('message', idAt(2), req.root);
+      if (!m) return fail(POSTMARK_ERRORS.messageNotFound, 'This message was not found.');
+      const v = view(m);
+      return { status: 200, body: { ...outboundSummary(v), TextBody: v.TextBody, HtmlBody: v.HtmlBody, Body: renderRawBody(v), MessageEvents: v.MessageEvents ?? [] } };
+    }
+    if (seg.length === 4 && seg[3] === 'dump' && method === 'GET') {
+      const m = getRow('message', idAt(2), req.root);
+      if (!m) return fail(POSTMARK_ERRORS.messageNotFound, 'This message was not found.');
+      return { status: 200, body: { Body: renderRawBody(view(m)) } };
+    }
+  }
+  if (family === 'messages' && seg[1] === 'inbound') {
+    if (seg.length === 2 && method === 'GET') {
+      let items = rows('inbound_message', req.root).map(view).map(inboundSummary);
+      if (query.recipient) items = items.filter((m) => String(m.To ?? '').includes(query.recipient!));
+      if (query.fromEmail) items = items.filter((m) => String(m.From ?? '').includes(query.fromEmail!));
+      if (query.subject) items = items.filter((m) => String(m.Subject ?? '').includes(query.subject!));
+      if (query.mailboxHash) items = items.filter((m) => m.MailboxHash === query.mailboxHash);
+      if (query.status) items = items.filter((m) => String(m.Status ?? '').toLowerCase() === query.status!.toLowerCase());
+      return { status: 200, body: { TotalCount: items.length, InboundMessages: paginate(items, query) } };
+    }
+    if (seg.length === 4 && seg[3] === 'details' && method === 'GET') {
+      const m = getRow('inbound_message', idAt(2), req.root);
+      return m ? { status: 200, body: view(m) } : fail(POSTMARK_ERRORS.messageNotFound, 'This message was not found.');
+    }
+    if (seg.length === 4 && (seg[3] === 'bypass' || seg[3] === 'retry') && method === 'PUT') {
+      const m = getRow('inbound_message', idAt(2), req.root);
+      if (!m) return fail(POSTMARK_ERRORS.messageNotFound, 'This message was not found, or cannot be bypassed or retried.');
+      const bypass = seg[3] === 'bypass';
+      if (bypass && m.Status !== 'Blocked') return fail(POSTMARK_ERRORS.messageNotFound, 'This message was not found, or cannot be bypassed or retried.');
+      await writeResource('inbound_message', idAt(2), { Status: bypass ? 'Processed' : 'Queued', BlockedReason: '' }, bypass ? 'inbound_message.bypass' : 'inbound_message.retry', req);
+      return ack(bypass ? 'Successfully bypassed message.' : 'Successfully rescheduled failed message.');
+    }
+  }
+
+  // ── BOUNCES ──────────────────────────────────────────────────────────────────────
+  if (family === 'deliverystats' && seg.length === 1 && method === 'GET') {
+    const bounces = rows('bounce', req.root);
+    const byType = new Map<string, { Type: string; Name: string; Count: number }>();
+    for (const b of bounces) {
+      const key = String(b.Type);
+      const cur = byType.get(key) ?? { Type: key, Name: String(b.Name ?? key), Count: 0 };
+      cur.Count += 1;
+      byType.set(key, cur);
+    }
+    // The first element is the "All" total and — per the vendor — carries NO `Type` key.
+    return { status: 200, body: { InactiveMails: rows('suppression', req.root).length, Bounces: [{ Name: 'All', Count: bounces.length }, ...byType.values()] } };
+  }
+  if (family === 'bounces') {
+    if (seg.length === 1 && method === 'GET') {
+      let items = rows('bounce', req.root).map(view).sort((a, b) => Number(b.ID) - Number(a.ID));
+      if (query.type) items = items.filter((b) => b.Type === query.type);
+      if (query.emailFilter) items = items.filter((b) => String(b.Email ?? '').includes(query.emailFilter!));
+      if (query.inactive !== undefined) items = items.filter((b) => String(b.Inactive) === query.inactive);
+      if (query.messageID) items = items.filter((b) => b.MessageID === query.messageID);
+      if (query.tag) items = items.filter((b) => b.Tag === query.tag);
+      return { status: 200, body: { TotalCount: items.length, Bounces: paginate(items, query) } };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const b = getRow('bounce', idAt(1), req.root);
+      return b ? { status: 200, body: view(b) } : fail(POSTMARK_ERRORS.bounceNotFound, 'The bounce was not found.');
+    }
+    if (seg.length === 3 && seg[2] === 'dump' && method === 'GET') {
+      const b = getRow('bounce', idAt(1), req.root);
+      if (!b) return fail(POSTMARK_ERRORS.bounceNotFound, 'The bounce was not found, or its dump is no longer available.');
+      return { status: 200, body: { Body: `Return-Path: <>\r\nSubject: Undelivered Mail Returned to Sender\r\nTo: ${b.From}\r\n\r\n${b.Description}\r\n` } };
+    }
+    // PUT /bounces/:id/activate — reactivate a bounced (inactive) address.
+    if (seg.length === 3 && seg[2] === 'activate' && method === 'PUT') {
+      const b = getRow('bounce', idAt(1), req.root);
+      if (!b) return fail(POSTMARK_ERRORS.bounceNotFound, 'The bounce was not found.');
+      if (b.CanActivate !== true) return fail(POSTMARK_ERRORS.bounceCannotActivate, 'Due to the type of bounce, this address cannot be reactivated.');
+      await writeResource('bounce', idAt(1), { Inactive: false }, 'bounce.activate', req);
+      // Reactivating clears the suppression, so the address becomes sendable again.
+      const sid = suppressionId(String(b.MessageStream ?? 'outbound'), String(b.Email ?? ''));
+      if (getRow('suppression', sid, req.root)) await writeResource('suppression', sid, { deleted: true }, 'suppression.delete', req);
+      return { status: 200, body: { Message: 'OK', Bounce: view(getRow('bounce', idAt(1), req.root)!) } };
+    }
+  }
+
+  // ── TEMPLATES ────────────────────────────────────────────────────────────────────
+  if (family === 'templates') {
+    // `PUT /templates/push` is a REAL account-token route this twin does not model yet. It has
+    // to be intercepted BEFORE the `/templates/:idOrAlias` branch below, which would otherwise
+    // read "push" as a template alias and answer "template not found" — an unmodeled op
+    // failing with the WRONG error rather than like the vendor (§9 finding 7). 404 is the
+    // honest answer for a route the twin does not serve.
+    if (seg.length === 2 && seg[1]?.toLowerCase() === 'push') {
+      return err('Cannot PUT /templates/push — the template-push API is not modeled by this twin', 404, POSTMARK_ERRORS.invalidRequestField);
+    }
+    if (seg.length === 2 && seg[1] === 'validate' && method === 'POST') {
+      const section = (content: unknown) => ({
+        ContentIsValid: typeof content !== 'string' || !/\{\{[^}]*$/.test(content),
+        ValidationErrors: [],
+        RenderedContent: renderTemplate(content, asObject(body.TestRenderModel)),
+      });
+      const html = section(body.HtmlBody);
+      const text = section(body.TextBody);
+      const subject = section(body.Subject);
+      return {
+        status: 200,
+        body: {
+          AllContentIsValid: html.ContentIsValid && text.ContentIsValid && subject.ContentIsValid,
+          HtmlBody: html, TextBody: text, Subject: subject,
+          SuggestedTemplateModel: suggestedModel(body.HtmlBody, body.TextBody, body.Subject),
+        },
+      };
+    }
+    if (seg.length === 1 && method === 'GET') {
+      let items = rows('template', req.root).map(view).sort((a, b) => Number(a.TemplateId) - Number(b.TemplateId));
+      if (query.templateType) items = items.filter((t) => t.TemplateType === query.templateType);
+      if (query.layoutTemplate) items = items.filter((t) => t.LayoutTemplate === query.layoutTemplate);
+      const page = paginate(items, query).map((t) => ({
+        Active: t.Active, TemplateId: t.TemplateId, Name: t.Name, Alias: t.Alias,
+        TemplateType: t.TemplateType, LayoutTemplate: t.LayoutTemplate,
+      }));
+      return { status: 200, body: { TotalCount: items.length, Templates: page } };
+    }
+    if (seg.length === 1 && method === 'POST') {
+      if (typeof body.Name !== 'string' || body.Name === '') return fail(POSTMARK_ERRORS.templateNoData, 'A template Name is required.');
+      const templateType = body.TemplateType === 'Layout' ? 'Layout' : 'Standard';
+      const alias = typeof body.Alias === 'string' && body.Alias !== '' ? body.Alias : null;
+      if (alias && rows('template', req.root).some((t) => t.Alias === alias)) {
+        // ⚠ doc-unverified CODE: the published table has no alias-conflict entry, so the
+        // refusal is right but the number is borrowed. The verify pins the 422 + message, not
+        // the code (§9).
+        return fail(POSTMARK_ERRORS.templateNotFound, `A template with the alias '${alias}' already exists on this server.`);
+      }
+      const id = nextIntId('template', req.root);
+      await writeResource('template', String(id), {
+        TemplateId: id, Name: body.Name, Alias: alias, TemplateType: templateType,
+        Subject: typeof body.Subject === 'string' ? body.Subject : '',
+        HtmlBody: typeof body.HtmlBody === 'string' ? body.HtmlBody : null,
+        TextBody: typeof body.TextBody === 'string' ? body.TextBody : null,
+        LayoutTemplate: typeof body.LayoutTemplate === 'string' ? body.LayoutTemplate : null,
+        Active: true, AssociatedServerId: DEFAULT_SERVER_ID,
+      }, 'template.create', req);
+      // The create/edit response is the SHORT template shape (no bodies) — SDK: TemplateInList.
+      return { status: 200, body: { TemplateId: id, Name: body.Name, Active: true, Alias: alias, TemplateType: templateType, LayoutTemplate: typeof body.LayoutTemplate === 'string' ? body.LayoutTemplate : null } };
+    }
+    if (seg.length === 2) {
+      const t = resolveTemplate(idAt(1), req.root);
+      const missing = fail(POSTMARK_ERRORS.templateNotFound, 'The template associated with this request was not found.');
+      if (method === 'GET') return t ? { status: 200, body: view(t) } : missing;
+      if (method === 'PUT') {
+        if (!t) return missing;
+        const patch: Record<string, unknown> = {};
+        for (const k of ['Name', 'Subject', 'HtmlBody', 'TextBody', 'Alias', 'LayoutTemplate']) if (k in body) patch[k] = body[k];
+        if (Object.keys(patch).length === 0) return fail(POSTMARK_ERRORS.templateNoData, 'No template data received.');
+        if (typeof patch.Alias === 'string' && rows('template', req.root).some((o) => o.Alias === patch.Alias && String(o.TemplateId) !== String(t.TemplateId))) {
+          return fail(POSTMARK_ERRORS.templateNotFound, `A template with the alias '${patch.Alias}' already exists on this server.`);
+        }
+        await writeResource('template', String(t.TemplateId), patch, 'template.update', req);
+        const after = getRow('template', String(t.TemplateId), req.root)!;
+        return { status: 200, body: { TemplateId: after.TemplateId, Name: after.Name, Active: after.Active, Alias: after.Alias, TemplateType: after.TemplateType, LayoutTemplate: after.LayoutTemplate } };
+      }
+      if (method === 'DELETE') {
+        if (!t) return missing;
+        await writeResource('template', String(t.TemplateId), { deleted: true }, 'template.delete', req);
+        return ack('Template deleted.');
+      }
+    }
+  }
+
+  // ── MESSAGE STREAMS (+ suppressions, which are nested under a stream) ─────────────
+  if (family === 'message-streams') {
+    if (seg.length >= 3 && seg[2] === 'suppressions') return suppressionsRoute(seg, method, body, query, req);
+    if (seg.length === 1 && method === 'GET') {
+      let items = rows('message_stream', req.root).map(view);
+      if (String(query.includeArchivedStreams ?? '') !== 'true') items = items.filter((s) => s.ArchivedAt == null);
+      if (query.messageStreamType && query.messageStreamType !== 'All') items = items.filter((s) => s.MessageStreamType === query.messageStreamType);
+      // NB: this is the one list endpoint where the vendor puts TotalCount LAST.
+      return { status: 200, body: { MessageStreams: items, TotalCount: items.length } };
+    }
+    if (seg.length === 1 && method === 'POST') {
+      const id = typeof body.ID === 'string' ? body.ID.trim() : '';
+      if (id === '' || !/^[A-Za-z][A-Za-z0-9-]{0,29}$/.test(id)) {
+        return fail(POSTMARK_ERRORS.streamIdInvalid, 'The ID must be a non-empty string starting with a letter, up to 30 characters.');
+      }
+      if (/^pm-/i.test(id)) return fail(POSTMARK_ERRORS.streamIdReservedPrefix, 'The ID must not start with the pm- prefix.');
+      if (allRows('message_stream', req.root).some((s) => s.id === id)) {
+        return fail(POSTMARK_ERRORS.streamIdExists, 'The ID provided already exists for this server.');
+      }
+      const type = body.MessageStreamType;
+      if (type !== 'Transactional' && type !== 'Broadcast' && type !== 'Inbound') {
+        return fail(POSTMARK_ERRORS.streamTypeInvalid, 'The MessageStreamType associated with this request was invalid.');
+      }
+      if (typeof body.Name !== 'string' || body.Name.trim() === '') {
+        return fail(POSTMARK_ERRORS.streamNameRequired, 'A valid Name must be provided.');
+      }
+      const s = await writeResource('message_stream', id, {
+        ID: id, ServerID: DEFAULT_SERVER_ID, Name: body.Name,
+        Description: typeof body.Description === 'string' ? body.Description : '',
+        MessageStreamType: type, CreatedAt: nowIso(req.occurredAt), UpdatedAt: null, ArchivedAt: null,
+        SubscriptionManagementConfiguration: asObject(body.SubscriptionManagementConfiguration).UnsubscribeHandlingType
+          ? asObject(body.SubscriptionManagementConfiguration)
+          : { UnsubscribeHandlingType: type === 'Broadcast' ? 'Postmark' : 'None' },
+      }, 'message_stream.create', req);
+      return { status: 200, body: s };
+    }
+    const streamMissing = fail(POSTMARK_ERRORS.streamNotFound, 'The message stream for the provided ID was not found.');
+    if (seg.length === 2 && method === 'GET') {
+      const s = getRow('message_stream', idAt(1), req.root);
+      return s ? { status: 200, body: view(s) } : streamMissing;
+    }
+    if (seg.length === 2 && method === 'PATCH') {
+      const s = getRow('message_stream', idAt(1), req.root);
+      if (!s) return streamMissing;
+      const patch: Record<string, unknown> = {};
+      for (const k of ['Name', 'Description', 'SubscriptionManagementConfiguration']) if (k in body) patch[k] = body[k];
+      if (Object.keys(patch).length === 0) return fail(POSTMARK_ERRORS.streamNameRequired, 'A valid Name must be provided.');
+      patch.UpdatedAt = nowIso(req.occurredAt);
+      await writeResource('message_stream', idAt(1), patch, 'message_stream.update', req);
+      return { status: 200, body: view(getRow('message_stream', idAt(1), req.root)!) };
+    }
+    if (seg.length === 3 && seg[2] === 'archive' && method === 'POST') {
+      const s = getRow('message_stream', idAt(1), req.root);
+      if (!s) return streamMissing;
+      if (UNARCHIVABLE_STREAMS.has(idAt(1))) return fail(POSTMARK_ERRORS.streamCannotArchiveDefault, 'You cannot archive the default transactional and inbound streams.');
+      if (s.ArchivedAt != null) return fail(POSTMARK_ERRORS.streamCannotArchive, 'Stream is unable to be archived at this time.');
+      const purge = new Date(Date.parse(nowIso(req.occurredAt)) + 45 * 24 * 3600 * 1000).toISOString();
+      await writeResource('message_stream', idAt(1), { ArchivedAt: nowIso(req.occurredAt), ExpectedPurgeDate: purge }, 'message_stream.archive', req);
+      return { status: 200, body: { ID: idAt(1), ServerID: DEFAULT_SERVER_ID, ExpectedPurgeDate: purge } };
+    }
+    if (seg.length === 3 && seg[2] === 'unarchive' && method === 'POST') {
+      const s = getRow('message_stream', idAt(1), req.root);
+      if (!s) return streamMissing;
+      // ⚠ doc-unverified CODE: the published table has no entry for "unarchive a stream that
+      // was never archived" (1232 is the too-old-to-unarchive case). The 422 refusal is the
+      // right shape — a no-op success would be a fake success — but the NUMBER is a guess, so
+      // the capability verify deliberately does NOT pin it (§9).
+      if (s.ArchivedAt == null) return fail(POSTMARK_ERRORS.streamCannotUnarchive, 'This message stream is not archived.');
+      await writeResource('message_stream', idAt(1), { ArchivedAt: null, ExpectedPurgeDate: null }, 'message_stream.unarchive', req);
+      return { status: 200, body: view(getRow('message_stream', idAt(1), req.root)!) };
+    }
+  }
+
+  // ── WEBHOOKS ─────────────────────────────────────────────────────────────────────
+  if (family === 'webhooks') {
+    const webhookMissing = fail(POSTMARK_ERRORS.webhookNotFound, 'The webhook for the provided ID was not found.');
+    if (seg.length === 1 && method === 'GET') {
+      let items = rows('webhook', req.root).map(view);
+      if (query.MessageStream) items = items.filter((w) => w.MessageStream === query.MessageStream);
+      // NB: the webhooks list is the one collection with NO TotalCount.
+      return { status: 200, body: { Webhooks: items } };
+    }
+    if (seg.length === 1 && method === 'POST') {
+      if (typeof body.Url !== 'string' || body.Url === '') return fail(POSTMARK_ERRORS.webhookUrlRequired, 'The request must contain a valid Url field.');
+      const stream = typeof body.MessageStream === 'string' && body.MessageStream !== '' ? body.MessageStream : 'outbound';
+      const s = getRow('message_stream', stream, req.root);
+      if (!s) return fail(POSTMARK_ERRORS.streamNotFound, 'The message stream for the provided ID was not found.');
+      if (s.ArchivedAt != null) return fail(POSTMARK_ERRORS.webhookArchivedStream, 'You cannot create a webhook using an archived MessageStream.');
+      const id = nextIntId('webhook', req.root);
+      const w = await writeResource('webhook', String(id), {
+        ID: id, Url: body.Url, MessageStream: stream,
+        HttpAuth: asObject(body.HttpAuth).Username ? asObject(body.HttpAuth) : null,
+        HttpHeaders: Array.isArray(body.HttpHeaders) ? body.HttpHeaders : [],
+        Triggers: normalizeTriggers(body.Triggers),
+      }, 'webhook.create', req);
+      return { status: 200, body: w };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const w = getRow('webhook', idAt(1), req.root);
+      return w ? { status: 200, body: view(w) } : webhookMissing;
+    }
+    if (seg.length === 2 && method === 'PUT') {
+      const w = getRow('webhook', idAt(1), req.root);
+      if (!w) return webhookMissing;
+      const patch: Record<string, unknown> = {};
+      if (typeof body.Url === 'string') patch.Url = body.Url;
+      if ('HttpAuth' in body) patch.HttpAuth = asObject(body.HttpAuth).Username ? asObject(body.HttpAuth) : null;
+      if (Array.isArray(body.HttpHeaders)) patch.HttpHeaders = body.HttpHeaders;
+      if ('Triggers' in body) patch.Triggers = normalizeTriggers(body.Triggers);
+      await writeResource('webhook', idAt(1), patch, 'webhook.update', req);
+      return { status: 200, body: view(getRow('webhook', idAt(1), req.root)!) };
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      if (!getRow('webhook', idAt(1), req.root)) return webhookMissing;
+      await writeResource('webhook', idAt(1), { deleted: true }, 'webhook.delete', req);
+      return ack('Webhook deleted.');
+    }
+  }
+
+  // ── SERVER (the server-token's own server) ───────────────────────────────────────
+  if (family === 'server' && seg.length === 1) {
+    const s = getRow('server', String(DEFAULT_SERVER_ID), req.root);
+    if (!s) return fail(POSTMARK_ERRORS.serverNotFound, 'This server was not found.');
+    if (method === 'GET') return { status: 200, body: view(s) };
+    if (method === 'PUT') {
+      const patch = pickServerFields(body);
+      if (Object.keys(patch).length === 0) return fail(POSTMARK_ERRORS.serverNoData, 'No server data received.');
+      await writeResource('server', String(DEFAULT_SERVER_ID), patch, 'server.update', req);
+      return { status: 200, body: view(getRow('server', String(DEFAULT_SERVER_ID), req.root)!) };
+    }
+  }
+
+  // ── SERVERS (account token) ──────────────────────────────────────────────────────
+  if (family === 'servers') {
+    const serverMissing = fail(POSTMARK_ERRORS.serverNotFound, 'This server was not found.');
+    if (seg.length === 1 && method === 'GET') {
+      let items = rows('server', req.root).map(view);
+      if (query.name) items = items.filter((s) => String(s.Name ?? '').includes(query.name!));
+      return { status: 200, body: { TotalCount: items.length, Servers: paginate(items, query) } };
+    }
+    if (seg.length === 1 && method === 'POST') {
+      if (typeof body.Name !== 'string' || body.Name.trim() === '') return fail(POSTMARK_ERRORS.serverNameInvalid, 'Server name is invalid or missing.');
+      if (rows('server', req.root).some((s) => s.Name === body.Name)) return fail(POSTMARK_ERRORS.serverNameExists, 'This server name already exists.');
+      if (typeof body.InboundDomain === 'string' && body.InboundDomain !== '' && rows('server', req.root).some((s) => s.InboundDomain === body.InboundDomain)) {
+        return fail(POSTMARK_ERRORS.serverInboundDomainInUse, 'The specified inbound domain is already registered or in use on another server.');
+      }
+      const id = nextIntId('server', req.root);
+      const s = await writeResource('server', String(id), serverRecord(id, body.Name, body), 'server.create', req);
+      return { status: 200, body: s };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const s = getRow('server', idAt(1), req.root);
+      return s ? { status: 200, body: view(s) } : serverMissing;
+    }
+    if (seg.length === 2 && method === 'PUT') {
+      if (!getRow('server', idAt(1), req.root)) return serverMissing;
+      const patch = pickServerFields(body);
+      if (Object.keys(patch).length === 0) return fail(POSTMARK_ERRORS.serverNoData, 'No server data received.');
+      await writeResource('server', idAt(1), patch, 'server.update', req);
+      return { status: 200, body: view(getRow('server', idAt(1), req.root)!) };
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      if (!getRow('server', idAt(1), req.root)) return serverMissing;
+      await writeResource('server', idAt(1), { deleted: true }, 'server.delete', req);
+      return ack('Server deleted.');
+    }
+  }
+
+  // ── STATS ────────────────────────────────────────────────────────────────────────
+  if (family === 'stats' && seg[1] === 'outbound' && method === 'GET') {
+    const root = req.root;
+    if (seg.length === 2) return { status: 200, body: outboundStatistics(root) };
+    const leaf = seg.slice(2).join('/').toLowerCase();
+    const opens = eventCount(root, 'Opened');
+    const clicks = eventCount(root, 'LinkClicked');
+    if (leaf === 'sends') return { status: 200, body: dayCounts(root, { Sent: rows('message', root).length }, () => ({ Sent: 1 })) };
+    if (leaf === 'bounces') return { status: 200, body: dayCounts(root, { HardBounce: eventCount(root, 'Bounced') }, (m) => ({ HardBounce: messageEvents(m, 'Bounced') })) };
+    if (leaf === 'spam') return { status: 200, body: dayCounts(root, { SpamComplaint: eventCount(root, 'SpamComplaint') }, (m) => ({ SpamComplaint: messageEvents(m, 'SpamComplaint') })) };
+    if (leaf === 'tracked') return { status: 200, body: dayCounts(root, { Tracked: rows('message', root).filter((m) => m.TrackOpens === true).length }, (m) => ({ Tracked: m.TrackOpens === true ? 1 : 0 })) };
+    if (leaf === 'opens') return { status: 200, body: dayCounts(root, { Opens: opens, Unique: opens }, (m) => ({ Opens: messageEvents(m, 'Opened'), Unique: messageEvents(m, 'Opened') })) };
+    if (leaf === 'opens/platforms') return { status: 200, body: dayCounts(root, { WebMail: opens, Desktop: 0, Mobile: 0, Unknown: 0 }, (m) => ({ WebMail: messageEvents(m, 'Opened') })) };
+    if (leaf === 'opens/emailclients') return { status: 200, body: dayCounts(root, { 'Twin Mail': opens }, (m) => ({ 'Twin Mail': messageEvents(m, 'Opened') })) };
+    if (leaf === 'opens/readtimes') return { status: 200, body: dayCounts(root, { '7s+': opens }, (m) => ({ '7s+': messageEvents(m, 'Opened') })) };
+    if (leaf === 'clicks') return { status: 200, body: dayCounts(root, { Clicks: clicks, Unique: clicks }, (m) => ({ Clicks: messageEvents(m, 'LinkClicked'), Unique: messageEvents(m, 'LinkClicked') })) };
+    if (leaf === 'clicks/browserfamilies') return { status: 200, body: dayCounts(root, { 'Twin Browser': clicks }, (m) => ({ 'Twin Browser': messageEvents(m, 'LinkClicked') })) };
+    if (leaf === 'clicks/platforms') return { status: 200, body: dayCounts(root, { Desktop: clicks, Mobile: 0, Unknown: 0 }, (m) => ({ Desktop: messageEvents(m, 'LinkClicked') })) };
+    if (leaf === 'clicks/location') return { status: 200, body: dayCounts(root, { HTML: clicks, Text: 0 }, (m) => ({ HTML: messageEvents(m, 'LinkClicked'), Text: 0 })) };
+  }
+
+  // ── INBOUND RULE TRIGGERS ────────────────────────────────────────────────────────
+  if (family === 'triggers' && seg[1]?.toLowerCase() === 'inboundrules') {
+    if (seg.length === 2 && method === 'GET') {
+      const items = rows('inbound_rule', req.root).map(view);
+      return { status: 200, body: { TotalCount: items.length, InboundRules: paginate(items, query) } };
+    }
+    if (seg.length === 2 && method === 'POST') {
+      if (typeof body.Rule !== 'string' || body.Rule.trim() === '') return fail(POSTMARK_ERRORS.inboundRuleNoData, 'No trigger data received.');
+      if (rows('inbound_rule', req.root).some((r) => r.Rule === body.Rule)) return fail(POSTMARK_ERRORS.inboundRuleExists, 'This inbound rule already exists.');
+      const id = nextIntId('inbound_rule', req.root);
+      const r = await writeResource('inbound_rule', String(id), { ID: id, Rule: body.Rule }, 'inbound_rule.create', req);
+      return { status: 200, body: r };
+    }
+    if (seg.length === 3 && method === 'DELETE') {
+      if (!getRow('inbound_rule', idAt(2), req.root)) return fail(POSTMARK_ERRORS.inboundRuleNotFound, 'This inbound rule was not found.');
+      await writeResource('inbound_rule', idAt(2), { deleted: true }, 'inbound_rule.delete', req);
+      return ack('Inbound rule removed.');
+    }
+  }
+
+  // ── DOMAINS (account token) ──────────────────────────────────────────────────────
+  if (family === 'domains') {
+    const domainMissing = fail(POSTMARK_ERRORS.domainNotFound, 'This domain was not found.');
+    if (seg.length === 1 && method === 'GET') {
+      const items = rows('domain', req.root).map(view).map(domainSummary);
+      return { status: 200, body: { TotalCount: items.length, Domains: paginate(items, query) } };
+    }
+    if (seg.length === 1 && method === 'POST') {
+      if (typeof body.Name !== 'string' || body.Name === '') return fail(POSTMARK_ERRORS.domainNameRequired, 'Name is a required field to create a Domain.');
+      if (rows('domain', req.root).some((d) => d.Name === body.Name)) return fail(POSTMARK_ERRORS.domainExists, 'Domain already exists.');
+      const id = nextIntId('domain', req.root);
+      const d = await writeResource('domain', String(id), domainRecord(id, body.Name, typeof body.ReturnPathDomain === 'string' ? body.ReturnPathDomain : ''), 'domain.create', req);
+      return { status: 200, body: d };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const d = getRow('domain', idAt(1), req.root);
+      return d ? { status: 200, body: view(d) } : domainMissing;
+    }
+    if (seg.length === 2 && method === 'PUT') {
+      if (!getRow('domain', idAt(1), req.root)) return domainMissing;
+      if (typeof body.ReturnPathDomain !== 'string') return fail(POSTMARK_ERRORS.invalidEmailValue, 'A valid ReturnPathDomain must be provided.');
+      await writeResource('domain', idAt(1), { ReturnPathDomain: body.ReturnPathDomain, ReturnPathDomainVerified: false }, 'domain.update', req);
+      return { status: 200, body: view(getRow('domain', idAt(1), req.root)!) };
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      if (!getRow('domain', idAt(1), req.root)) return domainMissing;
+      await writeResource('domain', idAt(1), { deleted: true }, 'domain.delete', req);
+      return ack('Domain deleted.');
+    }
+    if (seg.length === 3) {
+      const d = getRow('domain', idAt(1), req.root);
+      if (!d) return domainMissing;
+      const verb = seg[2]!.toLowerCase();
+      const after = async () => ({ status: 200, body: view(getRow('domain', idAt(1), req.root)!) });
+      if (verb === 'verifydkim' && method === 'PUT') {
+        await writeResource('domain', idAt(1), { DKIMVerified: true, WeakDKIM: false, DKIMUpdateStatus: 'Verified', DKIMPendingHost: '', DKIMPendingTextValue: '' }, 'domain.verify_dkim', req);
+        return after();
+      }
+      if (verb === 'verifyreturnpath' && method === 'PUT') {
+        // ⚠ doc-unverified RULE (§9): nothing in the SDK or the published docs states that a
+        // ReturnPathDomain must be set before it can be verified — this is the TWIN's own
+        // precondition, chosen because reporting `ReturnPathDomainVerified: true` for a domain
+        // that has no return path configured would be a fake success. The code is borrowed
+        // too, so the capability verify asserts only the 422, not the number.
+        if (!d.ReturnPathDomain) return fail(POSTMARK_ERRORS.invalidEmailValue, 'Set a ReturnPathDomain before verifying it.');
+        await writeResource('domain', idAt(1), { ReturnPathDomainVerified: true }, 'domain.verify_return_path', req);
+        return after();
+      }
+      if (verb === 'verifyspf' && method === 'POST') {
+        await writeResource('domain', idAt(1), { SPFVerified: true }, 'domain.verify_spf', req);
+        return after();
+      }
+      if (verb === 'rotatedkim' && method === 'POST') {
+        const selector = `twin${String(d.ID)}rot`;
+        await writeResource('domain', idAt(1), {
+          DKIMPendingHost: `${selector}._domainkey.${String(d.Name)}`,
+          DKIMPendingTextValue: `k=rsa;p=TWIN${selector.toUpperCase()}`,
+          DKIMUpdateStatus: 'Pending', DKIMVerified: false,
+        }, 'domain.rotate_dkim', req);
+        return after();
+      }
+    }
+  }
+
+  // ── SENDER SIGNATURES (account token) ────────────────────────────────────────────
+  if (family === 'senders') {
+    const sigMissing = fail(POSTMARK_ERRORS.signatureNotFound, 'This signature was not found.');
+    if (seg.length === 1 && method === 'GET') {
+      // NB: the array key is `SenderSignatures`, not `Senders`, despite the path.
+      const items = rows('sender_signature', req.root).map(view).map((s) => ({
+        Domain: s.Domain, EmailAddress: s.EmailAddress, ReplyToEmailAddress: s.ReplyToEmailAddress,
+        Name: s.Name, Confirmed: s.Confirmed, ID: s.ID,
+      }));
+      return { status: 200, body: { TotalCount: items.length, SenderSignatures: paginate(items, query) } };
+    }
+    if (seg.length === 1 && method === 'POST') {
+      if (typeof body.FromEmail !== 'string' || body.FromEmail === '') return fail(POSTMARK_ERRORS.fromEmailRequired, 'FromEmail is a required field to create a Sender Signature.');
+      if (!looksLikeEmail(body.FromEmail)) return fail(POSTMARK_ERRORS.invalidEmailValue, 'The value provided is not a valid email address.');
+      const domain = body.FromEmail.split('@')[1]!.toLowerCase();
+      if (PUBLIC_DOMAINS.has(domain)) return fail(POSTMARK_ERRORS.publicDomainSignature, "You can't use public domain emails or public domains.");
+      if (rows('sender_signature', req.root).some((s) => s.EmailAddress === body.FromEmail)) {
+        return fail(POSTMARK_ERRORS.signatureExists, 'This signature already exists, or a similar signature already exists.');
+      }
+      const id = nextIntId('sender_signature', req.root);
+      const s = await writeResource('sender_signature', String(id), signatureRecord(id, body.FromEmail, body), 'sender_signature.create', req);
+      return { status: 200, body: s };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const s = getRow('sender_signature', idAt(1), req.root);
+      return s ? { status: 200, body: view(s) } : sigMissing;
+    }
+    if (seg.length === 2 && method === 'PUT') {
+      if (!getRow('sender_signature', idAt(1), req.root)) return sigMissing;
+      const patch: Record<string, unknown> = {};
+      if (typeof body.Name === 'string') patch.Name = body.Name;
+      if (typeof body.ReplyToEmail === 'string') patch.ReplyToEmailAddress = body.ReplyToEmail;
+      if (typeof body.ReturnPathDomain === 'string') patch.ReturnPathDomain = body.ReturnPathDomain;
+      if (typeof body.ConfirmationPersonalNote === 'string') patch.ConfirmationPersonalNote = body.ConfirmationPersonalNote;
+      if (Object.keys(patch).length === 0) return fail(POSTMARK_ERRORS.signatureNoData, 'No update data or signature data received.');
+      await writeResource('sender_signature', idAt(1), patch, 'sender_signature.update', req);
+      return { status: 200, body: view(getRow('sender_signature', idAt(1), req.root)!) };
+    }
+    if (seg.length === 2 && method === 'DELETE') {
+      if (!getRow('sender_signature', idAt(1), req.root)) return sigMissing;
+      await writeResource('sender_signature', idAt(1), { deleted: true }, 'sender_signature.delete', req);
+      return ack('Signature deleted.');
+    }
+    if (seg.length === 3 && method === 'POST') {
+      const s = getRow('sender_signature', idAt(1), req.root);
+      if (!s) return sigMissing;
+      const verb = seg[2]!.toLowerCase();
+      if (verb === 'resend') return ack('Confirmation email for the sender signature was re-sent.');
+      if (verb === 'verifyspf') {
+        await writeResource('sender_signature', idAt(1), { SPFVerified: true }, 'sender_signature.verify_spf', req);
+        return { status: 200, body: view(getRow('sender_signature', idAt(1), req.root)!) };
+      }
+      if (verb === 'requestnewdkim') {
+        await writeResource('sender_signature', idAt(1), { DKIMUpdateStatus: 'Pending', DKIMPendingHost: `twinrot._domainkey.${String(s.Domain)}` }, 'sender_signature.request_dkim', req);
+        return ack('New DKIM has been requested for this signature.');
+      }
+    }
+  }
+
+  // ── DATA REMOVALS (account token, GDPR) ──────────────────────────────────────────
+  if (family === 'data-removals') {
+    if (seg.length === 1 && method === 'POST') {
+      const by = String(body.RequestedBy ?? '');
+      const forWhom = String(body.RequestedFor ?? '');
+      if (!looksLikeEmail(by) || !looksLikeEmail(forWhom)) {
+        return fail(POSTMARK_ERRORS.invalidEmailValue, "Provide a valid 'RequestedBy' and 'RequestedFor' email address.");
+      }
+      const id = nextIntId('data_removal', req.root);
+      await writeResource('data_removal', String(id), {
+        ID: id, Status: 'Pending', RequestedBy: by, RequestedFor: forWhom,
+        NotifyWhenCompleted: body.NotifyWhenCompleted === true,
+      }, 'data_removal.create', req);
+      return { status: 200, body: { ID: id, Status: 'Pending' } };
+    }
+    if (seg.length === 2 && method === 'GET') {
+      const d = getRow('data_removal', idAt(1), req.root);
+      if (!d) return fail(POSTMARK_ERRORS.dataRemovalIdInvalid, 'Missing or incorrect data removal request ID.');
+      return { status: 200, body: { ID: d.ID, Status: d.Status } };
+    }
+  }
+
+  // An unmodeled ROUTE fails like the vendor's 404 — never a fake success.
+  // ⚠ doc-unverified: the vendor's body for a completely unrouted path is not published; the
+  // twin keeps its own `{ErrorCode, Message}` envelope so a caller sees a Postmark-shaped error.
+  return err(`Cannot ${method} ${path}`, 404, POSTMARK_ERRORS.invalidRequestField);
+}
+
+// ── route helpers ───────────────────────────────────────────────────────────────────
+/** POST /email/withTemplate + each entry of POST /email/batchWithTemplates. */
+async function sendWithTemplate(p: Record<string, unknown>, req: PostmarkRequest): Promise<PostmarkResponse> {
+  const v = validateSend(p, true);
+  if (v) return v;
+  if (p.TemplateId === undefined && p.TemplateAlias === undefined) {
+    return fail(POSTMARK_ERRORS.templateNotFound, 'The request specifies neither TemplateId nor TemplateAlias.');
+  }
+  const t = resolveTemplate(p.TemplateId !== undefined ? p.TemplateId : p.TemplateAlias, req.root);
+  if (!t) return fail(POSTMARK_ERRORS.templateNotFound, 'The template associated with this request was not found.');
+  const model = asObject(p.TemplateModel);
+  return sendOne({
+    ...p,
+    Subject: renderTemplate(t.Subject, model),
+    HtmlBody: t.HtmlBody == null ? undefined : renderTemplate(t.HtmlBody, model),
+    TextBody: t.TextBody == null ? undefined : renderTemplate(t.TextBody, model),
+  }, req);
+}
+
+/** The list-shape of an outbound message (no body, no MessageEvents) — SDK: OutboundMessage. */
+function outboundSummary(m: Record<string, unknown>): Record<string, unknown> {
+  return {
+    MessageID: m.MessageID, Tag: m.Tag, To: m.To, Cc: m.Cc, Bcc: m.Bcc,
+    Recipients: m.Recipients, ReceivedAt: m.ReceivedAt, From: m.From, Subject: m.Subject,
+    Attachments: m.Attachments, Status: m.Status, TrackOpens: m.TrackOpens,
+    TrackLinks: m.TrackLinks, Metadata: m.Metadata, MessageStream: m.MessageStream,
+    Sandboxed: m.Sandboxed,
+  };
+}
+/** The list-shape of an inbound message (no bodies/headers) — SDK: InboundMessage. */
+function inboundSummary(m: Record<string, unknown>): Record<string, unknown> {
+  const { TextBody: _t, HtmlBody: _h, StrippedTextReply: _s, Headers: _hd, BlockedReason: _b, ...rest } = m;
+  return rest;
+}
+
+/** The raw RFC-822-ish source Postmark returns from `/dump` and in `details.Body`. */
+function renderRawBody(m: Record<string, unknown>): string {
+  const to = (m.Recipients as string[] | undefined)?.join(', ') ?? '';
+  const body = (m.HtmlBody as string | null) ?? (m.TextBody as string | null) ?? '';
+  return `From: ${m.From}\r\nTo: ${to}\r\nSubject: ${m.Subject}\r\nX-PM-Message-Id: ${m.MessageID}\r\n\r\n${body}`;
+}
+
+/** Fill Postmark's Triggers block, defaulting every trigger the caller omitted. */
+function normalizeTriggers(raw: unknown): Record<string, unknown> {
+  const t = asObject(raw);
+  const flag = (k: string) => ({ Enabled: asObject(t[k]).Enabled === true });
+  return {
+    Open: { ...flag('Open'), PostFirstOpenOnly: asObject(t.Open).PostFirstOpenOnly === true },
+    Click: flag('Click'),
+    Delivery: flag('Delivery'),
+    Bounce: { ...flag('Bounce'), IncludeContent: asObject(t.Bounce).IncludeContent === true },
+    SpamComplaint: { ...flag('SpamComplaint'), IncludeContent: asObject(t.SpamComplaint).IncludeContent === true },
+    SubscriptionChange: flag('SubscriptionChange'),
+  };
+}
+
+const SERVER_FIELDS = [
+  'Name', 'Color', 'SmtpApiActivated', 'RawEmailEnabled', 'InboundHookUrl', 'BounceHookUrl',
+  'OpenHookUrl', 'DeliveryHookUrl', 'ClickHookUrl', 'PostFirstOpenOnly', 'InboundSpamThreshold',
+  'TrackOpens', 'TrackLinks', 'IncludeBounceContentInHook', 'EnableSmtpApiErrorHooks',
+  'InboundDomain', 'DeliveryType',
+];
+function pickServerFields(body: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of SERVER_FIELDS) if (k in body) out[k] = body[k];
+  return out;
+}
+
+/** Postmark refuses a sender signature on a free/public mailbox domain (ErrorCode 503). */
+const PUBLIC_DOMAINS = new Set(['gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'aol.com', 'icloud.com', 'live.com', 'msn.com']);
+
+/** The DomainDetails object Postmark returns (SDK: models/domains/Domain.d.ts). */
+function domainRecord(id: number, name: string, returnPath: string): Record<string, unknown> {
+  return {
+    ID: id, Name: name,
+    SPFVerified: false, DKIMVerified: false, WeakDKIM: false, ReturnPathDomainVerified: false,
+    SPFHost: name, SPFTextValue: 'v=spf1 a mx include:spf.mtasv.net ~all',
+    DKIMHost: `20260101._domainkey.${name}`, DKIMTextValue: 'k=rsa;p=TWINDKIMPUBLICKEY',
+    DKIMPendingHost: '', DKIMPendingTextValue: '', DKIMRevokedHost: '', DKIMRevokedTextValue: '',
+    SafeToRemoveRevokedKeyFromDNS: false, DKIMUpdateStatus: 'Verified',
+    ReturnPathDomain: returnPath, ReturnPathDomainCNAMEValue: 'pm.mtasv.net',
+  };
+}
+/** The list-shape of a domain (SDK: `Domain` — the 6 fields, no DNS detail block). */
+function domainSummary(d: Record<string, unknown>): Record<string, unknown> {
+  return { ID: d.ID, Name: d.Name, SPFVerified: d.SPFVerified, DKIMVerified: d.DKIMVerified, WeakDKIM: d.WeakDKIM, ReturnPathDomainVerified: d.ReturnPathDomainVerified };
+}
+/** The SignatureDetails object Postmark returns (SDK: models/senders/Signature.d.ts). */
+function signatureRecord(id: number, fromEmail: string, body: Record<string, unknown>): Record<string, unknown> {
+  const domain = fromEmail.split('@')[1] ?? '';
+  return {
+    ...domainRecord(id, domain, typeof body.ReturnPathDomain === 'string' ? body.ReturnPathDomain : ''),
+    ID: id,
+    Domain: domain,
+    EmailAddress: fromEmail,
+    ReplyToEmailAddress: typeof body.ReplyToEmail === 'string' ? body.ReplyToEmail : '',
+    Name: typeof body.Name === 'string' ? body.Name : fromEmail,
+    Confirmed: false,
+    ConfirmationPersonalNote: typeof body.ConfirmationPersonalNote === 'string' ? body.ConfirmationPersonalNote : '',
+  };
+}
+
+/**
+ * `/message-streams/:id/suppressions{,/dump,/delete}` — Postmark's suppression list is
+ * STREAM-SCOPED, and deletion is a POST to `/delete` (not an HTTP DELETE).
+ */
+async function suppressionsRoute(
+  seg: string[], method: string, body: Record<string, unknown>, query: Record<string, string>, req: PostmarkRequest,
+): Promise<PostmarkResponse> {
+  const stream = decodeURIComponent(seg[1] ?? '');
+  if (!getRow('message_stream', stream, req.root)) {
+    return fail(POSTMARK_ERRORS.streamNotFound, 'The message stream for the provided ID was not found.');
+  }
+
+  if (seg.length === 4 && seg[3] === 'dump' && method === 'GET') {
+    let items = rows('suppression', req.root).filter((s) => s.MessageStream === stream).map(view)
+      .map((s) => ({ EmailAddress: s.EmailAddress, SuppressionReason: s.SuppressionReason, Origin: s.Origin, CreatedAt: s.CreatedAt }));
+    if (query.suppressionReason) items = items.filter((s) => s.SuppressionReason === query.suppressionReason);
+    if (query.origin) items = items.filter((s) => s.Origin === query.origin);
+    if (query.emailAddress) items = items.filter((s) => String(s.EmailAddress).includes(query.emailAddress!));
+    return { status: 200, body: { Suppressions: items } };
+  }
+
+  const entries = Array.isArray(body.Suppressions) ? body.Suppressions.map(asObject) : [];
+  if (seg.length === 3 && method === 'POST') { // add
+    if (entries.length === 0) return fail(POSTMARK_ERRORS.suppressionNoBody, 'A proper request body must be provided.');
+    const out: Array<Record<string, unknown>> = [];
+    for (const e of entries) {
+      const email = String(e.EmailAddress ?? '');
+      if (!looksLikeEmail(email)) { out.push({ EmailAddress: email, Status: 'Failed', Message: 'An invalid email address was provided.' }); continue; }
+      await suppress(stream, email, 'ManualSuppression', 'Customer', req);
+      out.push({ EmailAddress: email, Status: 'Suppressed', Message: null });
+    }
+    return { status: 200, body: { Suppressions: out } };
+  }
+  if (seg.length === 4 && seg[3] === 'delete' && method === 'POST') {
+    if (entries.length === 0) return fail(POSTMARK_ERRORS.suppressionNoBody, 'A proper request body must be provided.');
+    const out: Array<Record<string, unknown>> = [];
+    for (const e of entries) {
+      const email = String(e.EmailAddress ?? '');
+      const sid = suppressionId(stream, email);
+      const cur = getRow('suppression', sid, req.root);
+      // Postmark only lets you delete a MANUAL suppression — a hard bounce or spam complaint
+      // must be cleared through the Bounce API instead (per-item ErrorCode 1406 semantics).
+      if (cur && cur.SuppressionReason !== 'ManualSuppression') {
+        out.push({ EmailAddress: email, Status: 'Failed', Message: 'You do not have the required authority to change this suppression.' });
+        continue;
+      }
+      if (cur) await writeResource('suppression', sid, { deleted: true }, 'suppression.delete', req);
+      out.push({ EmailAddress: email, Status: 'Deleted', Message: null });
+    }
+    return { status: 200, body: { Suppressions: out } };
+  }
+  return err(`Cannot ${method} /${seg.join('/')}`, 404, POSTMARK_ERRORS.invalidRequestField);
+}
+
+// Resource types the twin serves (for the conformance + mirror surfaces).
+export const POSTMARK_RESOURCE_TYPES = [
+  'message', 'bounce', 'template', 'message_stream', 'webhook', 'suppression',
+  'server', 'domain', 'sender_signature', 'inbound_rule', 'inbound_message', 'data_removal',
+] as const;