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.

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 scopes plus Email Verifier. Starter plans can also manage forwarding via the dashboard, but API forwarding write access (mailboxes:forwarding:write) requires Pro or Agency. Pro and Agency unlock all scopes.
• You must be the account owner to manage tokens.
• Tip: Click the Guide button on the AI Agents & API page for an interactive tour that walks through token creation, scopes, 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 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. TrekMail stores only the SHA-256 hash for security.

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" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Available scopes: messages:read (list, read, update flags, delete, and move email), messages:write (same as read — included for explicit grants), and messages:send (send email).

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.

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. The available scopes depend on your plan:

• Nano: verify:read, verify:write (Email Verifier only)
• Starter: account:read, billing:read, domains:read, domains:dns:read, mailboxes:read, mailboxes:forwarding:read, migrations:read, migrations:write, tickets:read, tickets:write, verify:read, verify:write
• Pro / Agency: All ops scopes including write, create, and delete operations, plus migrations:read, migrations:write, SMTP, Cloudflare (cloudflare:read, cloudflare:write, cloudflare:delete), tickets, account, billing, verifier, and message scopes (messages:read, messages:send) on message tokens.

See API Scopes and Plan Permissions for the full 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 is logged in the Audit Log tab. Events include the token name, the action taken, your IP address, and a timestamp.

Quick fixes

• "Scopes not available on your plan": Your plan does not allow those scopes. Nano plans can only use verify:read and verify:write. Starter plans add read-only infrastructure scopes. Upgrade to Pro for full write access.
• 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.