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 applies three ceilings on every request:

1. Account entitlement: the current plan and active add-ons decide which capabilities exist now.
2. Membership: a delegated person cannot grant or use more than their current role and domain access.
3. Credential grant: the token or OAuth consent must include the endpoint's required scope.

The error identifies the failed ceiling. insufficient_scope means the credential was never granted the scope, scope_blocked_by_membership means the person's role is narrower, and scope_blocked_by_entitlement means the required White Label entitlement is not active.

Two scope layers: OAuth and API scopes

OAuth supports six legacy convenience bundles, every fine-grained API scope, and exposure-only tools:* selectors. The legacy bundles are:

Each legacy OAuth bundle expands into fine-grained API scopes, such as domains:read and drive:account:write. New integrations may request those granular scopes directly. White Label scopes are deliberately absent from the older mail:* bundles, so an existing connector never gains reseller administration after an upgrade. It must request the required White Label scopes explicitly. A tools:white_label selector limits MCP exposure but grants no API permission by itself.

Three ways to connect and how each one grants 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: hosted HTTP MCP filters its advertised tools from the OAuth credential; stdio MCP intersects token scopes with toolsets, read-only mode, and local safety controls; and the REST API is gated directly by the fine-grained scopes carried on the token. Runtime API authorization remains authoritative in every mode.

Scope reference

Account & Billing

billing:autopay is the only scope that moves money, so it is worth reading twice.

It is deliberately separate from billing:read: a connection allowed to see your bill must not be able to add to it, and granting read-only billing is not consent to spend. It is never included automatically, a token or connection has it only if you granted it explicitly, and it is absent from every one of the older coarse scope bundles, so a connection authorized before this existed cannot spend anything.

What it allows: buying email-verification credits, and starting a subscription. What it does not allow, at all: cancelling, downgrading, or changing a subscription you already have. Those have no endpoint. Spending is additionally bounded per purchase, per day and per month for the whole account, regardless of how many connections hold the scope.

It is available on every plan because verification credits are sold on every plan, including Nano.

Domains

Domain-alias delivery itself starts on Starter. Starter tokens can read the saved and live state; connecting, changing, or removing it through API/MCP needs the Pro/Agency domains:write capability. Dashboard changes remain available on Starter. See Domain Aliases via API and MCP.

White Label

These ops-token scopes appear only while a White Label trial or paid add-on is active. During cancellation grace, the owner retains the read scopes; delegated members and all write scopes are removed.

The live membership applies another ceiling. A client or teammate can never widen their own role, domain access, or custom permissions by creating a broader token. See Manage White Label Teams with API and MCP.

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. They have API-specific safeguards in addition to the ordinary sending route's limits: by default, reads allow 30 requests per minute and 5,000 successful reads per day per token; sending allows 60 requests per minute per token and 100 API sends per day across the mailbox. A second token safety counter defaults to 500 sends per day, so the lower mailbox cap normally wins.

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.

messages:read does not grant write access. In hosted OAuth, approving the broader messages:send capability provisions read, write, and send access together; a manually created tm_msg_ token keeps exactly the scopes selected at creation.

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

White Label scopes are additive rather than part of the base Pro or Agency plan. They appear for those accounts only while their White Label entitlement is active.

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.

For a locally hosted MCP server, its administrator can require TREKMAIL_ALLOW_DESTRUCTIVE=true before delete tools are available. Hosted MCP uses the scopes approved during OAuth.

The messages:send scope allows sending real email from the mailbox. In a locally hosted MCP server, sending can also require TREKMAIL_ALLOW_SENDING=true 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 a locally hosted MCP server, migration writes can also require TREKMAIL_ALLOW_MIGRATION=true 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.
• 403 "scope_blocked_by_entitlement": White Label is inactive, or a write was attempted during cancellation grace. Reactivate it, then retry with the same connection.
• 403 "scope_blocked_by_membership": The current member role or custom permission does not allow the action. Ask the account owner to change that membership.
• Some scopes are hidden in the create form: Your plan does not support those scopes. Only allowed scopes are shown.