Skip to main content
The email event stream sends live project-scoped delivery and engagement events over Server-Sent Events (SSE).

1. Issue a stream token

Use an API key with emails:send:
The token expires after 60 seconds and is atomically consumed by the first stream connection. Issue it immediately before connecting, never persist it, and avoid recording the query string in access logs.

2. Open the stream

Each SSE message places a JSON object in the data field:
Possible type values are sent, delivered, bounced, complained, opened, clicked, and unsubscribed. The data map contains event-specific string values when available.

Reconnect and recovery

The token cannot be reused, so the browser’s default EventSource reconnect with the same URL cannot re-authenticate. When the stream closes, dispose of it, issue a new token, and create a new connection with capped backoff. The stream is live and does not accept Last-Event-ID. After a disconnect, reconcile authoritative history with GET /v1/projects/{projectId}/emails/{emailId}/events for emails you track. Use webhooks when delivery across client disconnects must be durable.
Authentication errors returned before the stream opens are application/problem+json. After it opens, handle disconnects through the SSE client’s network error path.