Cumulative usage time-series
Return usage as a **cumulative time-series**: for each requested `usage_types` dimension, a list of `{ timestamp, value }` points where `value` is the **running total** at that bucket boundary. Counts (`inbox_count`, `message_count`, `thread_count`) accumulate over the window; `storage_bytes` reports the current live counter at each point. The window is `start`–`end` (ISO-8601, at most 90 days apart), bucketed by `period` seconds. The number of buckets — `(end − start) ÷ period` — may not exceed 500; use a larger `period` for a longer window. `limit` takes at most that many buckets from the tail of the window, and `descending` returns the newest bucket first. Requires the key's `metrics_read` permission; a key without it gets `403`.
Return usage as a cumulative time-series: for each requested
usage_types dimension, a list of { timestamp, value } points where
value is the running total at that bucket boundary. Counts
(inbox_count, message_count, thread_count) accumulate over the
window; storage_bytes reports the current live counter at each point.
The window is start–end (ISO-8601, at most 90 days apart), bucketed by
period seconds. The number of buckets — (end − start) ÷ period — may
not exceed 500; use a larger period for a longer window. limit takes
at most that many buckets from the tail of the window, and descending
returns the newest bucket first.
Requires the key's metrics_read permission; a key without it gets 403.
The per-tenant API key. Sent as the x-api-key request header. The key
is tenant-scoped.
In: header
Query Parameters
The metered dimensions to report. Repeat the parameter, or pass a comma-separated list, for more than one.
Window start (inclusive), ISO-8601 UTC.
Window end, ISO-8601 UTC. At most 90 days after start.
Bucket size in seconds. (end − start) ÷ period must be ≤ 500.
Return at most this many buckets, taken from the tail of the window.
Return the newest bucket first when true. Defaults to oldest-first.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/metrics/usage?usage_types=inbox_count&start=2019-08-24T14%3A15%3A22Z&end=2019-08-24T14%3A15%3A22Z&period=1"{ "inbox_count": [ { "timestamp": "2019-08-24T14:15:22Z", "value": 0 } ], "message_count": [ { "timestamp": "2019-08-24T14:15:22Z", "value": 0 } ], "thread_count": [ { "timestamp": "2019-08-24T14:15:22Z", "value": 0 } ], "storage_bytes": [ { "timestamp": "2019-08-24T14:15:22Z", "value": 0 } ], "property1": [ { "timestamp": "2019-08-24T14:15:22Z", "value": 0 } ], "property2": [ { "timestamp": "2019-08-24T14:15:22Z", "value": 0 } ]}{ "name": "string", "message": "string"}{ "name": "string", "message": "string"}{ "name": "validation", "errors": { "property1": "string", "property2": "string" }}{ "name": "string", "message": "string"}Get a single message GET
Returns the full structured message — parsed sender/recipients, `text`/ `html` bodies, the reply-history-stripped `extracted_*`, `headers`, threading headers, and the attachment list. A `spam`-labeled message requires the key's `label_spam_read` permission. Unknown/cross-tenant inbox or message ids return an indistinguishable `404`.
Sign up an agent and get a key + inbox POST
Provision a brand-new account entirely in code: this creates a tenant, a first inbox, and a first API key, then emails a 6-digit verification code to `human_email`. Call `verify` with that code to activate the account. This is the one unauthenticated endpoint — you use it to obtain your first API key, so there is no key to present yet. The `api_key` in the response is shown **once** and is never retrievable again — store it securely. Calling `sign_up` again with the same `human_email` is safe and idempotent: it returns the **same** account with a freshly **rotated** `api_key` (the previous key stops working) and re-sends the verification code if the previous one has expired — it never creates a duplicate account.