---
title: "nextmail live-events"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://nextmail.sh/docs/cli/reference/live-events"
area: "CLI"
category: "Reference"
---

# nextmail live-events

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `nextmail live-events stream`

Follow the mailbox as it changes

```bash
nextmail live-events stream [flags]
```

Opens the live event stream, `GET /live-events` as server-sent events, and yields one event per step for as long as you read it: `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 delivery of an email sent from an address moves on, with its `status`: `delivered`, `delivery_delayed`, `bounced`, `complained`, `failed`, `suppressed` or `cancelled`. Each event is `{ id, type, occurredAt, data }`, where `data.addresses` names the addresses it concerns and `threadId` and `messageId` the conversation and the message, where there is one. No content travels in an event, so read the conversation with `threads.get` or the message with `threads.getMessage` when you need it.

The stream never ends by itself. The server closes it after 30 minutes, when the credential stops being valid, or when the connection drops, and the generator opens it again and resumes where it left off through `Last-Event-ID`: at once after the server closes it, and with backoff after a failure. When the server can no longer replay from that point, which happens once the event is more than 10 minutes or 1,000 events back, the generator yields a `reset` event with `type: 'reset'` before the next events: anything may have changed in between, so list again what you keep in sync. Break out of the loop, or abort `options.signal`, to close it.

A key or an app limited to particular addresses gets only the events of the addresses it reaches, enforced on the server for every event.

Prints each event as one JSON object per line the moment it arrives, on a terminal, in a pipe and with `--json` alike, and keeps going until you press Ctrl+C. `--max <n>` stops after that many events.

- Scopes: `threads:read`.
- Needs a sign-in.

**Flags**

- `--types <a,b>` (repeatable): Only these kinds of event: `message.received`, `message.sent`, `thread.changed`, `thread.deleted` and `message.status_changed`. Left out, all of them. A `reset` is always delivered.
- `--address <value>`: Only the events of this address. One the key does not reach delivers nothing rather than failing.
- `--last-event-id <value>`: Resume after this event id, one an earlier stream yielded. Left out, the stream starts with what happens from now on.
- `--max <n>`: Stop after this many events.

**Examples**

```bash
nextmail live-events stream
```

With optional flags

```bash
nextmail live-events stream --types message.received
```

Wait for the next event, then stop

```bash
nextmail live-events stream --max 1
```

Write every event to a file as it arrives, one JSON object per line

```bash
nextmail live-events stream > live-events.ndjson
```

Also available in: API [`GET /live-events`](https://nextmail.sh/docs/api/reference/live-events#get-live-events); 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).