Scopes
Per-key scopes that govern which operations a key can perform.
Scopes restrict what a key can do, beyond which mailboxes it can target. A key only succeeds at an operation if it includes every scope the operation requires.
Choosing scopes when creating a key
Pick the smallest set that covers the integration’s needs. A reporting integration that pulls user and mailbox performance needs only reporting. An integration that pulls per-message detail needs reporting plus messages:read. An integration that downloads attachment files adds messages:content.
Recognized scopes
| Scope | Grants |
|---|---|
reporting | List mailboxes (GET /api/v1/admin/mailboxes) and run reports (POST /api/v1/reports/*). |
messages:read | List attachment metadata for a message (names, types, sizes), and read per-message reporting detail. |
messages:content | Download attachment binary content. |
Some endpoints require multiple scopes — the endpoint reference page calls this out. For example, POST /api/v1/reports/receivedMessageDetail requires both reporting and messages:read.
How scope failures look
If a key is missing a required scope, the API returns 403:
{
"status": "error",
"error": {
"code": "403",
"message": "Token does not have the required scope for this endpoint."
}
}The endpoint reference for each call documents which scope (if any) it requires.