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.

Two scope layers: OAuth vs internal

If you're connecting through Claude.ai, Claude Desktop, or another OAuth client, the consent screen shows five coarse OAuth scopes:

Behind the scenes each OAuth scope expands into a set of internal API scopes (the fine-grained list below — domains:read, drive:account:write, etc.). When you create a tm_live_ token by hand in the dashboard, you pick the internal scopes directly. When an AI agent OAuth-authorizes, Claude requests one or more of the five buckets and Laravel expands them into the matching internal-scope set on the token row. The endpoint-level checks always work against the internal scopes, so both paths reach the same gate. The full OAuth → internal expansion table lives in config/oauth-scope-map.php.

Three ways to connect — and how each one gates capabilities

There are three ways an agent or integration reaches TrekMail, and the gating mechanism differs in each. This matters because the MCP "capability flags" (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) only exist in one of them.

In short: HTTP MCP forces all capability flags true and relies entirely on the five OAuth scopes for gating; stdio MCP gates with the TREKMAIL_ALLOW_* env flags (default off) on top of token scopes; and the REST API is gated purely by the internal scope strings carried on the token. For the domain-SMTP tools specifically, the destructive set/create/update/delete/test tools map to mail:write under HTTP-MCP OAuth, sit behind TREKMAIL_ALLOW_DESTRUCTIVE under stdio, and require smtp:write over plain REST.

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

Starter: read-only via API. Open and reply to tickets from the dashboard.

SMTP Configuration

SMTP is configured per domain (/api/v1/domains/{id}/smtp), with a single account-wide default (/api/v1/smtp/default) deciding what new domains start on. See API Overview for the full endpoint list. The legacy account-level /api/v1/smtp endpoints still answer for back-compat but no longer drive routing.

Migrations

Migration scopes are carried by ops tokens (tm_live_ prefix). Starter can view migrations via API and run them from the dashboard. Pro and Agency can also start, cancel, retry, and delete migrations through the API and MCP.

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.

Nano + Drive Add-on: With an active Drive Storage Add-on, Nano gets the full Drive scope set. Nothing else unlocks — just Drive, plus the Email Verifier scopes Nano already has. If you cancel the add-on, read scopes stay live for the 7-day grace window so you can finish downloading or rolling off; write, share, and purge are cut off right away.

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.