Creating and Managing API Tokens

API tokens control what an application or agent can do on your account. Each token has a name, scopes, optional domain constraints, and an expiration date.

Connecting an MCP client? If it supports browser authorization, add https://trekmail.net/mcp as a remote MCP server and approve access in the browser. You usually do not need to create or paste a token. Manual tm_live_ tokens are for scripts, CI jobs, self-hosted MCP, and clients that do not support that flow. See Connecting AI Agents (MCP).

Before you start

• All plans can create API tokens, including Nano. Nano plans are limited to Email Verifier scopes (verify:read, verify:write).
• Starter plans allow read-only infrastructure scopes plus full Drive and Email Verifier scopes. Starter can also manage forwarding in the dashboard, but API forwarding write access (mailboxes:forwarding:write) requires Pro or Agency. Pro and Agency unlock all scopes.
• The owner can manage all account credentials. A delegated member with API-token permission can manage only credentials they created, and can grant only scopes and domains already present in their membership.
• Tip: Click Start tour on the AI Agents & API page for a short walkthrough of connection options, tokens, connected apps, and the audit log.

Creating a Drive automation token

Drive API and MCP tools use ops tokens (tm_live_...). Select only the Drive scopes needed by the workflow:

• Read-only reporting: drive:account:read, drive:mailbox:read, or drive:addon:read.
• Upload automation: add drive:account:write or drive:mailbox:write.
• Public delivery links: add drive:account:share or drive:mailbox:share.
• Permanent cleanup: use drive:account:purge or drive:mailbox:purge only in a separate, tightly controlled token.

Drive Add-on purchase, resize, and cancel are not available through API tokens. Agents may read add-on status and pricing with drive:addon:read, but subscription changes stay in the dashboard.

Creating a White Label automation token

White Label uses five ops-token scopes: branding:read, branding:write, members:read, members:write, and activity:read. They appear only while the account has White Label access. members:write is marked dangerous because it can remove access and revoke another person's keys.

For a read-only status and audit integration, select branding:read, members:read, and activity:read. Add branding:write only for brand and DNS setup. Add members:write only when the automation must invite or change people.

During cancellation grace, the owner retains the three read scopes for recovery, while writes and delegated White Label credentials stop working. Reactivation does not revive a revoked credential; create or authorize a new one.

Creating a token

1. Go to AI Agents & API → Tokens.
2. Click Create token.
3. Fill in the form:
   • Name: A label to identify the token (e.g., "Claude Agent", "CI/CD Pipeline").
   • Expiration: Choose 7 days, 30 days, 90 days, a custom date, or never.
   • Scopes: Select which operations the token can perform. All allowed scopes are checked by default.
   • Domain constraint: Choose "All domains" or select specific domains to restrict the token's access.
4. Click Create token.

After creation, the plaintext token is displayed once. Copy it immediately or use the Download button to save it as a .txt file.

The token cannot be viewed again. Save it securely before you close the confirmation.

Creating a message token

Message tokens let agents read and send email from a specific mailbox. They are separate from ops tokens and are created programmatically via the API using your ops token.

To create a message token, your agent calls:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Choose the smallest scopes the workflow needs:

The plaintext token (tm_msg_...) is returned once. Add it to your MCP config as TREKMAIL_MESSAGE_TOKEN.

Message tokens are available on Pro and Agency plans. The ops token must have the mailboxes:message-tokens:manage scope.

For a connected Gmail or other external inbox, use external_account_id. To make recipients see an authorized business address instead, also use an identity_id returned by the identities endpoint. See Send As Addresses via API and MCP.

Token format

TrekMail uses two token prefixes to distinguish token types:

The first 8 characters after the prefix are stored as a visible prefix in the dashboard for easy identification.

Scopes

Scopes control what the token can do. What you can pick depends on your plan:

• Nano: Email Verifier only (verify:read, verify:write). Adding Drive Storage also gives the account the Drive API and MCP capabilities it is entitled to use.
• Starter: Full Drive, full Email Verifier, and read-only access to everything else (domains, mailboxes, forwarding, mail filters, auto-reply, migrations, tickets, SMTP, Cloudflare). Use the dashboard for write actions that Starter does not expose through the API, such as creating migrations, replying to tickets, or changing auto-reply.
• Pro and Agency: Full access. Read, write, create, and delete across all families, plus message tokens for email read and send through the API.

White Label scopes are an add-on entitlement rather than a shortcut through the plan table. They are offered only when White Label is active; the owner keeps read-only recovery access during cancellation grace.

See API Scopes and Plan Permissions for the per-scope reference.

Domain constraints

By default, tokens can access all domains on your account. To restrict a token to specific domains:

1. Select Selected domains in the domain constraint section.
2. Check the domains the token should access.

A constrained token will receive 404 responses when trying to access resources on other domains, the API behaves as if those domains do not exist.

Revoking a token

1. Go to AI Agents & API → Tokens.
2. Find the token in the list.
3. Click Revoke.
4. Confirm the revocation.

Revoked tokens stop working immediately. Any API request using a revoked token receives 401 Unauthorized.

Revocation is permanent and cannot be undone. Create a new token if you need to restore access.

Token status

Tokens have three states:

Use the status filter on the Tokens page to view tokens by state.

Audit trail

Every token creation and revocation appears in the Audit Log tab. Events include the token name, action, and time.

Quick fixes

• "Scopes not available on your plan": Your plan doesn't include those scopes. Nano sticks to verify:read and verify:write (add a Drive Storage Add-on to also pick up the drive:* scopes). Starter adds read access across the infra families plus full Drive and full Email Verifier. Pro and Agency unlock writes everywhere.
• Lost the plaintext token: The token cannot be recovered. Revoke it and create a new one.
• Token works but returns 404 for some domains: The token likely has a domain constraint. Revoke and recreate with "All domains" or add the missing domains to the constraint.
• White Label scope returns scope_blocked_by_entitlement: Reactivate White Label, then retry with the same credential. Its saved scope does not need to be issued again.
• A delegated token stopped after a role change: Reduced, suspended, or removed membership access revokes affected credentials immediately. Create a new token after the owner restores the correct access.