metrics.md
title: "Metrics" description: "Query MachineMail metrics for the organization, a pod or an inbox: event counts over a time range, rolling bounce and complaint rates, and current usage." canonical: "https://machinemail.dev/docs/reference/api/metrics"
Metrics
Query MachineMail metrics for the organization, a pod or an inbox: event counts over a time range, rolling bounce and complaint rates, and current usage.
Source: https://machinemail.dev/docs/reference/api/metrics
| 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
GET /v0/inboxes/{inbox_id}/metrics
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 | Type | Description | |
|---|---|---|---|
inbox_id |
string |
required | ID of the inbox. |
Query parameters
| Field | Type | 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
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Events in Inbox
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 | Type | 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
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/events" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Rates in Inbox
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 | Type | Description | |
|---|---|---|---|
inbox_id |
string |
required | ID of the inbox. |
Query parameters
| Field | Type | 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
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/rates" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Usage in Inbox
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 | Type | Description | |
|---|---|---|---|
inbox_id |
string |
required | ID of the inbox. |
Query parameters
| Field | Type | 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
curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/metrics/usage" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Events (alias)
GET /v0/metrics
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
Error bodies use the error envelope.
Example
curl "https://api.machinemail.dev/v0/metrics" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Events
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
curl "https://api.machinemail.dev/v0/metrics/events" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Rates
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
curl "https://api.machinemail.dev/v0/metrics/rates" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Usage
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
curl "https://api.machinemail.dev/v0/metrics/usage" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Events (alias) in Pod
GET /v0/pods/{pod_id}/metrics
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 | Type | 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
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Events in Pod
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 | Type | 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
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/events" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Rates in Pod
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 | Type | 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
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/rates" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}
Query Usage in Pod
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 | Type | 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
curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/metrics/usage" \
-H "Authorization: Bearer $MACHINEMAIL_API_KEY"
{
"key": "value"
}