# 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.

The envelope:

```text
{
  "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

| 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

email.sent payload:

```text
{
  "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

email.scheduled payload:

```text
{
  "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

email.delivered payload:

```text
{
  "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

email.delivery_delayed payload:

```text
{
  "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

email.bounced payload:

```text
{
  "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

email.complained payload:

```text
{
  "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

email.opened payload:

```text
{
  "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

email.clicked payload:

```text
{
  "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

email.failed payload:

```text
{
  "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

email.suppressed payload:

```text
{
  "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

email.canceled payload:

```text
{
  "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

domain.created payload:

```text
{
  "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

domain.updated payload:

```text
{
  "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

domain.deleted payload:

```text
{
  "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

suppression.added payload:

```text
{
  "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

suppression.removed payload:

```text
{
  "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

contact.created payload:

```text
{
  "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

contact.updated payload:

```text
{
  "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

contact.deleted payload:

```text
{
  "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

email.received payload:

```text
{
  "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

automation.run.started payload:

```text
{
  "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

automation.run.completed payload:

```text
{
  "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

automation.run.failed payload:

```text
{
  "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](https://www.rasket.com/docs/api-reference/webhooks), 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.