@crvouga/mockingbird-service-resend

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Resend email API for test suites. Every send lands in an outbox that tests read (GET /__admin/outbox, and the links in each email). Idempotency-Key replays return the first send's id. Inbound emails are stored and announced with a Svix-signed email.received webhook, and the received-email endpoints serve their content and attachments. With --forward-to-inbox, every sent email is also copied into the Mailosaur emulator, so one inbox holds every code and link.

• Operation coverage: SUPPORT.md
• openapi.yaml is trimmed from Resend's published API reference to what [email protected] and our backend call.

Install

npm install -D @crvouga/mockingbird-service-resend

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-resend serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

[email protected] reads RESEND_BASE_URL once, when the module is first imported, so set it in the app's environment (or before the first import("resend") in a test). Set the app's RESEND_INBOUND_WEBHOOK_SECRET and pass the same whsec_… value as --webhook-secret.

npx mockingbird-resend serve --port 8794 \
  --webhook-url http://127.0.0.1:3000/messaging/inbound/email \
  --webhook-secret "$RESEND_INBOUND_WEBHOOK_SECRET" \
  --forward-to-inbox http://127.0.0.1:8793
RESEND_BASE_URL=http://127.0.0.1:8794 node app.js

import { createServer } from "@crvouga/mockingbird-service-resend/server"

// Test setup: the emulator, and the base URL the Resend SDK reads at import.
const emulator = await createServer()
process.env.RESEND_BASE_URL = emulator.url
const { Resend } = await import("resend")

// The app's own Resend call.
await new Resend("re_test").emails.send({
  from: "Acme <[email protected]>",
  to: ["[email protected]"],
  subject: "You're invited",
  html: '<a href="https://app.test/family/invitations/claim?token=abc">Join</a>',
})

// The test reads the mail back from the outbox.
const { messages } = await (await fetch(`${emulator.url}/__admin/[email protected]`)).json()
const { links } = await (await fetch(`${emulator.url}/__admin/outbox/${messages[0].id}/links`)).json()
// links[0] === "https://app.test/family/invitations/claim?token=abc"
await emulator.close()

The outbox is the assertion surface for every send. An idempotencyKey replay returns the first send's id and leaves one message in it:

import { createServer } from "@crvouga/mockingbird-service-resend/server"

const emulator = await createServer()
process.env.RESEND_BASE_URL = emulator.url
const { Resend } = await import("resend")

const resend = new Resend("re_test")
const email = { from: "[email protected]", to: ["[email protected]"], subject: "Hi", text: "Hello" }
const first = await resend.emails.send(email, { idempotencyKey: "invite-1" })
const retry = await resend.emails.send(email, { idempotencyKey: "invite-1" })
// retry.data?.id === first.data?.id

const sent = await (await fetch(`${emulator.url}/__admin/[email protected]`)).json()
// sent.messages.length === 1
await emulator.close()

Routes

Auth is Authorization: Bearer <key>; any key works; none is 401 missing_api_key.

SDK error mapping. [email protected] never throws: a non-2xx JSON body comes back verbatim as {data: null, error: {statusCode, name, message}}; a non-JSON body becomes {name: "application_error", message: "Internal server error. …"}; a dropped connection becomes {name: "application_error", message: "Unable to fetch data. The request could not be resolved."}. [email protected] also reads RESEND_BASE_URL at import and returns that JSON error object, but its client does not catch a non-JSON body or a dropped socket (those reject). It also has no idempotencyKey option; send the Idempotency-Key header yourself, as [email protected] does.

Webhooks

POST /__admin/inbound stores the email, then posts to every endpoint:

{"type": "email.received", "created_at": "…",
 "data": {"email_id": "…", "created_at": "…", "from": "…", "to": ["[email protected]"], "cc": [], "bcc": [],
          "subject": "…", "message_id": "<…>", "attachments": [{"id", "filename", "content_type", "content_disposition", "content_id"}]}}

Like Resend's, the body carries no text, html, headers or download URLs, so a receiver hydrates them through the received-email routes. Pass "inline": true to include them. Each delivery is signed the Svix way: svix-id, svix-timestamp (wall clock, even when the emulator clock moves), svix-signature: v1,<base64 HMAC-SHA256(secret bytes, "id.ts.body")>. The official svix Webhook.verify accepts them. Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). GET /__admin/webhooks, …/events, …/flush, …/:id/replay and PUT /__admin/webhook-endpoints (per-namespace receivers) come with the contract.

Admin (beyond the standard contract)

--forward-to-inbox <url> copies every accepted send (not replays) to the Mailosaur emulator's POST /__admin/ingest, under the same namespace name, and waits up to 2 s for it. A failing inbox never fails the send; it is counted in /__admin/forwarding. Map the same key to the same namespace on both emulators and a worker reads its forwarded mail through the Mailosaur SDK.

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): send_422 ({statusCode: 422, name: "validation_error", message}), send_429 (rate_limit_exceeded with retry-after and ratelimit-* headers), send_500 (internal_server_error), non_json_500 (an HTML 500 page), network_drop (the connection dies before acceptance, so nothing is stored), accepted_then_network_drop (the send is stored, then the connection dies before any response bytes; the same key replays), receiving_500 (the received-email routes answer 500), webhook_duplicate, webhook_reorder, webhook_drop.

Namespaces

new Resend(key) cannot add headers, so map API keys to namespaces: PUT /__admin/credentials {"credentials": {"<RESEND_API_KEY>": "<namespace>"}}. Also x-mockingbird-namespace, or a /__admin/ns/<name> prefix on RESEND_BASE_URL.

Deliberately not modelled

• Delivery itself: no SMTP, bounces, complaints, opens or clicks, and no email.sent / email.delivered webhooks. last_event is delivered at once (scheduled with scheduled_at, which is stored but never fires).
• Batch send, templates, domains, API keys, audiences, contacts and broadcasts (our code calls none).
• Attachment path URLs are not fetched; sent attachments keep metadata only.
• Rate limits, except through send_429.
• The idempotency window: keys never expire (Resend keeps them 24 h).

API

Part of mockingbird.