Email delivery webhooks

// Every webhook POST body has this shape:
{
  "id": "evt_01j9abc123def456",          // unique event ID — dedupe on this
  "type": "email.delivered",             // event type
  "created_at": "2026-06-30T12:00:00.000Z",  // ISO 8601 timestamp
  "data": {
    "email_id": "jn7abc123def456",      // the email this event belongs to
    "from": "hello@mail.acme.com",
    "to": ["alice@example.com"],
    "subject": "Your receipt",
    "tags": [{ "name": "category", "value": "receipt" }]
  }
}

// email.bounced — data carries the affected recipient and reason:
{
  "id": "evt_01j9xyz789ghi012",
  "type": "email.bounced",
  "created_at": "2026-06-30T12:00:02.000Z",
  "data": {
    "email_id": "jn7abc123def456",
    "from": "hello@mail.acme.com",
    "to": ["alice@example.com"],
    "subject": "Your receipt",
    "tags": [],
    "recipient": "alice@example.com",   // the (first) address that bounced/complained
    "reason": "hard_bounce",             // "hard_bounce" | "complaint" — why it is now suppressed
    "recipients": [                      // every affected address — one event can name several
      { "address": "alice@example.com", "reason": "hard_bounce" }
    ]
  }
}

// email.complained has the same shape — recipient is who filed the complaint.
// `reason` is the suppression reason, not the mailbox provider's diagnostic;
// GET /v1/emails/:id carries that on its bounce event.

import { constructWebhookEvent } from "yourmail";

// In your handler — pass the RAW request body (a string or Buffer), not a
// parsed object. Throws if the signature doesn't hold, so nothing below runs
// on a forged event.
let event;
try {
  event = await constructWebhookEvent({
    // Rotating? Pass [newSecret, oldSecret] until the new one is deployed —
    // rotation in the dashboard is a hard cut.
    secret: process.env.YOURMAIL_WEBHOOK_SECRET!,
    header: req.headers["yourmail-signature"],
    payload: rawBody,
  });
} catch {
  return res.status(400).end();
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyYourMailWebhook(
  secret: string,
  header: string,        // the yourmail-signature header value
  rawBody: string,       // the un-parsed request body string
): boolean {
  // Header format: t=<unix_timestamp>,v1=<hmac_hex>
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=") as [string, string]),
  );
  const timestamp = parts["t"];
  const signature = parts["v1"];
  if (!timestamp || !signature) return false;

  // Reject anything older (or newer) than five minutes. Without this, a
  // captured request replays forever — the signature never expires by itself.
  // The SDK helper applies the same 300-second window.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  // Use a constant-time comparison to prevent timing attacks.
  return expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

// app/api/webhooks/yourmail/route.ts  (Next.js App Router)
import { constructWebhookEvent, type WebhookEvent } from "yourmail";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  let event: WebhookEvent;
  try {
    event = await constructWebhookEvent({
      secret: process.env.YOURMAIL_WEBHOOK_SECRET!,
      header: req.headers.get("yourmail-signature"),
      payload: await req.text(),
    });
  } catch {
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  switch (event.type) {
    case "email.delivered":
      // mark order as sent in your DB
      break;
    case "email.bounced":
      // suppress or notify the recipient
      break;
    case "email.complained":
      // unsubscribe the recipient
      break;
  }

  return NextResponse.json({ received: true });
}