Webhook Payload

Primitive delivers inbound mail as an event in the email.* family. The most common is email.received; machine-generated mail (delivery failures, TLS and DMARC reports) is delivered under a more specific event type instead. All email.* events share the same payload shape, and the same shape is sent to self-hosted webhooks and hosted Primitive Functions.

The event name is delivered in the X-Webhook-Event request header, and the delivery id in X-Webhook-Id. Always read the event type from X-Webhook-Event (or the top-level event field) rather than assuming email.received. email.received is documented in full below; the other email.* events (next section) reuse the same fields, and the x402 payment and interaction events (at the end of this page) have their own payload shapes.

Email Event Types

Every inbound message is delivered under one of the email.* event types below. The type is resolved from the kind of message received: a delivery failure (DSN) arrives as email.bounced, an SMTP TLS report as email.tls_report, and so on. Anything that isn't one of these specialized kinds — ordinary mail, auto-replies, complaints — is delivered as email.received.

All email.* events use the same payload documented below. The email.bounced, email.tls_report, and email.dmarc_report types additionally carry a matching block under email.analysis (see Analysis) with the parsed report or bounce details. email.dmarc_failure carries no extra analysis block.

An endpoint receives only the event types it is subscribed to. Endpoints created before subscriptions existed, and endpoints that leave the subscription unset, receive every email.* event. To receive email.bounced (or any other specialized type) on a newer endpoint, subscribe it via the endpoint's rules.event_types. See Endpoints.

Top-Level Shape

This is the actual email.received payload shape Primitive sends to webhook endpoints and Primitive Functions.

{
  "id": "evt_0d4ce769a6f5822afa37417473d33ff8ae0254f280802d94f4eff284cde30567",
  "event": "email.received",
  "version": "2025-12-14",
  "delivery": {
    "endpoint_id": "ep_01HZYABCDEF1234567890",
    "attempt": 1,
    "attempted_at": "2026-01-01T00:00:05.000Z"
  },
  "email": {
    "id": "em_01HZYABCDEF1234567890",
    "received_at": "2026-01-01T00:00:00.000Z",
    "smtp": {
      "helo": "mail.example.com",
      "mail_from": "bounce@example.com",
      "rcpt_to": [
        "support@your-org.primitive.email"
      ]
    },
    "headers": {
      "message_id": "<message-id@example.com>",
      "subject": "Need help",
      "from": "Alice <alice@example.com>",
      "to": "Support <support@your-org.primitive.email>",
      "date": "Thu, 01 Jan 2026 00:00:00 +0000"
    },
    "content": {
      "raw": {
        "included": true,
        "encoding": "base64",
        "max_inline_bytes": 262144,
        "size_bytes": 257,
        "sha256": "8bf8f3c56544d3e56ac84f414754674d51c55d6504d847a9868af46ab65d4f0f",
        "data": "RnJvbTogQWxpY2UgPGFsaWNlQGV4YW1wbGUuY29tPg0KVG86IFN1cHBvcnQgPHN1cHBvcnRAeW91ci1vcmcucHJpbWl0aXZlLmVtYWlsPg0KQ2M6IEJvYiA8Ym9iQGV4YW1wbGUuY29tPg0KUmVwbHktVG86IEFsaWNlIFN1cHBvcnQgPHJlcGx5QGV4YW1wbGUuY29tPg0KU3ViamVjdDogTmVlZCBoZWxwDQpEYXRlOiBUaHUsIDAxIEphbiAyMDI2IDAwOjAwOjAwICswMDAwDQpNZXNzYWdlLUlEOiA8bWVzc2FnZS1pZEBleGFtcGxlLmNvbT4NCg0KSGVsbG8="
      },
      "download": {
        "url": "https://api.primitive.dev/v1/emails/em_01HZYABCDEF1234567890/raw?token=download-token",
        "expires_at": "2026-01-02T00:00:00.000Z"
      }
    },
    "parsed": {
      "status": "complete",
      "error": null,
      "body_text": "Hello",
      "body_html": "<p>Hello</p>",
      "reply_to": [
        {
          "address": "reply@example.com",
          "name": "Alice Support"
        }
      ],
      "cc": [
        {
          "address": "bob@example.com",
          "name": "Bob"
        }
      ],
      "bcc": null,
      "to_addresses": [
        {
          "address": "support@your-org.primitive.email",
          "name": "Support"
        }
      ],
      "in_reply_to": [
        "<previous@example.com>"
      ],
      "references": [
        "<root@example.com>",
        "<previous@example.com>"
      ],
      "attachments": [
        {
          "filename": "invoice.pdf",
          "content_type": "application/pdf",
          "size_bytes": 24576,
          "sha256": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
          "part_index": 0,
          "tar_path": "0_invoice.pdf"
        }
      ],
      "attachments_download_url": "https://api.primitive.dev/v1/emails/em_01HZYABCDEF1234567890/attachments.tar.gz?token=download-token"
    },
    "analysis": {
      "spamassassin": {
        "score": 0.1
      },
      "sender": {
        "authenticated": true,
        "basis": "dmarc_aligned",
        "reasons": [
          "DKIM signature aligned with the From domain"
        ]
      }
    },
    "auth": {
      "spf": "pass",
      "dmarc": "pass",
      "dmarcPolicy": "reject",
      "dmarcFromDomain": "example.com",
      "dmarcSpfAligned": false,
      "dmarcDkimAligned": true,
      "dmarcSpfStrict": false,
      "dmarcDkimStrict": false,
      "dkimSignatures": [
        {
          "domain": "example.com",
          "selector": "default",
          "result": "pass",
          "aligned": true,
          "keyBits": 2048,
          "algo": "rsa-sha256"
        }
      ]
    },
    "thread_id": "thr_01HZYABCDEF1234567890"
  }
}

Stable Identifiers

The top-level id is stable across retries and manual replays to the same endpoint. Use it for webhook dedupe.

email.id is the stored email id. Use it with REST endpoints such as /v1/emails/{id}, /v1/emails/{id}/replay, and /v1/emails/{id}/reply.

Delivery Metadata

The delivery object records the delivery attempt counter and endpoint information. delivery.attempt is a delivery-call counter; in the current delivery path it is 1 on the first delivery to an endpoint. Do not rely on it to distinguish a first delivery from a retry — the top-level id is preserved across retries and re-deliveries, so use it (not attempt) for dedupe.

Parsed Content

When parsing succeeds, email.parsed.status is complete and body fields are available. Large raw content and attachments can be stored separately and exposed through signed download URLs.

If parsing fails, email.parsed.status is failed, email.parsed.error is populated, body and address fields are null, and attachments are empty or partial metadata only.

Headers

Headers preserve the important RFC 5322 fields needed for audit trails. Use email.headers.message_id, email.parsed.in_reply_to, email.parsed.references, and email.thread_id when building threading logic.

Raw Content

Small raw emails are included inline at email.content.raw.data as base64. If the raw email is larger than email.content.raw.max_inline_bytes, email.content.raw.included is false and the raw content must be fetched from email.content.download.url before expires_at.

Attachments are listed as metadata in email.parsed.attachments. Download the files from email.parsed.attachments_download_url when it is not null.

Auth And Analysis

email.auth contains SPF, DMARC, and DKIM results from the inbound message. email.analysis.sender is Primitive's sender authentication verdict derived from those auth fields. email.analysis.spamassassin is present when spam scoring ran. email.analysis.forward is optional; in managed Primitive webhook deliveries it is currently included only when forward analysis detects forwarded content.

Specialized event types attach an additional block under email.analysis with the parsed details: email.analysis.bounce on an email.bounced event (the classified delivery failure), email.analysis.tls_report on an email.tls_report event (the parsed RFC 8460 report), and email.analysis.dmarc_report on an email.dmarc_report event (the parsed RFC 7489 aggregate report). Each is present only when the corresponding report or bounce parsed successfully.

Field Reference

These descriptions are sourced from the webhook JSON schema used by the SDK, with the managed email.analysis.sender extension documented from the webhook delivery implementation. Required means required when its parent object or union variant is present.

Top Level

Delivery

Routing

Present only when recipient routing is enabled for your organization; omitted otherwise. It is the same decision recorded on the email and returned by /v1/routes/simulate, so you can see why a message reached this endpoint without a separate call. Only outcome is guaranteed to be present; treat the other fields as optional.

Email And SMTP

Raw Content

Parsed Content

Auth

Analysis

x402 Payment And Interaction Events

x402 settlements deliver their own events, separate from email.received. The event name is in the X-Webhook-Event header. Subscribe an endpoint to these names (or accept all events) to receive them. x402 is in an invite-only soft launch; see Collecting Payments and x402 over Email.

Payment events

payment.settled and payment.failed fire for BOTH the synthetic API pay flow and the email-native settle flow, with an identical payload shape. For email-native settlements payer_org is null because the payer is off-net.

The payee (the org that issued the challenge and receives the funds) always gets the event, with direction set to received. When the payer is also an on-net org (the synthetic API pay flow, where payer_org is non-null), that org ALSO gets its own copy of the same outcome, with direction set to sent. This gives an org that auto-pays a challenge an asynchronous settlement channel of its own, so it can reconcile a payment it made without relying on the synchronous response of the pay call. When the payer is off-net (email-native settlements), only the payee's received event is emitted.

payment.settled as seen by the payee (direction: "received"):

{
  "type": "payment.settled",
  "challenge_id": "11111111-1111-4111-8111-111111111111",
  "network": "base-sepolia",
  "amount": "10000",
  "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "payer_org": "22222222-2222-4222-8222-222222222222",
  "direction": "received",
  "settle_tx": "0x..."
}

The same settlement as seen by the on-net payer (direction: "sent"):

{
  "type": "payment.settled",
  "challenge_id": "11111111-1111-4111-8111-111111111111",
  "network": "base-sepolia",
  "amount": "10000",
  "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "payer_org": "22222222-2222-4222-8222-222222222222",
  "direction": "sent",
  "settle_tx": "0x..."
}

payment.failed carries failure_reason instead of settle_tx, and likewise reaches both sides when the payer is on-net:

{
  "type": "payment.failed",
  "challenge_id": "11111111-1111-4111-8111-111111111111",
  "network": "base-sepolia",
  "amount": "10000",
  "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "payer_org": null,
  "direction": "received",
  "failure_reason": "settle_daily_cap_exceeded"
}

Interaction events (email-native)

Each accepted step of an email-native x402 interaction also emits a protocol-specific interaction.x402.* event: interaction.x402.settled for a receipt step, interaction.x402.rejected for a reject, plus interaction.x402.challenge, interaction.x402.payment, interaction.x402.declined, interaction.x402.expired, and interaction.x402.verify_timeout for the other steps. The payload is a snapshot of the interaction at that step:

{
  "interaction": {
    "id": "...",
    "wire_id": "<uuid>@agent.payee.example",
    "protocol": "x402.payment",
    "protocol_version": 1,
    "state": "completed",
    "role": "initiator",
    "awaiting": null,
    "counterparty_address": "wallet@agent.payer.example",
    "counterparty_domain": "agent.payer.example",
    "our_address": "billing@agent.payee.example",
    "step": "receipt"
  }
}

A settled email-native payment therefore delivers both an interaction.x402.settled event (the step) and a payment.settled event (the uniform settlement notification); a rejected one delivers interaction.x402.rejected and payment.failed. They complement each other: subscribe to payment.* for a uniform settlement signal across both rails, or to interaction.x402.* for step-level detail.

Security

Every webhook includes a Primitive-Signature header. Verify it before trusting the payload. See Signature Verification.