## Events Commands

### `events get`
Get event.

One event of the log. An event the credential may not read (see GET /v0/events) is a 404, like one outside its scope.

Requires the metrics_read permission.

#### Shell Command
```
machinemail events get <event-id> [flags]
```

#### Arguments
| Field        | Description               |
|--------------|---------------------------|
| `<event-id>` | Required; ID of the event (evt_...). |

#### Flags
| Field                 | Description           |
|-----------------------|-----------------------|
| `--inbox <inbox-id>` | Only this inbox.      |
| `--pod <pod-id>`     | Only this pod.        |

#### Examples
```
machinemail events get evt_01m4g0d4n60000v8b2c6k3y7zd
machinemail events get evt_01m4g0d4n60000v8b2c6k3y7zd --inbox agent@machinemail.dev
```

#### API
- [`GET /v0/events/{event_id}`](/content/docs/reference/api/events#get-event/index.html)

### `events list`
List events.

Also: `machinemail events ls`.

The replayable event log, newest first. Pass `--after` (an event ID or a time) to read forward from a point, oldest first. Events are kept without a retention limit. Only the events the credential may read are listed, as on the live streams: message.* needs message_read, inbox.* inbox_read, domain.* domain_read, draft.* draft_read, webhook.test webhook_read, and the audit events (agent registrations, members) metrics_read.  —event-types cannot add others.

Requires the metrics_read permission.

#### Shell Command
```
machinemail events list [flags]
```

#### Flags
| Field                 | Description              |
|-----------------------|--------------------------|
| `--inbox <inbox-id>` | Only this inbox.         |
| `--pod <pod-id>`     | Only this pod.           |
| `--limit <n>`        | Maximum number of items to return. Default 50, maximum 500; larger values are capped. |
| `--page-token <value>` | next_page_token from the previous page. |
| `--ascending`        | Sort oldest first. Defaults to true when `--after` is set. |
| `--after <time>`     | Returns only events after a specified event ID or time. |
| `--before <time>`    | Only events created before this time. |
| `-e, --event-types`  | Only these event types (repeat parameter or comma-separate). Omit for every type. |
| `--all`              | Follow next_page_token and return every page. |

#### Examples
```
machinemail events list
machinemail events list --inbox agent@machinemail.dev
machinemail events list --all --json | jq '.events | length'
```

#### API
- [`GET /v0/events`](/content/docs/reference/api/events#list-events/index.html)

### `events stream`
Stream events as they happen (server-sent events).

Server-Sent Events of everything in the credential scope that its permissions allow, narrowed by the query filters.

Requires the metrics_read permission.

#### Shell Command
```
machinemail events stream [flags]
```

#### Flags
| Field                 | Description                     |
|-----------------------|---------------------------------|
| `--inbox <id>`       | Only events of these inboxes.   |
| `--pod <id>`         | Only events of these pods.      |
| `-e, --event-types`  | Only these event types.         |
| `--last-event-id <value>`| Resume after this event (evt_...). |

#### Examples
```
machinemail events stream --json | jq -c 'select(.type == "message.received")'
```

#### API
- [`GET /v0/events/stream`](/content/docs/reference/api/events/index.html)