@hogsend/plugin-postmark 0.10.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2025 Doug Silkstone and Hogsend contributors
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,48 @@
+# @hogsend/plugin-postmark
+
+Postmark email delivery for [Hogsend](https://github.com/dougwithseismic/hogsend):
+single + batch sends and webhook parsing/verification, normalized into the
+provider-neutral `EmailEvent` the engine consumes.
+
+`createPostmarkProvider` implements the `EmailProvider` contract — the contract
+itself lives in `@hogsend/core` (canonical author import `@hogsend/engine`). It is
+an **opt-in** provider: Resend stays the default. Register it explicitly (see
+below) or via the `POSTMARK_SERVER_TOKEN` env preset, then make it active with
+`EMAIL_PROVIDER=postmark` (or `email.defaultProvider: "postmark"`).
+
+Two sovereign invariants Hogsend enforces through this provider:
+
+- **First-party open/click tracking is the single source of truth.** Postmark's
+  native tracking is forced OFF on every send (`TrackOpens: false`,
+  `TrackLinks: "None"`) — `capabilities.nativeTracking` is `false` and the engine
+  trusts it.
+- **The engine renders React → HTML itself** before the wire; this provider only
+  ever sees HTML (`HtmlBody`).
+
+## Opt-in usage
+
+```ts
+import { createPostmarkProvider } from "@hogsend/plugin-postmark";
+import { createHogsendClient } from "@hogsend/engine";
+
+const client = createHogsendClient({
+  email: {
+    providers: [
+      createPostmarkProvider({
+        serverToken: process.env.POSTMARK_SERVER_TOKEN!,
+        // Postmark has no HMAC — webhook auth is HTTP Basic creds baked into the
+        // webhook URL. Unconfigured = fail-closed (status updates rejected).
+        webhookBasicAuth: { user: "hogsend", pass: process.env.POSTMARK_WEBHOOK_PASS! },
+      }),
+    ],
+    defaultProvider: "postmark",
+  },
+});
+```
+
+Postmark has no native scheduled send (`capabilities.scheduledSend` is `false`):
+a `scheduledAt` is logged + dropped by the engine — use `ctx.sleepUntil` instead.
+
+This package ships raw TypeScript source; consumers bundle it via their own build
+(tsup `noExternal`). See the
+[release model](https://github.com/dougwithseismic/hogsend/blob/main/docs/RELEASING.md).

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hogsend/plugin-postmark",
+  "version": "0.10.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dougwithseismic/hogsend.git",
+    "directory": "packages/plugin-postmark"
+  },
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "postmark": "^4.0.7",
+    "@hogsend/core": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.7",
+    "@repo/typescript-config": "^0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  }
+}

package/src/__tests__/provider.test.ts

@@ -0,0 +1,335 @@
+import { WebhookHandshakeSignal } from "@hogsend/core";
+import { Models } from "postmark";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Capture the args every ServerClient method is called with, so we can assert on
+// the wire mapping without hitting the network.
+const sendEmail = vi.fn();
+const sendEmailBatch = vi.fn();
+
+vi.mock("postmark", async () => {
+  const actual = await vi.importActual<typeof import("postmark")>("postmark");
+  class MockServerClient {
+    sendEmail = sendEmail;
+    sendEmailBatch = sendEmailBatch;
+  }
+  return {
+    ...actual,
+    ServerClient: MockServerClient,
+  };
+});
+
+// Imported AFTER the mock so the provider picks up the mocked ServerClient.
+const { classifyPostmarkBounce, createPostmarkProvider, parsePostmarkWebhook } =
+  await import("../index.js");
+
+const SEND_OK = { ErrorCode: 0, Message: "OK", MessageID: "pm_msg_1" };
+
+beforeEach(() => {
+  sendEmail.mockReset();
+  sendEmailBatch.mockReset();
+});
+
+describe("send → Postmark message mapping", () => {
+  it("forces native tracking OFF and maps neutral fields to Postmark", async () => {
+    sendEmail.mockResolvedValue(SEND_OK);
+    const provider = createPostmarkProvider({ serverToken: "pm_token" });
+
+    const result = await provider.send({
+      from: "from@hogsend.com",
+      to: ["a@example.com", "b@example.com"],
+      cc: "cc@example.com",
+      subject: "Hello",
+      html: "<p>hi</p>",
+      text: "hi",
+      replyTo: "reply@hogsend.com",
+      tags: [
+        { name: "welcome", value: "onboarding" },
+        { name: "userId", value: "u_1" },
+      ],
+      headers: { "X-Custom": "v" },
+    });
+
+    expect(result).toEqual({ id: "pm_msg_1" });
+    // biome-ignore lint/style/noNonNullAssertion: the mock was just invoked.
+    const msg = sendEmail.mock.calls[0]![0];
+    // Sovereign invariant: native open/click tracking is forced off per-send.
+    expect(msg.TrackOpens).toBe(false);
+    expect(msg.TrackLinks).toBe(Models.LinkTrackingOptions.None);
+    // HTML-only wire — no React ever reaches Postmark.
+    expect(msg.HtmlBody).toBe("<p>hi</p>");
+    expect(msg.TextBody).toBe("hi");
+    expect("react" in msg).toBe(false);
+    // Recipient lists are joined into Postmark's comma string format.
+    expect(msg.To).toBe("a@example.com,b@example.com");
+    expect(msg.Cc).toBe("cc@example.com");
+    expect(msg.From).toBe("from@hogsend.com");
+    expect(msg.ReplyTo).toBe("reply@hogsend.com");
+    expect(msg.Subject).toBe("Hello");
+    // First tag's value → Postmark `Tag`; ALL tags → `Metadata` name→value.
+    expect(msg.Tag).toBe("onboarding");
+    expect(msg.Metadata).toEqual({ welcome: "onboarding", userId: "u_1" });
+    expect(msg.Headers).toEqual([{ Name: "X-Custom", Value: "v" }]);
+    expect(msg.MessageStream).toBe("outbound");
+  });
+
+  it("honors a custom message stream", async () => {
+    sendEmail.mockResolvedValue(SEND_OK);
+    const provider = createPostmarkProvider({
+      serverToken: "pm_token",
+      messageStream: "broadcasts",
+    });
+    await provider.send({
+      from: "f@h.com",
+      to: "t@h.com",
+      subject: "s",
+      html: "<p>x</p>",
+    });
+    // biome-ignore lint/style/noNonNullAssertion: the mock was just invoked.
+    expect(sendEmail.mock.calls[0]![0].MessageStream).toBe("broadcasts");
+  });
+
+  it("throws on a non-zero Postmark ErrorCode", async () => {
+    sendEmail.mockResolvedValue({
+      ErrorCode: 406,
+      Message: "Inactive recipient",
+      MessageID: "",
+    });
+    const provider = createPostmarkProvider({ serverToken: "pm_token" });
+    await expect(
+      provider.send({
+        from: "f@h.com",
+        to: "t@h.com",
+        subject: "s",
+        html: "<p>x</p>",
+      }),
+    ).rejects.toThrow("Postmark 406: Inactive recipient");
+  });
+
+  it("sendBatch forces tracking off on every item and maps ids", async () => {
+    sendEmailBatch.mockResolvedValue([
+      { ErrorCode: 0, Message: "OK", MessageID: "pm_a" },
+      { ErrorCode: 0, Message: "OK", MessageID: "pm_b" },
+    ]);
+    const provider = createPostmarkProvider({ serverToken: "pm_token" });
+    const { results } = await provider.sendBatch([
+      { from: "f@h.com", to: "a@h.com", subject: "s", html: "<p>a</p>" },
+      { from: "f@h.com", to: "b@h.com", subject: "s", html: "<p>b</p>" },
+    ]);
+    expect(results).toEqual([{ id: "pm_a" }, { id: "pm_b" }]);
+    // biome-ignore lint/style/noNonNullAssertion: the mock was just invoked.
+    const messages = sendEmailBatch.mock.calls[0]![0];
+    for (const m of messages) {
+      expect(m.TrackOpens).toBe(false);
+      expect(m.TrackLinks).toBe(Models.LinkTrackingOptions.None);
+    }
+  });
+});
+
+describe("verifyWebhook fail-closed auth", () => {
+  const payload = JSON.stringify({
+    RecordType: "Delivery",
+    MessageID: "pm_msg_1",
+    Recipient: "user@example.com",
+    DeliveredAt: "2024-01-01T00:00:00Z",
+  });
+  const basicAuth = { user: "hogsend", pass: "secret" };
+  const goodHeader = `Basic ${Buffer.from("hogsend:secret").toString("base64")}`;
+
+  it("FAILS CLOSED when webhook auth is unconfigured", () => {
+    const provider = createPostmarkProvider({ serverToken: "pm_token" });
+    expect(() =>
+      provider.verifyWebhook({
+        payload,
+        headers: { authorization: goodHeader },
+      }),
+    ).toThrow("Postmark webhook auth not configured");
+  });
+
+  it("rejects a missing Authorization header", () => {
+    const provider = createPostmarkProvider({
+      serverToken: "pm_token",
+      webhookBasicAuth: basicAuth,
+    });
+    expect(() => provider.verifyWebhook({ payload, headers: {} })).toThrow(
+      "Postmark webhook auth failed",
+    );
+  });
+
+  it("rejects a mismatched Authorization header", () => {
+    const provider = createPostmarkProvider({
+      serverToken: "pm_token",
+      webhookBasicAuth: basicAuth,
+    });
+    const wrong = `Basic ${Buffer.from("hogsend:wrong").toString("base64")}`;
+    expect(() =>
+      provider.verifyWebhook({ payload, headers: { authorization: wrong } }),
+    ).toThrow("Postmark webhook auth failed");
+  });
+
+  it("accepts the correct Basic creds and returns a normalized event", async () => {
+    const provider = createPostmarkProvider({
+      serverToken: "pm_token",
+      webhookBasicAuth: basicAuth,
+    });
+    // verifyWebhook may be sync OR async per the contract — await covers both.
+    const event = await provider.verifyWebhook({
+      payload,
+      headers: { authorization: goodHeader },
+    });
+    expect(event.type).toBe("email.delivered");
+    expect(event.messageId).toBe("pm_msg_1");
+    expect(event.recipients).toEqual(["user@example.com"]);
+  });
+});
+
+describe("parsePostmarkWebhook RecordType → EmailEvent", () => {
+  it("maps Delivery → email.delivered", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "Delivery",
+        MessageID: "pm_1",
+        Recipient: "u@example.com",
+        DeliveredAt: "2024-01-01T00:00:00Z",
+      }),
+    );
+    expect(event.type).toBe("email.delivered");
+    expect(event.occurredAt).toBe("2024-01-01T00:00:00Z");
+  });
+
+  it("maps Open → email.opened (native echo, status no-op)", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "Open",
+        MessageID: "pm_1",
+        Recipient: "u@example.com",
+        ReceivedAt: "2024-01-01T00:01:00Z",
+      }),
+    );
+    expect(event.type).toBe("email.opened");
+  });
+
+  it("maps Click → email.clicked with the click payload", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "Click",
+        MessageID: "pm_1",
+        Recipient: "u@example.com",
+        ReceivedAt: "2024-01-01T00:02:00Z",
+        OriginalLink: "https://hogsend.com/x",
+        UserAgent: "Mozilla",
+      }),
+    );
+    expect(event.type).toBe("email.clicked");
+    expect(event.click).toEqual({
+      url: "https://hogsend.com/x",
+      at: "2024-01-01T00:02:00Z",
+      ua: "Mozilla",
+    });
+  });
+
+  it("maps SpamComplaint → email.complained (class: complaint)", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "SpamComplaint",
+        MessageID: "pm_1",
+        Email: "u@example.com",
+        BouncedAt: "2024-01-01T00:00:00Z",
+        Description: "User marked as spam",
+      }),
+    );
+    expect(event.type).toBe("email.complained");
+    expect(event.bounce).toEqual({
+      class: "complaint",
+      code: "SpamComplaint",
+      reason: "User marked as spam",
+    });
+    expect(event.recipients).toEqual(["u@example.com"]);
+  });
+
+  it("throws WebhookHandshakeSignal for a non-status RecordType", () => {
+    expect(() =>
+      parsePostmarkWebhook(
+        JSON.stringify({
+          RecordType: "SubscriptionChange",
+          MessageID: "pm_1",
+          Recipient: "u@example.com",
+        }),
+      ),
+    ).toThrow(WebhookHandshakeSignal);
+  });
+});
+
+describe("Bounce TypeCode → class mapping", () => {
+  // The spec table: HardBounce=1, Transient=2, DnsError=256,
+  // SpamNotification=512, SoftBounce=4096, BadEmailAddress=100000,
+  // SpamComplaint=100001, Blocked=100006.
+  const cases: Array<[number, string, string]> = [
+    [1, "HardBounce", "permanent"],
+    [2, "Transient", "transient"],
+    [256, "DnsError", "transient"],
+    [512, "SpamNotification", "complaint"],
+    [4096, "SoftBounce", "transient"],
+    [100000, "BadEmailAddress", "permanent"],
+    [100001, "SpamComplaint", "complaint"],
+    [100006, "Blocked", "permanent"],
+  ];
+
+  for (const [typeCode, , expected] of cases) {
+    it(`TypeCode ${typeCode} → ${expected}`, () => {
+      expect(classifyPostmarkBounce(typeCode)).toBe(expected);
+    });
+  }
+
+  it("maps a permanent Bounce → email.bounced class:permanent", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "Bounce",
+        MessageID: "pm_1",
+        Email: "u@example.com",
+        TypeCode: 1,
+        Type: "HardBounce",
+        BouncedAt: "2024-01-01T00:00:00Z",
+        Description: "Mailbox not found",
+      }),
+    );
+    expect(event.type).toBe("email.bounced");
+    expect(event.bounce).toEqual({
+      class: "permanent",
+      code: "HardBounce",
+      reason: "Mailbox not found",
+    });
+  });
+
+  it("maps a transient (soft) Bounce → email.bounced class:transient", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "Bounce",
+        MessageID: "pm_1",
+        Email: "u@example.com",
+        TypeCode: 4096,
+        Type: "SoftBounce",
+        BouncedAt: "2024-01-01T00:00:00Z",
+      }),
+    );
+    // Recorded as bounced, carrying transient class — the engine records but
+    // does NOT increment the suppression counter for these.
+    expect(event.type).toBe("email.bounced");
+    expect(event.bounce?.class).toBe("transient");
+  });
+
+  it("routes a complaint-class Bounce → email.complained", () => {
+    const event = parsePostmarkWebhook(
+      JSON.stringify({
+        RecordType: "Bounce",
+        MessageID: "pm_1",
+        Email: "u@example.com",
+        TypeCode: 100001,
+        Type: "SpamComplaint",
+        BouncedAt: "2024-01-01T00:00:00Z",
+      }),
+    );
+    expect(event.type).toBe("email.complained");
+    expect(event.bounce?.class).toBe("complaint");
+  });
+});

package/src/index.ts

@@ -0,0 +1,253 @@
+import {
+  type BatchEmailItem,
+  type BounceClass,
+  defineEmailProvider,
+  type EmailEvent,
+  type EmailEventType,
+  type EmailProvider,
+  joinRecipients,
+  type SendEmailOptions,
+  type SendResult,
+  WebhookHandshakeSignal,
+} from "@hogsend/core";
+import { type Message, Models, ServerClient } from "postmark";
+
+/**
+ * Construction config for {@link createPostmarkProvider}.
+ *
+ * Postmark has no svix/HMAC webhook signature, so webhook authenticity is HTTP
+ * Basic creds baked into the webhook URL. `webhookBasicAuth` is OPTIONAL only so
+ * a send-only deploy can skip it — but `verifyWebhook` FAILS CLOSED when it is
+ * unset, so an unauthenticated status update is always rejected.
+ */
+export interface PostmarkConfig {
+  /** Postmark Server API token (per-server, not the account token). */
+  serverToken: string;
+  /** Outbound message stream id. Defaults to Postmark's `"outbound"`. */
+  messageStream?: string;
+  /** HTTP Basic creds the webhook URL must present. Unset → webhooks rejected. */
+  webhookBasicAuth?: { user: string; pass: string };
+}
+
+/** Postmark wants comma-joined recipient strings; omit the field when empty. */
+const join = (v?: string | string[]): string | undefined =>
+  joinRecipients(v) || undefined;
+
+/**
+ * The Postmark implementation of the engine's {@link EmailProvider} contract: a
+ * dumb delivery + webhook parse/verify layer. All tracking, DB, preference, and
+ * render logic lives in the engine's `createTrackedMailer`, not here.
+ *
+ * Two sovereign invariants are enforced here:
+ *
+ * - **First-party open/click tracking is the source of truth.** Every send
+ *   forces `TrackOpens: false` + `TrackLinks: "None"`, so `capabilities`
+ *   declares `nativeTracking: false` and the engine trusts it.
+ * - **HTML-only wire.** The engine renders React → HTML itself before calling
+ *   `send`; Postmark only ever sees `HtmlBody`.
+ *
+ * Opt-in only — Resend stays the default. Register it explicitly via
+ * `email.providers` (or the `POSTMARK_SERVER_TOKEN` env preset) and activate it
+ * with `EMAIL_PROVIDER=postmark` / `email.defaultProvider: "postmark"`.
+ */
+export function createPostmarkProvider(cfg: PostmarkConfig): EmailProvider {
+  const client = new ServerClient(cfg.serverToken);
+  const stream = cfg.messageStream ?? "outbound";
+
+  const toMessage = (o: SendEmailOptions | BatchEmailItem): Message => {
+    // Postmark has a single `Tag` (first tag's value) + a `Metadata` record (all
+    // tags as name→value). Omit each when there are no tags.
+    const tags = o.tags ?? [];
+    const message: Message = {
+      From: o.from,
+      To: join(o.to),
+      Cc: join(o.cc),
+      Bcc: join(o.bcc),
+      Subject: o.subject,
+      // The engine ALWAYS renders React → HTML before the wire — no React here.
+      HtmlBody: o.html,
+      TextBody: o.text,
+      ReplyTo: join(o.replyTo),
+      Tag: tags[0]?.value,
+      Metadata:
+        tags.length > 0
+          ? Object.fromEntries(tags.map((t) => [t.name, t.value]))
+          : undefined,
+      Headers: o.headers
+        ? Object.entries(o.headers).map(([Name, Value]) => ({ Name, Value }))
+        : undefined,
+      // NATIVE TRACKING OFF — first-party open/click tracking is sovereign.
+      TrackOpens: false,
+      TrackLinks: Models.LinkTrackingOptions.None,
+      MessageStream: stream,
+    };
+    return message;
+  };
+
+  return defineEmailProvider({
+    meta: { id: "postmark", name: "Postmark" },
+    capabilities: {
+      // Forced off per-send above → the engine TRUSTS native tracking is off.
+      nativeTracking: false,
+      // No native scheduled send — the engine drops `scheduledAt` with a WARN.
+      scheduledSend: false,
+      // No HMAC scheme — webhooks fail-closed on HTTP Basic creds instead.
+      signedWebhooks: false,
+    },
+
+    async send(o: SendEmailOptions): Promise<SendResult> {
+      const r = await client.sendEmail(toMessage(o));
+      if (r.ErrorCode !== 0) {
+        throw new Error(`Postmark ${r.ErrorCode}: ${r.Message}`);
+      }
+      return { id: r.MessageID } satisfies SendResult;
+    },
+
+    async sendBatch(
+      items: BatchEmailItem[],
+    ): Promise<{ results: SendResult[] }> {
+      const r = await client.sendEmailBatch(items.map(toMessage));
+      return { results: r.map((x) => ({ id: x.MessageID })) };
+    },
+
+    /**
+     * Postmark has no svix/HMAC — webhook authenticity is HTTP Basic creds in
+     * the webhook URL. FAIL CLOSED when creds are unconfigured or mismatched so
+     * an unauthenticated status update is always rejected.
+     */
+    verifyWebhook(opts: {
+      payload: string;
+      headers: Record<string, string>;
+    }): EmailEvent {
+      if (!cfg.webhookBasicAuth) {
+        throw new Error("Postmark webhook auth not configured");
+      }
+      const expected = `Basic ${Buffer.from(
+        `${cfg.webhookBasicAuth.user}:${cfg.webhookBasicAuth.pass}`,
+      ).toString("base64")}`;
+      if (opts.headers.authorization !== expected) {
+        throw new Error("Postmark webhook auth failed");
+      }
+      return parsePostmarkWebhook(opts.payload);
+    },
+
+    parseWebhook(payload: string): EmailEvent {
+      return parsePostmarkWebhook(payload);
+    },
+  });
+}
+
+/**
+ * Postmark `Bounce.TypeCode` values, mapped to provider-neutral bounce classes.
+ * The raw string `Type` is preserved in `bounce.code` so nothing is lost.
+ *
+ * - `complaint` → immediate suppress via the complaint path.
+ * - `transient` → recorded as `email.bounced` but does NOT suppress.
+ * - `permanent` → auto-suppress (the engine increments `bounceCount`).
+ *
+ * @see https://postmarkapp.com/developer/api/bounce-api#bounce-types
+ */
+const COMPLAINT_TYPE_CODES = new Set<number>([
+  512, // SpamNotification
+  100001, // SpamComplaint
+]);
+const TRANSIENT_TYPE_CODES = new Set<number>([
+  2, // Transient
+  256, // DnsError
+  4096, // SoftBounce
+]);
+
+/** Map a Postmark `Bounce.TypeCode` → provider-neutral bounce class. */
+export function classifyPostmarkBounce(typeCode: number): BounceClass {
+  if (COMPLAINT_TYPE_CODES.has(typeCode)) return "complaint";
+  if (TRANSIENT_TYPE_CODES.has(typeCode)) return "transient";
+  // Default conservative for a delivery-status Bounce record is `permanent`
+  // (HardBounce=1, BadEmailAddress=100000, Blocked=100006, …) — these are the
+  // states that SHOULD auto-suppress.
+  return "permanent";
+}
+
+/**
+ * Adapt Postmark's verbatim webhook payload into the provider-neutral
+ * {@link EmailEvent}. Maps `RecordType` → event type, `MessageID` →
+ * `messageId`, `Recipient`/`Email` → `recipients`, and the `Bounce.TypeCode`
+ * table → `bounce.class`. Non-delivery-status records (e.g. SubscriptionChange)
+ * throw {@link WebhookHandshakeSignal} — the engine's webhook route 200s those.
+ */
+export function parsePostmarkWebhook(payload: string): EmailEvent {
+  const p = JSON.parse(payload) as Record<string, unknown>;
+  const recipients = [p.Recipient ?? p.Email].filter(
+    (x): x is string => typeof x === "string" && x.length > 0,
+  );
+  const base = {
+    messageId: (p.MessageID as string) ?? "",
+    recipients,
+    raw: p,
+  };
+
+  switch (p.RecordType as string) {
+    case "Delivery":
+      return {
+        ...base,
+        type: "email.delivered" as EmailEventType,
+        occurredAt: (p.DeliveredAt as string) ?? new Date().toISOString(),
+      };
+    case "Open":
+      // Only arrives if native tracking is on — we keep it off, so this is a
+      // status no-op echo at most. First-party tracking owns opens.
+      return {
+        ...base,
+        type: "email.opened" as EmailEventType,
+        occurredAt: (p.ReceivedAt as string) ?? new Date().toISOString(),
+      };
+    case "Click":
+      // Same as Open — first-party owns clicks; native echo only.
+      return {
+        ...base,
+        type: "email.clicked" as EmailEventType,
+        occurredAt: (p.ReceivedAt as string) ?? new Date().toISOString(),
+        click: {
+          url: (p.OriginalLink as string) ?? "",
+          ...(p.ReceivedAt ? { at: p.ReceivedAt as string } : {}),
+          ...(p.UserAgent ? { ua: p.UserAgent as string } : {}),
+        },
+      };
+    case "SpamComplaint":
+      return {
+        ...base,
+        type: "email.complained" as EmailEventType,
+        occurredAt: (p.BouncedAt as string) ?? new Date().toISOString(),
+        bounce: {
+          class: "complaint",
+          code: "SpamComplaint",
+          ...(p.Description ? { reason: p.Description as string } : {}),
+        },
+      };
+    case "Bounce": {
+      const typeCode = Number(p.TypeCode ?? 0);
+      const cls = classifyPostmarkBounce(typeCode);
+      // Map BOTH transient + permanent → email.bounced, carrying bounce.class so
+      // the ENGINE decides suppression (only `permanent` increments bounceCount;
+      // `transient` is recorded but never suppresses). Do NOT map transient →
+      // email.delivery_delayed (the engine no-ops that).
+      return {
+        ...base,
+        type: (cls === "complaint"
+          ? "email.complained"
+          : "email.bounced") as EmailEventType,
+        occurredAt: (p.BouncedAt as string) ?? new Date().toISOString(),
+        bounce: {
+          class: cls,
+          code: (p.Type as string) ?? String(typeCode),
+          ...(p.Description ? { reason: p.Description as string } : {}),
+        },
+      };
+    }
+    default:
+      // SubscriptionChange and other non-delivery-status records are NOT email
+      // events. Throw the typed handshake skip — the engine route 200s it.
+      throw new WebhookHandshakeSignal(
+        `ignored RecordType ${String(p.RecordType)}`,
+      );
+  }
+}