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.

Hooking up Claude, Cursor, or another AI agent? You usually don't need to create a token by hand — those clients use the OAuth flow at claude.ai/customize/connectors (or claude mcp add for Claude Code). Your browser walks through the consent step and the token lives in the agent. Manual tm_live_ tokens are for your own scripts, CI jobs, and integrations that don't speak OAuth. 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 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. What you can pick depends on your plan:

• Nano — Email Verifier only (verify:read, verify:write). Buy a Drive Storage Add-on and you also get the full Drive API and all 42 Drive MCP tools.
• Starter — Full Drive, full Email Verifier, and read-only access to everything else (domains, mailboxes, forwarding, mail filters, auto-reply, migrations, tickets, SMTP, Cloudflare). For the writes that aren't on Starter API — creating migrations, replying to tickets, changing auto-reply, etc. — use the dashboard.
• Pro and Agency — Everything. Read, write, create, delete across all families, plus message tokens for full email read/send via the API.

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 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 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.