---
title: "Live events"
description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with."
url: "https://nextmail.sh/docs/api/reference/live-events"
area: "API"
category: "Reference"
---

# Live events

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

## Operations

Follow the mailbox as it changes, over one long-lived server-sent event stream, and wait for a message to arrive.

### `GET /live-events`

Stream mailbox events as they happen

Holds the response open as `text/event-stream` and sends one event each time the mailbox changes, so a program stays in sync without polling. Every event is an SSE message whose `event` is its type, whose `id` is its id and whose `data` is the event as JSON (`LiveEvent`): `message.received` when a message is filed for an address, `message.sent` when a message sent from an address is filed in its Sent folder, `thread.changed` when a conversation gains or loses labels (read, starred, archived, moved, snoozed or labelled), `thread.deleted` when one is deleted for good, and `message.status_changed` when the receiving servers report on a sent email: delivered, delayed, bounced, complained of, failed, suppressed or cancelled. Events name the addresses, the conversation and the message they concern and carry no content: read it with `GET /threads/{id}` or `GET /threads/{id}/messages/{messageId}`.

The stream starts with `retry: 3000`, then a `ready` event whose data is `{ cursor, resumed }`. Pass the id of the last event you handled as the `Last-Event-ID` header (or the `lastEventId` query parameter) and the events after it are replayed first, for as long as it is at most 10 minutes and 1000 events back. When it is older, or unknown, a `reset` event comes first, with `{ reason, cursor }` (`expired` or `unknown`): list again what you keep in sync, then carry on from the stream. A comment line keeps the connection open every 25 seconds, and carries an `id` when events you filtered out moved the cursor on. The server ends every stream after 30 minutes, and when the credential stops being valid, with an `end` event whose `reason` is `lifetime`, `credential` or `unavailable`: open it again with `Last-Event-ID`, as the SDKs do by themselves.

A key, an app or a session holds at most 5 open streams and a workspace at most 50. A key or an app limited to particular addresses gets only the events of the addresses it reaches, checked on the server for every event, and an address it does not reach delivers nothing rather than failing. The credential is checked again at most once a minute while events flow, so a revoked key stops receiving within a minute.

Requires the `threads:read` scope.

- Scopes: `threads:read`.

**Query parameters**

- `types` (`string`, up to 200 characters): Only these kinds of event, separated by commas: `message.received`, `message.sent`, `thread.changed`, `thread.deleted`, `message.status_changed`. Left out, all of them. `ready`, `reset` and `end` always come.
- `address` (`string`, 3 to 320 characters): Only the events of this address. One the key does not reach delivers nothing rather than failing.
- `lastEventId` (`string`, up to 32 characters): Resume after this event id, for clients such as a browser `EventSource` that cannot set the `Last-Event-ID` header on the first request. The header wins when both are sent.

**Headers**

- `Last-Event-ID` (`string`, up to 32 characters): Resume after this event id: the `id` of the last event you handled.

**Returns**

- `200` `LiveEventStream` (`text/event-stream`): The open stream, as server-sent events. Each `data` line is a `LiveEvent`, or the payload of a `ready`, `reset` or `end` event.

**Errors**

- `429`: `too_many_streams`: this credential already holds 5 open streams, or the workspace 50. `rate_limited`: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in `Retry-After`.
- `503`: `live_events_unavailable`: the stream could not be opened just now. Try again shortly.
- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors).

Also available in: TypeScript [`liveEvents.stream()`](https://nextmail.sh/docs/sdk/reference/live-events#stream); Python [`live_events.stream()`](https://nextmail.sh/docs/python/reference/live-events#stream); Ruby [`live_events.stream`](https://nextmail.sh/docs/ruby/reference/live-events#stream); PHP [`liveEvents->stream`](https://nextmail.sh/docs/php/reference/live-events#stream); Go [`LiveEvents.Stream`](https://nextmail.sh/docs/go/reference/live-events#stream); Java [`liveEvents().stream`](https://nextmail.sh/docs/java/reference/live-events#stream); C# [`LiveEvents.StreamAsync`](https://nextmail.sh/docs/csharp/reference/live-events#stream); CLI [`nextmail live-events stream`](https://nextmail.sh/docs/cli/reference/live-events#live-events-stream).

### Objects

#### `LiveEventStream`

`string`

A `text/event-stream` body. Events whose `event` is one of the `LiveEvent` types carry a `LiveEvent` as JSON in `data`; `ready` carries `LiveStreamReady`, `reset` carries `LiveStreamReset` and `end` carries `LiveStreamEnd`. Lines starting with `:` are keepalive comments.