Email Events

Connect records an event each time something happens to an email. You can have events sent to your server as webhooks, or see them in an email’s timeline.

Event types

Type	When
email.queued	The email was accepted, or scheduled
email.sent	The email was handed to the recipient’s email server
email.delivered	The recipient’s email server accepted the email
email.bounced	The email bounced. reason.category is hard_bounce or soft_bounce
email.complained	The recipient marked the email as spam
email.failed	The email could not be sent or delivered. reason says why
email.opened	The email was opened for the first time (email sent with trackOpens only)
email.cancelled	A scheduled email was cancelled
suppression.created	An address was added to your suppression list, for example after a hard bounce, a complaint or an unsubscribe

A soft bounce can be followed by email.delivered if the recipient’s server accepts the email later.

Webhook payload

Every webhook is a POST with a JSON body. data is the email object as it was when the event happened:

{
  "id": "358120561368793088",
  "type": "email.delivered",
  "occurredAt": "2026-10-10T09:30:03Z",
  "apiVersion": "2026-10-01",
  "workspaceId": "301245883010879488",
  "data": {
    "id": "358120554712436736",
    "kind": "transactional",
    "sender": "hello@yourcompany.com",
    "recipient": "sam@example.com",
    "subject": "Your order has shipped",
    "content": { "html": null, "text": "Hi Sam, your order is on its way." },
    "status": "delivered",
    "reason": null,
    "clientReference": "order-991",
    "clientTag": null,
    "openCount": 0,
    "createdAt": "2026-10-10T09:30:00Z",
    "scheduledAt": null,
    "sentAt": "2026-10-10T09:30:01Z",
    "deliveredAt": "2026-10-10T09:30:03Z",
    "openedAt": null,
    "updatedAt": "2026-10-10T09:30:03Z"
  }
}

For suppression.created, data is the suppression, with email and scope set.

Each delivery has a Webhook-Id header that stays the same if we retry it. Use it to ignore a webhook you have already handled. Reply with any 2xx status to tell us you received it. Otherwise we retry.

Every webhook is signed. See Verifying webhooks.

Subscribe to email events

Create a webhook with the email events you want:

{
  "url": "https://yourcompany.com/webhooks/connect",
  "events": ["email.delivered", "email.bounced", "email.complained", "email.failed"]
}

The response includes the webhook’s id and its secret, which you use to verify webhooks.

Caution

The secret is only shown once, when you create the webhook. Store it somewhere safe.

API reference: POST /v2/webhooks