API Scopes and Plan Permissions

Scopes control exactly what an API token can do. Each token carries a set of scopes, and the API checks them on every request.

How scopes work

When you create a token, you select which scopes to include. The API enforces scopes at two levels:

1. Token creation — You can only select scopes allowed by your plan.
2. Every API request — The middleware checks the token's scopes against the endpoint's requirements.

If a token lacks the required scope, the API returns 403 with an insufficient_scope error code.

Scope reference

Account & Billing

Domains

Mailboxes

Messages (message token)

Message scopes are carried by message tokens (tm_msg_ prefix), not ops tokens (tm_live_ prefix). Message tokens are created via the API using an ops token with the mailboxes:message-tokens:manage scope. Message tokens have their own scopes and rate limits, independent of ops tokens. A daily read limit per token (default 5,000) prevents mailbox scraping, and a daily send limit (default 500) prevents abuse.

All new webmail API endpoints (contacts, calendar, identities, templates, blocked senders, drafts, scheduled send, folders, attachments) map to the existing three message scopes — no new scopes were added. Existing tokens continue to work without any changes.

Note: Existing tokens with messages:read automatically include messages:write for backward compatibility.

Support Tickets

SMTP Configuration

Migrations

Migration scopes are carried by ops tokens (tm_live_ prefix). The migration tool must be available on your plan (Starter and above). All paid plans can start and manage migrations via API.

Cloudflare

Drive

Drive scopes are ops-token scopes. A token can be limited to selected mailboxes, and Drive will hide other mailbox spaces from that token. Drive Add-on purchase, resize, and cancel are not API/MCP write operations; billing changes stay in the dashboard.

Email Verifier

Email Verifier scopes are available on all plans, including Nano. The only limitation is your credit balance. See Email Verifier API for the full endpoint reference.

Plan access levels

What happens when you downgrade

If you downgrade from Pro to Starter, existing tokens with write scopes are not deleted. Instead, the API blocks requests that use disallowed scopes at runtime.

For example, a token with mailboxes:create on a Starter plan will receive 403 with code token_scope_blocked_by_plan when trying to create a mailbox. The read scopes on the same token will continue to work.

To fix this, revoke the old token and create a new one with only the scopes your current plan allows.

Dangerous scopes

The mailboxes:delete, domains:delete, migrations:write, and cloudflare:delete scopes are flagged as dangerous in the dashboard. Tokens with these scopes can initiate mailbox or domain deletion, remove Cloudflare tokens, or perform other irreversible actions. Consider whether your use case truly requires them.

The MCP server has an additional gate: delete tools require TREKMAIL_ALLOW_DESTRUCTIVE=true in the environment. Without it, agents cannot trigger deletion even if the token has the scope.

The messages:send scope allows sending real email from the mailbox. In the MCP server, sending requires two additional safety gates: TREKMAIL_ALLOW_SENDING=true in the environment and confirm_send=true on every send call. See Safety Rails and Delete Intents for details.

The migrations:write scope allows starting email migrations that connect to external IMAP servers using stored credentials. In the MCP server, migration write tools require TREKMAIL_ALLOW_MIGRATION=true in the environment and per-call confirmation parameters (confirm_start, confirm_cancel, confirm_retry).

Domain constraints

Scopes control what a token can do. Domain constraints control where it can do it.

A token constrained to specific domains will only see and modify resources within those domains. This is useful for giving a contractor or agent access to a single client domain without exposing others.

Scope checks happen before domain constraint checks. If a token lacks the required scope, the request fails with 403 regardless of domain constraints.

Quick fixes

• 403 "insufficient_scope": Your token does not have the scope required for this endpoint. Create a new token with the correct scopes.
• 403 "token_scope_blocked_by_plan": Your plan no longer allows one or more of the token's scopes. Upgrade your plan, or revoke the token and create a new one with allowed scopes.
• Some scopes are hidden in the create form: Your plan does not support those scopes. Only allowed scopes are shown.