GuidesEvents

Events

Every event a webhook can deliver, with one real payload each. The envelope is the same for all of them; only data changes.

The envelope

Three keys, always. type is the event, created_at is when it happened — not when we delivered it — and data is the subject.

{
  "type": "email.delivered",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {}
}

For an email.* event, data always carries email_id, from, to, subject, message_id and the email's own created_at. tags and headers appear only when the send had them. Some types add one more object, named in the table below. For a contact.* event, data is the contact: id, email, first_name, last_name, unsubscribed, created_at, updated_at and segment_ids.

to lists the recipients this event is about. For a bounce, a complaint or a delivery that is the affected addresses only, not everyone the message went to.

Every type

Every event type, what it adds to data, and what it means
Type	Adds	Means
`email.sent`	—	We handed the message to the mail provider.
`email.scheduled`	—	A send with `scheduled_at` was accepted and is waiting.
`email.delivered`	—	A receiving mail server accepted the message.
`email.delivery_delayed`	`delay`	A receiver deferred the message. It has not been rejected.
`email.bounced`	`bounce`	A receiver rejected it. A permanent bounce also adds the address to suppressions.
`email.complained`	—	A recipient reported the message as spam. The address is suppressed.
`email.opened`	`open`	A tracking pixel was loaded. Requires open tracking on the sending domain.
`email.clicked`	`click`	A tracked link was followed. Requires click tracking on the sending domain.
`email.failed`	`failed`	We could not send it. `failed.reason` says why.
`email.suppressed`	`suppressed`	The send was skipped because the address was already on your list.
`email.canceled`	—	A scheduled send was cancelled before it went out.
`domain.created`	—	A domain was added, or arrived on your team through a claim.
`domain.updated`	—	A domain's settings or record statuses changed.
`domain.deleted`	—	A domain was removed, or left your team through someone else's claim.
`suppression.added`	—	An address was added to the suppression list.
`suppression.removed`	—	An address was taken off it.
`contact.created`	—	A contact was added through the API. An import sends none of these.
`contact.updated`	—	A contact's fields or properties changed through the API or an automation's update step. Topic and segment changes do not send one.
`contact.deleted`	—	A contact was erased. `data` is the contact as it was.
`email.received`	—	Mail arrived at one of your receiving addresses. Attachments are listed without URLs; fetch each one from the API.
`automation.run.started`	—	An automation enrolled a contact and the run began.
`automation.run.completed`	—	A run reached the end of its graph.
`automation.run.failed`	—	A run ended without finishing. `error.reason` says why, and covers a cancelled or stopped run too.

The payloads

One example per type, folded away so the page stays readable. Each is the shape we send; the values are illustrative.

email.sent

{
  "type": "email.sent",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ]
  }
}

email.scheduled

{
  "type": "email.scheduled",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ]
  }
}

email.delivered

{
  "type": "email.delivered",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ]
  }
}

email.delivery_delayed

{
  "type": "email.delivery_delayed",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ],
    "delay": {
      "type": "MailboxFull",
      "expirationTime": "2026-09-10T10:16:44.902Z",
      "delayedRecipients": [
        {
          "emailAddress": "ronald.williams@example.com",
          "status": "4.2.2",
          "diagnosticCode": "smtp; 452 4.2.2 Mailbox full"
        }
      ]
    }
  }
}

email.bounced

{
  "type": "email.bounced",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ],
    "bounce": {
      "type": "Permanent",
      "subType": "General",
      "message": "smtp; 550 5.1.1 The email account that you tried to reach does not exist.",
      "diagnosticCode": ["smtp; 550 5.1.1 user unknown"]
    }
  }
}

email.complained

{
  "type": "email.complained",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ]
  }
}

email.opened

{
  "type": "email.opened",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ],
    "open": {
      "ipAddress": "66.249.84.201",
      "timestamp": "2026-09-09T10:16:44.902Z",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (via ggpht.com GoogleImageProxy)"
    }
  }
}

email.clicked

{
  "type": "email.clicked",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ],
    "click": {
      "ipAddress": "203.0.113.42",
      "link": "https://acme.example/orders/1042",
      "timestamp": "2026-09-09T10:16:44.902Z",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
    }
  }
}

email.failed

{
  "type": "email.failed",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ],
    "failed": {
      "reason": "ses_rejected"
    }
  }
}

email.suppressed

{
  "type": "email.suppressed",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ],
    "suppressed": {
      "reason": "previous_bounce",
      "type": "Suppressed",
      "message": "The address is on this team's suppression list.",
      "diagnosticCode": ["smtp; 550 5.1.1 user unknown"]
    }
  }
}

email.canceled

{
  "type": "email.canceled",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Acme <orders@send.acme.example>",
    "to": ["ronald.williams@example.com"],
    "subject": "Your order has shipped",
    "message_id": "<01000199a3c4d5e6-7f8a9b0c@send.acme.example>",
    "created_at": "2026-09-09T10:14:02.118Z",
    "tags": {
      "order": "1042"
    },
    "headers": [
      {
        "name": "X-Entity-Ref-ID",
        "value": "1042"
      }
    ]
  }
}

domain.created

{
  "type": "domain.created",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "d91a7b60-1a5f-4a2e-9d1b-0d9f2c7a1e34",
    "name": "send.acme.example",
    "status": "pending",
    "created_at": "2026-09-09T09:02:44.301Z",
    "region": "eu-west-1",
    "records": [
      {
        "record": "SPF",
        "name": "rasket",
        "value": "eu1.rasket.net",
        "type": "CNAME",
        "ttl": "Auto",
        "status": "verified"
      },
      {
        "record": "DKIM",
        "name": "rasket._domainkey",
        "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…",
        "type": "TXT",
        "ttl": "Auto",
        "status": "verified"
      },
      {
        "record": "Tracking",
        "name": "links",
        "value": "links1.rasket-dns.com",
        "type": "CNAME",
        "ttl": "Auto",
        "status": "not_started"
      }
    ]
  }
}

domain.updated

{
  "type": "domain.updated",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "d91a7b60-1a5f-4a2e-9d1b-0d9f2c7a1e34",
    "name": "send.acme.example",
    "status": "verified",
    "created_at": "2026-09-09T09:02:44.301Z",
    "region": "eu-west-1",
    "records": [
      {
        "record": "SPF",
        "name": "rasket",
        "value": "eu1.rasket.net",
        "type": "CNAME",
        "ttl": "Auto",
        "status": "verified"
      },
      {
        "record": "DKIM",
        "name": "rasket._domainkey",
        "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…",
        "type": "TXT",
        "ttl": "Auto",
        "status": "verified"
      },
      {
        "record": "Tracking",
        "name": "links",
        "value": "links1.rasket-dns.com",
        "type": "CNAME",
        "ttl": "Auto",
        "status": "not_started"
      }
    ]
  }
}

domain.deleted

{
  "type": "domain.deleted",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "d91a7b60-1a5f-4a2e-9d1b-0d9f2c7a1e34",
    "name": "send.acme.example",
    "status": "verified",
    "created_at": "2026-09-09T09:02:44.301Z",
    "region": "eu-west-1",
    "records": [
      {
        "record": "SPF",
        "name": "rasket",
        "value": "eu1.rasket.net",
        "type": "CNAME",
        "ttl": "Auto",
        "status": "verified"
      },
      {
        "record": "DKIM",
        "name": "rasket._domainkey",
        "value": "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…",
        "type": "TXT",
        "ttl": "Auto",
        "status": "verified"
      },
      {
        "record": "Tracking",
        "name": "links",
        "value": "links1.rasket-dns.com",
        "type": "CNAME",
        "ttl": "Auto",
        "status": "not_started"
      }
    ]
  }
}

suppression.added

{
  "type": "suppression.added",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "2c9a7f10-b4e8-4d61-8a3c-5f7b9e1d2a06",
    "email": "ronald.williams@example.com",
    "origin": "bounce",
    "source_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "created_at": "2026-09-09T10:16:44.902Z"
  }
}

suppression.removed

{
  "type": "suppression.removed",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "2c9a7f10-b4e8-4d61-8a3c-5f7b9e1d2a06",
    "email": "ronald.williams@example.com",
    "origin": "bounce",
    "source_id": null,
    "created_at": "2026-09-09T10:16:44.902Z"
  }
}

contact.created

{
  "type": "contact.created",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "email": "ronald.williams@example.com",
    "first_name": "Ronald",
    "last_name": "Williams",
    "unsubscribed": false,
    "created_at": "2026-09-08T22:22:17.595Z",
    "updated_at": "2026-09-08T22:22:17.595Z",
    "segment_ids": []
  }
}

contact.updated

{
  "type": "contact.updated",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "email": "ronald.williams@example.com",
    "first_name": "Ronald",
    "last_name": null,
    "unsubscribed": true,
    "created_at": "2026-09-08T22:22:17.595Z",
    "updated_at": "2026-09-09T10:16:44.902Z",
    "segment_ids": ["78261eea-8f8b-4381-83c6-79fa7120f1cf"]
  }
}

contact.deleted

{
  "type": "contact.deleted",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "email": "ronald.williams@example.com",
    "first_name": "Ronald",
    "last_name": null,
    "unsubscribed": true,
    "created_at": "2026-09-08T22:22:17.595Z",
    "updated_at": "2026-09-08T22:22:17.595Z",
    "segment_ids": []
  }
}

email.received

{
  "type": "email.received",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "created_at": "2026-09-09T10:16:44.902Z",
    "from": "Ronald Williams <ronald.williams@example.com>",
    "to": ["support@inbound.acme.example"],
    "subject": "Order #1042 arrived damaged",
    "message_id": "<CAF1042.damaged@mail.example.com>",
    "bcc": [],
    "cc": ["billing@example.com"],
    "received_for": ["support@inbound.acme.example"],
    "attachments": [
      {
        "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
        "filename": "photo.png",
        "content_type": "image/png",
        "content_disposition": "inline",
        "content_id": "photo-1042@example.com"
      },
      {
        "id": "d91a7b60-1a5f-4a2e-9d1b-0d9f2c7a1e34",
        "filename": "damage-report.pdf",
        "content_type": "application/pdf",
        "content_disposition": "attachment"
      }
    ]
  }
}

automation.run.started

{
  "type": "automation.run.started",
  "created_at": "2026-09-09T10:14:02.118Z",
  "data": {
    "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e02",
    "automation_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e01",
    "automation_version_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e03",
    "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "status": "running",
    "trigger": {
      "event_name": "trial.started",
      "event_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e06"
    },
    "current_step_key": null,
    "started_at": "2026-09-09T10:14:02.118Z",
    "completed_at": null,
    "created_at": "2026-09-09T10:14:02.118Z",
    "error": null
  }
}

automation.run.completed

{
  "type": "automation.run.completed",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e02",
    "automation_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e01",
    "automation_version_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e03",
    "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "status": "completed",
    "trigger": {
      "event_name": "trial.started",
      "event_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e06"
    },
    "current_step_key": null,
    "started_at": "2026-09-09T10:14:02.118Z",
    "completed_at": "2026-09-09T10:16:44.902Z",
    "created_at": "2026-09-09T10:14:02.118Z",
    "error": null
  }
}

automation.run.failed

{
  "type": "automation.run.failed",
  "created_at": "2026-09-09T10:16:44.902Z",
  "data": {
    "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e02",
    "automation_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e01",
    "automation_version_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e03",
    "contact_id": "e169aa45-1ecf-4183-9955-b1499d5701d3",
    "status": "failed",
    "trigger": {
      "event_name": "trial.started",
      "event_id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5e06"
    },
    "current_step_key": null,
    "started_at": null,
    "completed_at": "2026-09-09T10:16:44.902Z",
    "created_at": "2026-09-09T10:14:02.118Z",
    "error": {
      "reason": "automation_quota_reached"
    }
  }
}

Subscribing

Pick the types you want when you create a webhook endpoint, on the webhooks reference, which is also where signature verification, the retry schedule and replay live.

Events are not ordered. An email.delivered can arrive before the email.sent for the same message.
Dedupe on the svix-id header, which is stable across retries and replays. The payload has no id of its own.