Metrics · MachineMail Docs
Query Events (alias) in Inbox
| Method | Path | Summary |
|---|---|---|
GET |
/v0/inboxes/{inbox_id}/metrics |
Query Events (alias) in Inbox |
GET |
/v0/inboxes/{inbox_id}/metrics/events |
Query Events in Inbox |
GET |
/v0/inboxes/{inbox_id}/metrics/rates |
Query Rates in Inbox |
GET |
/v0/inboxes/{inbox_id}/metrics/usage |
Query Usage in Inbox |
GET |
/v0/metrics |
Query Events (alias) |
GET |
/v0/metrics/events |
Query Events |
GET |
/v0/metrics/rates |
Query Rates |
GET |
/v0/metrics/usage |
Query Usage |
GET |
/v0/pods/{pod_id}/metrics |
Query Events (alias) in Pod |
GET |
/v0/pods/{pod_id}/metrics/events |
Query Events in Pod |
GET |
/v0/pods/{pod_id}/metrics/rates |
Query Rates in Pod |
GET |
/v0/pods/{pod_id}/metrics/usage |
Query Usage in Pod |
Query Events (alias) in Inbox
http
GET /v0/inboxes/{inbox_id}/metrics
Warning
Deprecated.
Same as Query Events (alias) (GET /v0/metrics), 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 |
|---|---|
event_types |
string[] - Event types to count: message.received, message.received.spam, message.received.blocked, message.received.unauthenticated, message.received.quarantined, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified (the default is all of them). message.received counts every inbound message, including the message.received.* sub-types, which are also reported under their own keys. Other values give a series of zeros. |
start |
string (date-time) - Start of the range. Default: 24 hours before end. |
end |
string (date-time) - End of the range. Default: now; a later time is clamped to now. |
limit |
integer - Return at most this many points per series. |
descending |
boolean - Newest point first. |
period |
integer - Bucket size in seconds, 1 to 86400. Default 86400 (one bucket per UTC day). The range may hold at most 1000 buckets. |
Response
200 Event counts by type (application/json)
Type: Record<string, MetricBucket[]>
Errors
| Status | Meaning |
|---|---|
400 |
Invalid request: error.type is validation and error.param names the field. |
401 |
Missing, invalid, expired or revoked credential. |
403 |
The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register). |
404 |
Not found. Also returned for resources outside the credential scope. |
500 |
Unexpected server error. |
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Events in Inbox
http
GET /v0/inboxes/{inbox_id}/metrics/events
Same as Query Events (GET /v0/metrics/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
Response
200 Event counts by type (application/json)
Type: Record<string, MetricBucket[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/events" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Rates in Inbox
http
GET /v0/inboxes/{inbox_id}/metrics/rates
Same as Query Rates (GET /v0/metrics/rates), 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 |
|---|---|
rate_types |
string[] - Rate types: bounce, complaint. Default: both. Another value is a 400. |
start |
string (date-time) - Start of the range. Default: 24 hours before end. |
end |
string (date-time) - End of the range. Default: now; a later time is clamped to now. |
limit |
integer - Return at most this many points per series. |
descending |
boolean - Newest point first. |
period |
integer - How often a point is sampled, in seconds, 60 to 86400. Default 3600. The range may hold at most 1000 points. |
window |
integer - How far back each point looks, in seconds: a whole multiple of period, at most 2592000 (30 days). Default 86400 when that is a multiple of period, otherwise period. |
Response
200 Rates by type (application/json)
Type: Record<string, RatePoint[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/rates" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Usage in Inbox
http
GET /v0/inboxes/{inbox_id}/metrics/usage
Same as Query Usage (GET /v0/metrics/usage), 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 |
|---|---|
usage_types |
string[] - Usage types: storage_bytes, message_count, thread_count, inbox_count, pod_count, domain_count. Default: all. Another value is a 400. |
start |
string (date-time) - Start of the range. Default: 24 hours before end. |
end |
string (date-time) - End of the range. Default: now; a later time is clamped to now. |
limit |
integer - Return at most this many points per series. |
descending |
boolean - Newest point first. |
period |
integer - Accepted for AgentMail compatibility; usage has no history, so there is one point whatever the period. |
Response
200 Usage by type (application/json)
Type: Record<string, UsagePoint[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/usage" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Events (alias)
http
GET /v0/metrics
Warning
Deprecated.
Alias of GET /v0/metrics/events.
Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: metrics_read.
Query parameters
Response
200 Event counts by type (application/json)
Type: Record<string, MetricBucket[]>
Errors
| Status | Meaning |
|---|---|
400 |
Invalid request: error.type is validation and error.param names the field. |
401 |
Missing, invalid, expired or revoked credential. |
403 |
The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register). |
500 |
Unexpected server error. |
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/metrics" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Events
http
GET /v0/metrics/events
Counts of events per event type over time, in buckets of period seconds (default one day), over the last 24 hours unless start and end say otherwise. message.received includes its sub-types (spam, blocked, unauthenticated, quarantined). At most 100,000 events are counted per query.
Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: metrics_read.
Query parameters
Response
200 Event counts by type (application/json)
Type: Record<string, MetricBucket[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/metrics/events" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Rates
http
GET /v0/metrics/rates
Rolling bounce and complaint rates. At each period grid point: the bounced (or complained) messages over the preceding window, divided by the messages sent over the same window, with the send count alongside. Defaults: the last 24 hours, period 3600, window 86400.
Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: metrics_read.
Query parameters
Response
200 Rates by type (application/json)
Type: Record<string, RatePoint[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/metrics/rates" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Usage
http
GET /v0/metrics/usage
Current usage in the scope. Usage history is not kept yet: each series has a single point, at end, with the value now.
Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: metrics_read.
Query parameters
Response
200 Usage by type (application/json)
Type: Record<string, UsagePoint[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/metrics/usage" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Events (alias) in Pod
http
GET /v0/pods/{pod_id}/metrics
Warning
Deprecated.
Same as Query Events (alias) (GET /v0/metrics), 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 Event counts by type (application/json)
Type: Record<string, MetricBucket[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Events in Pod
http
GET /v0/pods/{pod_id}/metrics/events
Same as Query Events (GET /v0/metrics/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 Event counts by type (application/json)
Type: Record<string, MetricBucket[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/events" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Rates in Pod
http
GET /v0/pods/{pod_id}/metrics/rates
Same as Query Rates (GET /v0/metrics/rates), 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 Rates by type (application/json)
Type: Record<string, RatePoint[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/rates" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}
Query Usage in Pod
http
GET /v0/pods/{pod_id}/metrics/usage
Same as Query Usage (GET /v0/metrics/usage), 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 Usage by type (application/json)
Type: Record<string, UsagePoint[]>
Errors
Error bodies use the error envelope.
Example
Request
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/usage" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
Response 200
{
"key": "value"
}