Event reference
The webhook event types, the envelope they share, and what each one means.
Every webhook event arrives in the same envelope:
{
"id": "evt_...",
"type": "email.received",
"created_at": "2026-09-01T10:31:04Z",
"space_id": null,
"data": { }
}id is stable across retries and replays — deduplicate on it. space_id is the space the resource is in, null for the workspace itself. data varies by type, and both SDKs discriminate on type so a type checker narrows it for you.
| Event | Fires when |
|---|---|
email.received |
Inbound mail arrives. |
email.sent |
A message is handed to the mail provider. |
email.delivered |
The receiving server accepted it. |
email.bounced |
Delivery failed. |
email.complained |
The recipient marked it as spam. |
email.failed |
The provider refused it before any attempt. |
email.unsubscribed |
The recipient opted out. |
email.opened |
An open was tracked. |
email.clicked |
A tracked link was clicked. |
Thread
| Event | Fires when |
|---|---|
thread.created |
A new conversation started. |
Domain
| Event | Fires when |
|---|---|
domain.verified |
The domain’s DKIM identity was verified. |
domain.lost |
A verified domain’s DKIM record stopped resolving. |
Mailbox
| Event | Fires when |
|---|---|
mailbox.connected |
A customer authorized a mailbox. |
mailbox.needs_reauth |
A mailbox’s authorization stopped working. |
mailbox.disconnected |
A mailbox was removed. |
Handle events in a worker
Verify and durably enqueue each event in your HTTP handler. In a worker, branch on event.type to select the appropriate application behavior:
| Type | Typical action |
|---|---|
email.received |
Load the message or thread and evaluate whether to respond |
email.bounced |
Record affected recipients and whether the failure is permanent |
email.failed |
Surface the provider’s reason; the message never went out |
email.complained |
Record the complaint and review the recipient’s suppression state |
email.unsubscribed |
Update the matching preference in your application |
mailbox.needs_reauth |
Ask the mailbox owner to reconnect |
Make each action recoverable and idempotent. Mark work complete after it succeeds. Unknown event types should not crash the handler; record the type for diagnosis and ignore it until the application supports it.
Verifying requests
How to authenticate each delivery before storing or processing it.