Events · MachineMail Docs
List Events
| Method | Path | Summary |
|---|---|---|
GET |
/v0/events |
List Events |
GET |
/v0/events/stream |
Stream Events (SSE) |
GET |
/v0/events/{event_id} |
Get Event |
GET |
/v0/inboxes/{inbox_id}/events |
List Events in Inbox |
GET |
/v0/inboxes/{inbox_id}/events/{event_id} |
Get Event in Inbox |
GET |
/v0/pods/{pod_id}/events |
List Events in Pod |
GET |
/v0/pods/{pod_id}/events/{event_id} |
Get Event in Pod |
GET |
/v0/ws |
WebSocket Event Stream |
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" |
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:
| Field | Description |
|---|---|
event_id |
string Required ID of the event (evt_...). Sorts by creation time. |
event_type |
`"message.received" |
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" |
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" |
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" |
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:
| Field | Description |
|---|---|
event_id |
string Required ID of the event (evt_...). |
event_type |
`"message.received" |
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:
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. |