---
title: Event reference
description: The webhook event types, the envelope they share, and what each one means.
sidebar:
  label: Overview
  icon: list
---

Every webhook event arrives in the same envelope:

```json
{
  "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](/guides/spaces) 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.

## Email

| Event | Fires when |
| --- | --- |
| [`email.received`](/webhooks/events/email-received) | Inbound mail arrives. |
| [`email.sent`](/webhooks/events/email-sent) | A message is handed to the mail provider. |
| [`email.delivered`](/webhooks/events/email-delivered) | The receiving server accepted it. |
| [`email.bounced`](/webhooks/events/email-bounced) | Delivery failed. |
| [`email.complained`](/webhooks/events/email-complained) | The recipient marked it as spam. |
| [`email.failed`](/webhooks/events/email-failed) | The provider refused it before any attempt. |
| [`email.unsubscribed`](/webhooks/events/email-unsubscribed) | The recipient opted out. |
| [`email.opened`](/webhooks/events/email-opened) | An open was tracked. |
| [`email.clicked`](/webhooks/events/email-clicked) | A tracked link was clicked. |

## Thread

| Event | Fires when |
| --- | --- |
| [`thread.created`](/webhooks/events/thread-created) | A new conversation started. |

## Domain

| Event | Fires when |
| --- | --- |
| [`domain.verified`](/webhooks/events/domain-verified) | The domain’s DKIM identity was verified. |
| [`domain.lost`](/webhooks/events/domain-lost) | A verified domain's DKIM record stopped resolving. |

## Mailbox

| Event | Fires when |
| --- | --- |
| [`mailbox.connected`](/webhooks/events/mailbox-connected) | A customer authorized a mailbox. |
| [`mailbox.needs_reauth`](/webhooks/events/mailbox-needs-reauth) | A mailbox's authorization stopped working. |
| [`mailbox.disconnected`](/webhooks/events/mailbox-disconnected) | A mailbox was removed. |

## Handle events in a worker

[Verify and durably enqueue](/guides/production#receive-events-durably) 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](/webhooks/verifying)**

How to authenticate each delivery before storing or processing it.