@hogsend/plugin-resend 0.9.0 → 0.10.0

package/README.md

@@ -1,14 +1,27 @@
 # @hogsend/plugin-resend
 
 Resend email delivery for [Hogsend](https://github.com/dougwithseismic/hogsend):
-single + batch sends, tracked sends, webhook parsing/verification, and an email
-service with bounce tracking.
-
-`createResendProvider` is the **reference implementation** of the `EmailProvider`
-contract — the contract itself lives in `@hogsend/core` (canonical author import
-`@hogsend/engine`); this package re-exports `EmailProvider` and its supporting
-types for back-compat. To support another provider, implement that interface. See
-[docs/adr/0001-provider-boundary.md](https://github.com/dougwithseismic/hogsend/blob/main/docs/adr/0001-provider-boundary.md).
+single + batch sends and webhook parsing/verification (svix), normalized into the
+provider-neutral `EmailEvent` the engine consumes.
+
+`createResendProvider` is the **reference implementation** of the provider-neutral
+`EmailProvider` contract — the contract itself lives in `@hogsend/core` (canonical
+author import `@hogsend/engine`); this package re-exports `EmailProvider` and its
+supporting types for back-compat. To support another provider, implement that
+interface (see the sibling `@hogsend/plugin-postmark`, or
+[docs/byo-email-provider.md](https://github.com/dougwithseismic/hogsend/blob/main/docs/byo-email-provider.md)).
+
+Resend is the **default** provider; activate another with `EMAIL_PROVIDER` /
+`email.defaultProvider`. Two sovereign invariants the engine enforces through this
+provider:
+
+- **First-party open/click tracking is the single source of truth.** Resend's
+  native open/click tracking is an account-level toggle the provider can't disable
+  per-send, so `capabilities.nativeTracking` is `true` and the engine logs a boot
+  WARN — disable it in the Resend dashboard. Provider webhooks are consumed only
+  for `delivered`/`bounced`/`complained`.
+- **The engine renders React → HTML itself** before the wire; this provider's
+  `send`/`sendBatch` only ever see HTML strings.
 
 This package ships raw TypeScript source; consumers bundle it via their own build
 (tsup `noExternal`). See the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/plugin-resend",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -24,8 +24,8 @@
   "dependencies": {
     "resend": "^6.12.3",
     "svix": "^1.94.0",
-    "@hogsend/core": "^0.9.0",
-    "@hogsend/email": "^0.9.0"
+    "@hogsend/core": "^0.10.0",
+    "@hogsend/email": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/__tests__/send.test.ts

@@ -1,5 +1,4 @@
 import { EmailSendError } from "@hogsend/email";
-import { createElement } from "react";
 import type { Resend } from "resend";
 import { describe, expect, it, vi } from "vitest";
 import { sendBatchEmails, sendEmail } from "../send.js";
@@ -28,9 +27,7 @@ function mockResendClient(overrides?: {
   } as unknown as Resend;
 }
 
-function dummyElement() {
-  return createElement("div", null, "test");
-}
+const HTML = "<p>test</p>";
 
 describe("sendEmail", () => {
   it("sends successfully and returns id", async () => {
@@ -41,12 +38,36 @@ describe("sendEmail", () => {
         from: "test@hogsend.com",
         to: "user@example.com",
         subject: "Test",
-        react: dummyElement(),
+        html: HTML,
       },
     });
     expect(result.id).toBe("resend_123");
   });
 
+  it("sends HTML on the wire (never React)", async () => {
+    const sendFn = vi.fn().mockResolvedValue({
+      data: { id: "resend_123" },
+      error: null,
+    });
+    const client = mockResendClient({ sendFn });
+
+    await sendEmail({
+      client,
+      options: {
+        from: "test@hogsend.com",
+        to: "user@example.com",
+        subject: "Test",
+        html: HTML,
+        text: "test",
+      },
+    });
+
+    const arg = sendFn.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(arg.html).toBe(HTML);
+    expect(arg.text).toBe("test");
+    expect(arg).not.toHaveProperty("react");
+  });
+
   it("normalizes string recipient to array", async () => {
     const sendFn = vi.fn().mockResolvedValue({
       data: { id: "resend_123" },
@@ -60,7 +81,7 @@ describe("sendEmail", () => {
         from: "test@hogsend.com",
         to: "user@example.com",
         subject: "Test",
-        react: dummyElement(),
+        html: HTML,
       },
     });
 
@@ -69,6 +90,55 @@ describe("sendEmail", () => {
     );
   });
 
+  it("passes neutral tags straight through to Resend", async () => {
+    const sendFn = vi.fn().mockResolvedValue({
+      data: { id: "resend_123" },
+      error: null,
+    });
+    const client = mockResendClient({ sendFn });
+
+    const tags = [
+      { name: "campaign", value: "q1" },
+      { name: "cohort", value: "beta" },
+    ];
+    await sendEmail({
+      client,
+      options: {
+        from: "test@hogsend.com",
+        to: "user@example.com",
+        subject: "Test",
+        html: HTML,
+        tags,
+      },
+    });
+
+    const arg = sendFn.mock.calls[0]?.[0] as {
+      tags?: Array<{ name: string; value: string }>;
+    };
+    expect(arg.tags).toEqual(tags);
+  });
+
+  it("omits Resend tags when none are set", async () => {
+    const sendFn = vi.fn().mockResolvedValue({
+      data: { id: "resend_123" },
+      error: null,
+    });
+    const client = mockResendClient({ sendFn });
+
+    await sendEmail({
+      client,
+      options: {
+        from: "test@hogsend.com",
+        to: "user@example.com",
+        subject: "Test",
+        html: HTML,
+      },
+    });
+
+    const arg = sendFn.mock.calls[0]?.[0] as { tags?: unknown };
+    expect(arg.tags).toBeUndefined();
+  });
+
   it("throws EmailSendError on API error", async () => {
     const client = mockResendClient({
       sendFn: vi.fn().mockResolvedValue({
@@ -84,7 +154,7 @@ describe("sendEmail", () => {
           from: "test@hogsend.com",
           to: "user@example.com",
           subject: "Test",
-          react: dummyElement(),
+          html: HTML,
         },
         retryOptions: { maxRetries: 0 },
       }),
@@ -111,7 +181,7 @@ describe("sendEmail", () => {
         from: "test@hogsend.com",
         to: "user@example.com",
         subject: "Test",
-        react: dummyElement(),
+        html: HTML,
       },
       retryOptions: { maxRetries: 3, baseDelayMs: 10, maxDelayMs: 50 },
     });
@@ -134,7 +204,7 @@ describe("sendEmail", () => {
           from: "test@hogsend.com",
           to: "user@example.com",
           subject: "Test",
-          react: dummyElement(),
+          html: HTML,
         },
         retryOptions: { maxRetries: 3, baseDelayMs: 10 },
       }),
@@ -160,13 +230,13 @@ describe("sendBatchEmails", () => {
           from: "a@hogsend.com",
           to: "b@example.com",
           subject: "A",
-          react: dummyElement(),
+          html: HTML,
         },
         {
           from: "a@hogsend.com",
           to: "c@example.com",
           subject: "B",
-          react: dummyElement(),
+          html: HTML,
         },
       ],
     });
@@ -184,7 +254,7 @@ describe("sendBatchEmails", () => {
       from: "a@hogsend.com",
       to: `user${i}@example.com`,
       subject: `Email ${i}`,
-      react: dummyElement(),
+      html: HTML,
     }));
 
     await sendBatchEmails({ client, emails });

package/src/__tests__/webhooks.test.ts

@@ -1,7 +1,12 @@
+import type { LegacyResendWebhookEvent } from "@hogsend/core";
 import { WebhookVerificationError } from "@hogsend/email";
 import { describe, expect, it } from "vitest";
 import type { EmailSentEvent } from "../types.js";
-import { createWebhookHandler, parseWebhookEvent } from "../webhooks.js";
+import {
+  classifyResendBounce,
+  createWebhookHandler,
+  parseWebhookEvent,
+} from "../webhooks.js";
 
 function makeSentEvent(): EmailSentEvent {
   return {
@@ -17,15 +22,20 @@ function makeSentEvent(): EmailSentEvent {
   };
 }
 
-describe("parseWebhookEvent", () => {
-  it("parses a valid sent event", () => {
+describe("parseWebhookEvent → EmailEvent", () => {
+  it("normalizes a sent event into the neutral shape", () => {
     const event = makeSentEvent();
     const parsed = parseWebhookEvent(JSON.stringify(event));
     expect(parsed.type).toBe("email.sent");
-    expect(parsed.data.email_id).toBe("email_123");
+    expect(parsed.messageId).toBe("email_123");
+    expect(parsed.recipients).toEqual(["user@example.com"]);
+    expect(parsed.occurredAt).toBe("2024-01-01T00:00:00Z");
+    // `raw` is the escape hatch: still readable via the legacy union cast.
+    const legacy = parsed.raw as LegacyResendWebhookEvent;
+    expect(legacy.data.email_id).toBe("email_123");
   });
 
-  it("parses a valid bounced event", () => {
+  it("normalizes a bounced event with the bounce class table", () => {
     const event = {
       type: "email.bounced",
       created_at: "2024-01-01T00:00:00Z",
@@ -35,11 +45,44 @@ describe("parseWebhookEvent", () => {
         to: ["user@example.com"],
         subject: "Test",
         created_at: "2024-01-01T00:00:00Z",
-        bounce: { message: "Mailbox not found", type: "hard" },
+        bounce: { message: "Mailbox not found", type: "HardBounce" },
       },
     };
     const parsed = parseWebhookEvent(JSON.stringify(event));
     expect(parsed.type).toBe("email.bounced");
+    expect(parsed.bounce).toEqual({
+      class: "permanent",
+      code: "HardBounce",
+      reason: "Mailbox not found",
+    });
+  });
+
+  it("normalizes a clicked event into the neutral click shape", () => {
+    const event = {
+      type: "email.clicked",
+      created_at: "2024-01-01T00:00:00Z",
+      data: {
+        email_id: "email_789",
+        from: "test@hogsend.com",
+        to: ["user@example.com"],
+        subject: "Test",
+        created_at: "2024-01-01T00:00:00Z",
+        click: {
+          link: "https://hogsend.com/x",
+          timestamp: "2024-01-01T00:01:00Z",
+          ipAddress: "1.2.3.4",
+          userAgent: "Mozilla",
+        },
+      },
+    };
+    const parsed = parseWebhookEvent(JSON.stringify(event));
+    expect(parsed.type).toBe("email.clicked");
+    expect(parsed.click).toEqual({
+      url: "https://hogsend.com/x",
+      at: "2024-01-01T00:01:00Z",
+      ip: "1.2.3.4",
+      ua: "Mozilla",
+    });
   });
 
   it("throws on unknown event type", () => {
@@ -54,6 +97,41 @@ describe("parseWebhookEvent", () => {
   });
 });
 
+describe("classifyResendBounce (the free-string → class table)", () => {
+  const cases: Array<[string, string]> = [
+    ["HardBounce", "permanent"],
+    ["Permanent", "permanent"],
+    ["SuppressedRecipient", "permanent"],
+    ["Suppressed", "permanent"],
+    ["SoftBounce", "transient"],
+    ["Transient", "transient"],
+    ["MailboxFull", "transient"],
+    ["Throttled", "transient"],
+    ["Undetermined", "transient"],
+    ["Complaint", "complaint"],
+    ["Spam", "complaint"],
+    ["Abuse", "complaint"],
+    ["SomethingNew", "unknown"],
+    ["", "unknown"],
+  ];
+
+  for (const [input, expected] of cases) {
+    it(`maps "${input}" → ${expected}`, () => {
+      expect(classifyResendBounce(input)).toBe(expected);
+    });
+  }
+
+  it("is case-insensitive and substring-based", () => {
+    expect(classifyResendBounce("a HardBounce occurred")).toBe("permanent");
+    expect(classifyResendBounce("a spam complaint")).toBe("complaint");
+    expect(classifyResendBounce("HARDBOUNCE")).toBe("permanent");
+  });
+
+  it("treats undefined as unknown (no suppression)", () => {
+    expect(classifyResendBounce(undefined)).toBe("unknown");
+  });
+});
+
 describe("createWebhookHandler", () => {
   it("requires valid svix headers", async () => {
     const handler = createWebhookHandler({

package/src/index.ts

@@ -7,26 +7,45 @@ export {
 } from "./provider.js";
 // Sending (with retry + auto-chunking)
 export { sendBatchEmails, sendEmail } from "./send.js";
-// Types
+// Deprecated Resend-shaped union (frozen one minor; cast `event.raw`).
 export type {
   BatchEmailItem,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailBouncedEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailClickedEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailComplainedEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailDeliveredEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailDeliveryDelayedEvent,
+  EmailEvent,
+  EmailEventType,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailOpenedEvent,
   EmailProvider,
+  EmailProviderCapabilities,
+  EmailProviderMeta,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailSentEvent,
+  /** @deprecated Use {@link EmailEvent}. Frozen `event.raw` cast target. */
+  LegacyResendWebhookEvent,
   SendEmailOptions,
   SendResult,
+  /** @deprecated Use {@link EmailEvent}. Kept for one minor. */
   WebhookEvent,
+  /** @deprecated Use {@link EmailEventType}. Kept for one minor. */
   WebhookEventType,
   WebhookHandlerMap,
 } from "./types.js";
+// Types
+export { defineEmailProvider, WebhookHandshakeSignal } from "./types.js";
 // Webhooks
 export {
+  classifyResendBounce,
   createWebhookHandler,
   parseWebhookEvent,
+  toEmailEvent,
   verifyWebhook,
 } from "./webhooks.js";

package/src/provider.ts

@@ -1,12 +1,13 @@
 import type { RetryOptions } from "@hogsend/email";
 import { createResendClient } from "./client.js";
 import { sendBatchEmails, sendEmail } from "./send.js";
-import type {
-  BatchEmailItem,
-  EmailProvider,
-  SendEmailOptions,
-  SendResult,
-  WebhookEvent,
+import {
+  type BatchEmailItem,
+  defineEmailProvider,
+  type EmailEvent,
+  type EmailProvider,
+  type SendEmailOptions,
+  type SendResult,
 } from "./types.js";
 import { parseWebhookEvent, verifyWebhook } from "./webhooks.js";
 
@@ -27,7 +28,17 @@ export function createResendProvider(
   const client = createResendClient({ apiKey: config.apiKey });
   const retryOptions = config.retryOptions;
 
-  return {
+  return defineEmailProvider({
+    meta: { id: "resend", name: "Resend" },
+    capabilities: {
+      // Resend's open/click tracking is an account-level toggle the provider
+      // can't disable per-send, so the engine logs a boot WARN (first-party
+      // tracking stays the source of truth).
+      nativeTracking: true,
+      scheduledSend: true,
+      signedWebhooks: true,
+    },
+
     async send(options: SendEmailOptions): Promise<SendResult> {
       return sendEmail({ client, options, retryOptions });
     },
@@ -42,7 +53,7 @@ export function createResendProvider(
     verifyWebhook(opts: {
       payload: string;
       headers: Record<string, string>;
-    }): WebhookEvent {
+    }): EmailEvent {
       if (!config.webhookSecret) {
         throw new Error(
           "webhookSecret is required on the provider to verify webhooks",
@@ -55,8 +66,8 @@ export function createResendProvider(
       });
     },
 
-    parseWebhook(payload: string): WebhookEvent {
+    parseWebhook(payload: string): EmailEvent {
       return parseWebhookEvent(payload);
     },
-  };
+  });
 }

package/src/send.ts

@@ -1,3 +1,4 @@
+import { normalizeRecipients } from "@hogsend/core";
 import {
   DEFAULT_RETRY_OPTIONS,
   EmailSendError,
@@ -8,10 +9,6 @@ import type { BatchEmailItem, SendEmailOptions, SendResult } from "./types.js";
 
 const BATCH_CHUNK_SIZE = 100;
 
-function normalizeRecipients(to: string | string[]): string[] {
-  return Array.isArray(to) ? to : [to];
-}
-
 function isRetryableStatusCode(statusCode: number): boolean {
   return statusCode === 429 || statusCode >= 500;
 }
@@ -104,11 +101,15 @@ export async function sendEmail(args: {
       from: options.from,
       to: normalizeRecipients(options.to),
       subject: options.subject,
-      ...(options.html ? { html: options.html } : { react: options.react }),
+      // HTML-ONLY wire — the engine always renders React → HTML before the
+      // provider, so no React ever reaches Resend here.
+      html: options.html,
+      text: options.text,
       replyTo: options.replyTo,
       cc: options.cc,
       bcc: options.bcc,
       scheduledAt: options.scheduledAt,
+      // Resend accepts neutral `{name,value}[]` tags natively — pass them through.
       tags: options.tags,
       headers: options.headers,
     });
@@ -175,10 +176,13 @@ async function sendBatchChunk(
         from: email.from,
         to: normalizeRecipients(email.to),
         subject: email.subject,
-        react: email.react,
+        // HTML-ONLY wire — no React reaches Resend.
+        html: email.html,
+        text: email.text,
         replyTo: email.replyTo,
         cc: email.cc,
         bcc: email.bcc,
+        // Resend accepts neutral `{name,value}[]` tags natively.
         tags: email.tags,
         headers: email.headers,
       })),

package/src/types.ts

@@ -1,19 +1,39 @@
 // The email-provider contract now lives in the neutral @hogsend/core package.
 // These re-exports keep every existing `import ... from "@hogsend/plugin-resend"`
 // working unchanged.
+
+// --- Deprecated Resend-shaped union (frozen one minor) ---------------------
+// These no longer flow through verifyWebhook/parseWebhook (which now return the
+// provider-neutral `EmailEvent`); they remain only as `event.raw` cast targets.
 export type {
   BatchEmailItem,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailBouncedEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailClickedEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailComplainedEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailDeliveredEvent,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailDeliveryDelayedEvent,
+  EmailEvent,
+  EmailEventType,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailOpenedEvent,
   EmailProvider,
+  EmailProviderCapabilities,
+  EmailProviderMeta,
+  /** @deprecated Use {@link EmailEvent}; cast `event.raw`. */
   EmailSentEvent,
+  /** @deprecated Use {@link EmailEvent}. Frozen `event.raw` cast target. */
+  LegacyResendWebhookEvent,
   SendEmailOptions,
   SendResult,
+  /** @deprecated Use {@link EmailEvent}. Kept for one minor. */
   WebhookEvent,
+  /** @deprecated Use {@link EmailEventType}. Kept for one minor. */
   WebhookEventType,
   WebhookHandlerMap,
 } from "@hogsend/core";
+export { defineEmailProvider, WebhookHandshakeSignal } from "@hogsend/core";

package/src/webhooks.ts

@@ -1,3 +1,9 @@
+import {
+  type BounceClass,
+  type EmailEvent,
+  type EmailEventType,
+  normalizeRecipients,
+} from "@hogsend/core";
 import { WebhookVerificationError } from "@hogsend/email";
 import { Webhook } from "svix";
 import type {
@@ -6,11 +12,123 @@ import type {
   WebhookHandlerMap,
 } from "./types.js";
 
+const VALID_TYPES: readonly EmailEventType[] = [
+  "email.sent",
+  "email.delivered",
+  "email.bounced",
+  "email.complained",
+  "email.delivery_delayed",
+  "email.opened",
+  "email.clicked",
+];
+
+/**
+ * Resend's `bounce.type` is a FREE STRING (no enum). Map a case-insensitive
+ * substring of it to a provider-neutral {@link EmailEvent} bounce class. The raw
+ * Resend string is preserved in `bounce.code` so nothing is lost.
+ *
+ * - `permanent` → auto-suppress (the engine increments `bounceCount`).
+ * - `transient` → recorded as `email.bounced` but does NOT suppress.
+ * - `complaint` → immediate suppress via the complaint path.
+ * - `unknown`   → recorded, NEVER suppresses (conservative default).
+ */
+export function classifyResendBounce(type: string | undefined): BounceClass {
+  const t = (type ?? "").toLowerCase();
+  if (!t) return "unknown";
+  const has = (needle: string) => t.includes(needle.toLowerCase());
+
+  // Complaint/spam/abuse first — a "spam complaint" must never be read as a
+  // permanent bounce.
+  if (has("complaint") || has("spam") || has("abuse")) return "complaint";
+  if (
+    has("hardbounce") ||
+    has("hard_bounce") ||
+    has("permanent") ||
+    has("suppressedrecipient") ||
+    has("suppressed")
+  ) {
+    return "permanent";
+  }
+  if (
+    has("softbounce") ||
+    has("soft_bounce") ||
+    has("transient") ||
+    has("mailboxfull") ||
+    has("mailbox_full") ||
+    has("throttled") ||
+    has("undetermined")
+  ) {
+    return "transient";
+  }
+  return "unknown";
+}
+
+/**
+ * Adapt Resend's verbatim webhook payload into the provider-neutral
+ * {@link EmailEvent}. Maps `data.email_id` → `messageId`, `data.to` →
+ * `recipients`, `created_at` → `occurredAt`, `data.click` → `click`, and
+ * `data.bounce.{type,message}` → `bounce` (via {@link classifyResendBounce}).
+ * The untouched payload is preserved in `raw` as the deprecation escape hatch.
+ */
+export function toEmailEvent(raw: WebhookEvent): EmailEvent {
+  const occurredAt = raw.created_at ?? raw.data?.created_at ?? "";
+  const recipients = normalizeRecipients(
+    raw.data?.to as string | string[] | undefined,
+  );
+
+  const base = {
+    messageId: raw.data?.email_id ?? "",
+    recipients,
+    occurredAt,
+    raw,
+  };
+
+  switch (raw.type) {
+    case "email.bounced": {
+      const bounce = raw.data.bounce;
+      return {
+        ...base,
+        type: "email.bounced",
+        bounce: {
+          class: classifyResendBounce(bounce?.type),
+          code: bounce?.type ?? "",
+          ...(bounce?.message ? { reason: bounce.message } : {}),
+        },
+      };
+    }
+    case "email.complained":
+      return {
+        ...base,
+        type: "email.complained",
+        bounce: { class: "complaint", code: "complaint" },
+      };
+    case "email.clicked": {
+      const click = raw.data.click;
+      return {
+        ...base,
+        type: "email.clicked",
+        click: {
+          url: click?.link ?? "",
+          ...(click?.timestamp ? { at: click.timestamp } : {}),
+          ...(click?.ipAddress ? { ip: click.ipAddress } : {}),
+          ...(click?.userAgent ? { ua: click.userAgent } : {}),
+        },
+      };
+    }
+    default:
+      return { ...base, type: raw.type as EmailEventType };
+  }
+}
+
+/**
+ * Svix-verify Resend's webhook over the EXACT received payload bytes, then adapt
+ * it into the provider-neutral {@link EmailEvent}.
+ */
 export function verifyWebhook(opts: {
   payload: string;
   headers: Record<string, string>;
   signingSecret: string;
-}): WebhookEvent {
+}): EmailEvent {
   const svixId = opts.headers["svix-id"];
   const svixTimestamp = opts.headers["svix-timestamp"];
   const svixSignature = opts.headers["svix-signature"];
@@ -29,7 +147,7 @@ export function verifyWebhook(opts: {
       "svix-signature": svixSignature,
     }) as WebhookEvent;
 
-    return event;
+    return toEmailEvent(event);
   } catch (error) {
     throw new WebhookVerificationError(
       `Webhook verification failed: ${error instanceof Error ? error.message : "unknown error"}`,
@@ -44,14 +162,14 @@ export function createWebhookHandler(opts: {
   return async (
     payload: string,
     headers: Record<string, string>,
-  ): Promise<{ type: WebhookEventType; handled: boolean }> => {
+  ): Promise<{ type: EmailEventType; handled: boolean }> => {
     const event = verifyWebhook({
       payload,
       headers,
       signingSecret: opts.signingSecret,
     });
     const handler = opts.handlers[event.type] as
-      | ((event: WebhookEvent) => void | Promise<void>)
+      | ((event: EmailEvent) => void | Promise<void>)
       | undefined;
 
     if (handler) {
@@ -63,24 +181,15 @@ export function createWebhookHandler(opts: {
   };
 }
 
-export function parseWebhookEvent(payload: string): WebhookEvent {
+/** Parse an unsigned Resend payload into the neutral {@link EmailEvent}. */
+export function parseWebhookEvent(payload: string): EmailEvent {
   const parsed = JSON.parse(payload) as WebhookEvent;
 
-  const validTypes: WebhookEventType[] = [
-    "email.sent",
-    "email.delivered",
-    "email.bounced",
-    "email.complained",
-    "email.delivery_delayed",
-    "email.opened",
-    "email.clicked",
-  ];
-
-  if (!validTypes.includes(parsed.type)) {
+  if (!VALID_TYPES.includes(parsed.type as EmailEventType)) {
     throw new WebhookVerificationError(
-      `Unknown webhook event type: ${parsed.type}`,
+      `Unknown webhook event type: ${parsed.type as WebhookEventType}`,
     );
   }
 
-  return parsed;
+  return toEmailEvent(parsed);
 }