Scopes

Scopes control what an identity's API key can do. They are set when creating an identity and cannot be changed after creation.

Available Scopes

Scope	Allows	API Endpoints
`mail:read`	Read messages and threads	`GET /v0/messages`, `GET /v0/threads`
`mail:send`	Send and reply to emails	`POST /v0/messages/send`, `POST /v0/messages/:id/reply`
`mail:manage`	Update message labels	`PATCH /v0/messages/:id`

If an API key attempts an action outside its scopes, the API returns 403 Forbidden:

{
  "error": "forbidden",
  "message": "Missing required scope: mail:send",
  "status": 403
}

When using the MCP server, only tools matching the identity's scopes are available. An identity with only mail:read will only see:

The mail.send, mail.reply, and mail.update_labels tools won't appear.

Use Case	Recommended Scopes
Read-only monitoring agent	`mail:read`
Agent that reads and responds	`mail:read`, `mail:send`, `mail:manage`
Notification sender only	`mail:send`
Full access agent	All scopes