### List Events

| Method | Path | Summary |
| --- | --- | --- |
| `GET` | `/v0/events` | [List Events](/content/docs/reference/api/events#list-events/index.html) |
| `GET` | `/v0/events/stream` | [Stream Events (SSE)](/content/docs/reference/api/events#stream-events-sse/index.html) |
| `GET` | `/v0/events/{event_id}` | [Get Event](/content/docs/reference/api/events#get-event/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/events` | [List Events in Inbox](/content/docs/reference/api/events#list-events-in-inbox/index.html) |
| `GET` | `/v0/inboxes/{inbox_id}/events/{event_id}` | [Get Event in Inbox](/content/docs/reference/api/events#get-event-in-inbox/index.html) |
| `GET` | `/v0/pods/{pod_id}/events` | [List Events in Pod](/content/docs/reference/api/events#list-events-in-pod/index.html) |
| `GET` | `/v0/pods/{pod_id}/events/{event_id}` | [Get Event in Pod](/content/docs/reference/api/events#get-event-in-pod/index.html) |
| `GET` | `/v0/ws` | [WebSocket Event Stream](/content/docs/reference/api/events#websocket-event-stream/index.html) |

#### List Events

http

```
GET /v0/events
```

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.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Query parameters

| Field | Description |
| --- | --- |
| `limit` | `integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. |
| `page_token` | `string` next_page_token from the previous page. |
| `ascending` | `boolean` Sort oldest first. Defaults to true when after is set. |
| `after` | `string` An event ID (evt_...): only events stored after it, in commit order. Or an ISO 8601 time: only events created after it. Either one makes the default order oldest first. |
| `before` | `string (date-time)` Only events created before this time. |
| `event_types` | `("message.received" | "message.received.spam" | ... )[]` Only these event types (repeat the parameter, or comma-separate). Omit for every type. |
| `inbox_id` | `string` Only events of this inbox. |
| `pod_id` | `string` Only events of this pod. |

#### Response

**200** A page of events (`application/json`)

| Field | Description |
| --- | --- |
| `count` | `integer` Required Number of items returned. |
| `limit` | `integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. |
| `next_page_token` | `string` Page token for pagination. Absent on the last page. |
| `events` | `[Event[]](/content/docs/reference/api/objects#event/index.html)` Required Newest first; oldest first when after is set or ascending is true. |

Each item of `events` is a [Event](/content/docs/reference/api/objects#event/index.html):

| Field | Description |
| --- | --- |
| `event_id` | `string` Required ID of the event (evt_...). Sorts by creation time. |
| `event_type` | `"message.received" | "message.received.spam" | ...` Required Type of event... |
| `organization_id` | `string` Required ID of the organization. |
| `pod_id` | `string` ID of the pod. Absent for organization-level events. |
| `inbox_id` | `string` ID of the inbox. Absent for events without an inbox (for example domain.verified). |
| `data` | `Record<string, unknown>` Required Event payload... |
| `timestamp` | `string (date-time)` Required When the event happened (same as created_at). |
| `created_at` | `string (date-time)` Required When the event was stored. |

#### Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request... |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission or scope for this request... |
| `500` | Unexpected server error. |

#### Example

Request

```
curl "https://api.machinemail.dev/v0/events" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "events": [
    {
      "event_id": "evt_01k6x3g4pt0000k6t2wa8e1n3q",
      "event_type": "message.received",
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
      "inbox_id": "agent@machinemail.dev",
      "data": {
        "key": "value"
      },
      "timestamp": "2026-10-01T12:00:00.000Z",
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}
```

### Stream Events (SSE)

http

```
GET /v0/events/stream
```

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

**Authentication:** `Authorization: Bearer <api key>` or `?token=<api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Query parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string[]` Only events of these inboxes... |
| `inbox_ids` | `string[]` Same as inbox_id. |
| `pod_id` | `string[]` Only events of these pods... |
| `pod_ids` | `string[]` Same as pod_id. |
| `event_types` | `("message.received" | "message.received.spam" | ... )[]` Only these event types... |

#### Headers

| Field | Description |
| --- | --- |
| `Last-Event-Id` | `string` Resume after this event... |

#### Response

**200** The event stream (`text/event-stream`)

#### Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request... |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential holds no permission... |
| `404` | Not found. |
| `500` | Unexpected server error. |

#### Example

Request

```
curl "https://api.machinemail.dev/v0/events/stream" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
id: evt_01k6x3g4pt0000k6t2wa8e1n3q
data: {"event_id":"evt_01k6x3g4pt0000k6t2wa8e1n3q", ...}
```

### Get Event

http

```
GET /v0/events/{event_id}
```

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

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `event_id` | `string` Required ID of the event (evt_...). |

#### Response

**200** The event (`application/json`)

| Field | Description |
| --- | --- |
| `event_id` | `string` Required ID of the event (evt_...). |
| `event_type` | `"message.received" | "message.received.spam" | ...` Required Type of event... |
| `organization_id` | `string` Required ID of the organization. |
| `pod_id` | `string` ID of the pod. Absent for organization-level events. |
| `inbox_id` | `string` ID of the inbox. Absent for events without an inbox... |
| `data` | `Record<string, unknown>` Required Event payload... |
| `timestamp` | `string (date-time)` Required When the event happened... |
| `created_at` | `string (date-time)` Required When the event was stored. |

#### Errors

| Status | Meaning |
| --- | --- |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission... |
| `404` | Not found. Also returned for resources... |
| `500` | Unexpected server error. |

#### Example

Request

```
curl "https://api.machinemail.dev/v0/events/evt_01k6x3g4pt0000k6t2wa8e1n3q" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

```
{
  "event_id": "evt_01k6x3g4pt0000k6t2wa8e1n3q",
  "event_type": "message.received",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "inbox_id": "agent@machinemail.dev",
  "data": {
    "key": "value"
  },
  "timestamp": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z"
}
```

### List Events in Inbox

http

```
GET /v0/inboxes/{inbox_id}/events
```

Same as List Events (`GET /v0/events`), limited to the inbox.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string` Required ID of the inbox. |

#### Query parameters

| Field | Description |
| --- | --- |
| `limit` | `integer` Maximum number of items to return... |
| `page_token` | `string` next_page_token from the previous page. |
| `ascending` | `boolean` Sort oldest first... |
| `after` | `string` An event ID (evt_...): only events stored... |
| `before` | `string (date-time)` Only events created before this time. |
| `event_types` | `("message.received" | ...)[]` Only these event types... |
| `inbox_id` | `string` Only events of this inbox. |
| `pod_id` | `string` Only events of this pod. |

#### Response

**200** A page of events (`application/json`)

| Field | Description |
| --- | --- |
| `count` | `integer` Required Number of items returned. |
| `limit` | `integer` Maximum number of items per page... |
| `next_page_token` | `string` Page token for pagination... |
| `events` | `[Event[]](/content/docs/reference/api/objects#event/index.html)` Required Newest first... |

Each item of `events` is a [Event](/content/docs/reference/api/objects#event/index.html):

| Field | Description |
| --- | --- |
| `event_id` | `string` Required ID of the event (evt_...). |
| `event_type` | `"message.received" | "message.received.spam" | ...` Required Type of event... |
| `organization_id` | `string` Required ID of the organization. |
| `pod_id` | `string` ID of the pod... |
| `inbox_id` | `string` ID of the inbox... |
| `data` | `Record<string, unknown>` Required Event payload... |
| `timestamp` | `string (date-time)` Required When the event happened... |
| `created_at` | `string (date-time)` Required When the event was stored. |

#### Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid request... |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential lacks the permission... |
| `404` | Not found. Also returned for resources... |
| `500` | Unexpected server error. |

#### Example

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/events" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

### Get Event in Inbox

http

```
GET /v0/inboxes/{inbox_id}/events/{event_id}
```

Same as Get Event (`GET /v0/events/{event_id}`), limited to the inbox.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `inbox_id` | `string` Required ID of the inbox. |
| `event_id` | `string` Required ID of the event (evt_...). |

#### Response

**200** The event (`application/json`)

#### Errors

#### Example

Request

```
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/events/evt_01k6x3g4pt0000k6t2wa8e1n3q" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

### List Events in Pod

http

```
GET /v0/pods/{pod_id}/events
```

Same as List Events (`GET /v0/events`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `pod_id` | `string` Required ID of the pod. |

#### Query parameters

#### Response

**200** A page of events (`application/json`)

Each item of `events` is a [Event](/content/docs/reference/api/objects#event/index.html):

#### Errors

#### Example

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/events" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

### Get Event in Pod

http

```
GET /v0/pods/{pod_id}/events/{event_id}
```

Same as Get Event (`GET /v0/events/{event_id}`), limited to the pod.

**Authentication:** `Authorization: Bearer <api key>` or the dashboard `mm_session` cookie. Permission: `metrics_read`.

#### Path parameters

| Field | Description |
| --- | --- |
| `pod_id` | `string` Required ID of the pod. |
| `event_id` | `string` Required ID of the event (evt_...). |

#### Response

**200** The event (`application/json`)

#### Errors

#### Example

Request

```
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/events/evt_01k6x3g4pt0000k6t2wa8e1n3q" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"
```

Response 200

### WebSocket Event Stream

http

```
GET /v0/ws
```

Upgrades to a WebSocket...

**Authentication:** `Authorization: Bearer <api key>` or

| Status | Meaning |
| --- | --- |
| `400` | The WebSocket handshake failed... |
| `401` | Missing, invalid, expired or revoked credential. |
| `403` | The credential holds no permission... |
| `404` | Not found. Also returned for resources... |
| `500` | Unexpected server error. |