Webhooks

Webhooks push email lifecycle events to your endpoints as they happen. Create endpoints in the dashboard, choose which event types each one receives, and inspect every delivery (payload, response, attempts) in the per-endpoint delivery log.

Event typesCopy Anchor Link

Team-level events carry no email; data describes the team's standing instead:

On the Free plan, the Free teams you created share one daily cap and one bounce and complaint record: each of these events fires once for all of them, on one of the teams that sent, with the shared figures.

Audience events fire when a contact or the suppression list changes, whoever changed it. data carries the contact in Resend's shape — id, email, first_name, last_name, unsubscribed, created_at, updated_at — plus source: api, dashboard, hosted_page (the preference center) or one_click (an RFC 8058 header post). Of the events below, Resend emits contact.created, contact.updated, contact.deleted, suppression.added and suppression.removed; the rest are MillionSend extensions. MillionSend doesn't send Resend's contact.topics.updated: subscribe to contact.topic_opt_in and contact.topic_opt_out instead.

Scheduled, failed and suppressed emailCopy Anchor Link

Like every event about an email you send, these three carry email_id, from, to, subject and created_at, when the event happened.

{
  "type": "email.scheduled",
  "created_at": "2026-10-13T09:30:12.084Z",
  "data": {
    "email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
    "from": "Acme <hello@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-13T09:30:12.084Z"
  }
}

email.failed and email.suppressed fire once per email that ends failed or suppressed, and add an object that says why.

{
  "type": "email.failed",
  "created_at": "2026-10-13T10:00:02.317Z",
  "data": {
    "email_id": "3f7b2c71-5274-4246-82f3-57bc1563c276",
    "from": "Acme <billing@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your receipt",
    "created_at": "2026-10-13T10:00:02.317Z",
    "failed": {
      "reason": "domain_not_verified"
    }
  }
}

{
  "type": "email.suppressed",
  "created_at": "2026-10-14T09:30:00.912Z",
  "data": {
    "email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
    "from": "Acme <hello@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-14T09:30:00.912Z",
    "suppressed": {
      "type": "OnAccountSuppressionList",
      "message": "The recipient is on your suppression list.",
      "reason": "recipient_suppressed"
    }
  }
}

OnAccountSuppressionList is Resend's value; Unsubscribed and Ineligible are MillionSend's own.

• A POST /emails that the suppression list alone refuses with 422 all_recipients_suppressed keeps a suppressed email, which fires email.suppressed too; see Suppressions.
• Dropping only some recipients, at accept or when the email goes out, fires no email.suppressed: the email goes to the rest.
• Canceling a broadcast fires nothing for the emails it stops.

Received mailCopy Anchor Link

email.received carries Resend's metadata-only payload: no body, headers or attachment sizes, and from is the bare address. received_for lists the addresses at your domains the message was delivered to, Bcc recipients included. When a later delivery of the same message reaches more of your addresses, another email.received with the same email_id lists only those.

{
  "type": "email.received",
  "created_at": "2026-10-11T14:37:40.951Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "created_at": "2026-10-11T14:37:40.951Z",
    "from": "ada@example.org",
    "to": ["support@inbound.example.com"],
    "bcc": [],
    "cc": [],
    "received_for": ["support@inbound.example.com"],
    "message_id": "<CAF1x7Qm9@mail.example.org>",
    "subject": "Order #1042",
    "attachments": [
      {
        "id": "b344102e-962e-8943-aef6-271c7743e1dd",
        "filename": "invoice.pdf",
        "content_type": "application/pdf",
        "content_disposition": "attachment",
        "content_id": null
      }
    ]
  }
}

Inbox eventsCopy Anchor Link

Inboxes emit Resend's inbox.* events, plus two of MillionSend's own. They are opt-in: an endpoint gets them only by naming them, never through "all events".

• source is api (an API key or an MCP client), dashboard or system (mail arriving, sends, expiries). It is never agent.
• inbox is the inbox object, thread is { object, id, subject, folder, labels, read }, email a thread email and draft a draft. email and draft never carry html, text, extracted_text, codes or links: fetch the content with the API.
• The objects are taken when the event happens, not when it is delivered, so a quick second change doesn't rewrite the first event.
• Keys that don't apply are left out, never sent as null.

{
  "type": "inbox.email.received",
  "created_at": "2026-10-12T14:03:12.301Z",
  "data": {
    "source": "system",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147",
    "thread_id": "b9e1837b-c150-45c6-a055-73b02ec9f1dc",
    "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
    "thread": {
      "object": "inbox_thread",
      "id": "b9e1837b-c150-45c6-a055-73b02ec9f1dc",
      "subject": "Where is my order?",
      "folder": "inbox",
      "labels": [],
      "read": false
    },
    "email": {
      "id": "155252fb-e93e-45ee-8c19-5080a929c28b",
      "direction": "inbound",
      "from": "Maria Silva <maria@example.org>",
      "to": ["orders@inbound.example.com"],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "subject": "Where is my order?",
      "message_id": "<CAF7c1f0a2e5d3b@mail.example.org>",
      "attachments": [],
      "read": false,
      "received_at": "2026-10-12T14:03:11.229Z"
    }
  }
}

{
  "type": "inbox.email.quarantined",
  "created_at": "2026-10-12T14:05:40.017Z",
  "data": {
    "source": "system",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147",
    "thread_id": "6581da0f-148e-49c7-8ba3-b1c2fcabc5ef",
    "email_id": "6166ec82-4ea7-481a-a78d-42c6f84af265",
    "reason": "injection",
    "sender_trust": "external",
    "from": "billing@example.net",
    "subject": "Invoice overdue",
    "received_at": "2026-10-12T14:05:38.442Z"
  }
}

Only some inboxes. POST /webhooks and PATCH /webhooks/{id} take inbox_ids, up to 100 inboxes of the team (null, the default, means every inbox), and webhook objects return it. Such an endpoint gets inbox events and email.received only for those inboxes, so mail at a catch-all address doesn't reach it. In the dashboard: Only these inboxes.

Signatures (Standard Webhooks)Copy Anchor Link

Deliveries are signed following the Standard Webhooks spec — the same scheme Resend and Svix use, so existing verification code works unchanged.

Each endpoint has a whsec_... secret, shown once at creation. Every request carries:

webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>

The same three values are also sent as svix-id, svix-timestamp and svix-signature — the names Resend's docs tell receivers to read. One signature, two header names: a handler written for either family verifies without changes.

The signed content is {webhook-id}.{webhook-timestamp}.{raw body}. During a secret rotation the header carries two space-separated v1,… candidates, new secret first; a verifier accepts if any of them matches, which every Standard Webhooks library does. Verify with one, e.g. in Node:

import { Webhook } from "standardwebhooks";

const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});

Always verify against the raw request body, and reject stale timestamps.

Bringing your own secretCopy Anchor Link

POST /webhooks accepts an optional signing_secret: whsec_ followed by standard base64 of 24–64 bytes — the format Resend and Svix issue. Pass the secret your receiver already verifies with and the endpoint keeps working without a redeploy; omit it and MillionSend generates one. Anything else is rejected with 422 signing_secret must be whsec_ followed by base64 of 24-64 bytes.

To carry a secret over from another provider, read it from their API or dashboard (Resend returns it on GET /webhooks/{id}) and create the endpoint here with the same value:

curl -X POST "https://api.millionsend.com/webhooks" \
  -H "Authorization: Bearer ms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com/webhooks/email",
    "events": ["email.delivered", "email.bounced"],
    "signing_secret": "whsec_..."
  }'

The secret is returned on create and on GET /webhooks/{id}, never in list rows.

Rotating the secretCopy Anchor Link

POST /webhooks/{id}/rotate (or Rotate secret in the dashboard) mints a new secret, or takes the one in signing_secret, and returns it. For overlap_hours (default 24, up to 72) the previous secret keeps signing too: every delivery in that window carries both signatures, so a receiver holding either one verifies. Switch the receiver at any point in the window; after it only the new secret signs. 0 drops the old secret at once, for a leaked one. GET /webhooks/{id} reports the window's end as previous_secret_expires_at, and a second rotation inside the window replaces the previous secret.

curl -X POST "https://api.millionsend.com/webhooks/{id}/rotate" \
  -H "Authorization: Bearer ms_..." \
  -H "Content-Type: application/json" \
  -d '{ "overlap_hours": 24 }'
# → { "object": "webhook", "id": "...", "signing_secret": "whsec_...", "previous_secret_expires_at": "..." }

DeliveryCopy Anchor Link

A delivery is successful on any 2xx response. Each endpoint has its own queue, started in due order with up to eight requests in flight at up to 50 requests per second; a burst of events waits in the queue rather than hitting the receiver all at once.

A failed attempt (non-2xx, timeout, connection error) is retried on a fixed schedule: 5 s, 5 min, 30 min, 2 h, 5 h, 10 h — six attempts over about 18 hours. A 429 with a Retry-After header is honoured (up to an hour) and does not count as an attempt: it is the receiver asking for room, not failing. An event still undelivered 24 hours after it was queued is dropped as exhausted without another attempt.

After 20 consecutive exhausted deliveries the endpoint is disabled automatically and receives nothing further until you re-enable it from its page; events that happen in the meantime are not replayed. Team owners are emailed when an endpoint's deliveries start failing (the last ten settled deliveries all exhausted), when it is disabled, and — at most once a day — when its backlog is more than six hours old. The dashboard shows each endpoint's queue depth and how long its oldest delivery has been waiting.

A reconcile job re-arms queues lost to crashes, so delivery is at-least-once — make handlers idempotent, keyed on webhook-id. Delivery rows (payload, response, attempts) are kept for WEBHOOK_DELIVERY_RETENTION_DAYS (default 30) and then purged.

Subscribe each endpoint only to the events it needs. A full contact re-import emits nothing for contacts that did not change, but every new contact is one contact.created delivery — an endpoint subscribed to "all events" receives all of them.