API Overview

The TrekMail API lets you manage domains, mailboxes, forwarding, DNS, email migrations, and full webmail operations — read, send, draft, schedule, folder management, contacts, calendar, identities, templates, and blocked senders — from any HTTP client or AI agent. Every request uses a bearer token, every response is JSON, and every action is audited.

What you get

• REST API v1 with JSON request/response format.
• Bearer token authentication — no cookies, no sessions.
• Idempotency keys on mutating requests to prevent duplicate operations.
• Per-token rate limiting with Retry-After headers.
• Audit log visible in your dashboard under AI Agents & API → Audit Log.
• MCP server with 181 tools, including 38 Drive tools for files, folders, uploads, share links, bulk operations, and read-only Drive Add-on status.
• Dual-token architecture — separate ops tokens for infrastructure and message tokens for full email operations (read, send, draft, schedule, contacts, calendar, identities, templates, folders, and more).

Drive API and file automation

Drive is now part of the public API surface. The Drive API adds 39 REST endpoints for Account Drive and mailbox Drive: spaces, usage, folder browsing, uploads, file and folder management, Trash, bulk actions, public share links, and read-only Drive Storage Add-on status.

Drive uses nine ops-token scopes: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, and drive:addon:read. Billing actions for the Drive Add-on — purchase, resize, and cancel — remain dashboard-only and are not exposed as API or MCP write operations.

Start with Drive API Overview or the Drive API Quickstart.

Dual-token architecture

The API uses two independent token types. You can use one or both depending on your needs:

Ops tokens and message tokens have separate scopes and separate rate limits. A single agent can use both tokens simultaneously by configuring them in the MCP server environment.

Message tokens are available on Pro and Agency plans.

Before you start

• All plans have API access. Nano plans can use the Email Verifier API (verify:read, verify:write). Starter plans add read-only infrastructure scopes plus verifier. Pro and Agency plans get full read/write access.
• Create a token in AI Agents & API → Tokens → Create token.
• New to the API? Click the Guide button at the top of the AI Agents & API page for an interactive walkthrough of the dashboard — it covers connection methods, token management, and the audit log in about 60 seconds.

How authentication works

Every request must include your token in the Authorization header:

Authorization: Bearer tm_live_abc123...

Ops tokens start with tm_live_ and message tokens start with tm_msg_. Both are shown once at creation. TrekMail stores only the SHA-256 hash — the plaintext cannot be recovered.

If the token is missing, revoked, or expired, the API returns 401 with an unauthenticated error code.

Base URL and versioning

All endpoints live under:

https://trekmail.net/api/v1

The base URL is shown on your AI Agents & API dashboard under Quick Reference. The version is in the URL path. When a v2 is introduced (if ever), v1 will continue to work.

Response format

Successful responses return JSON with a data key for single resources or a paginated list:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Error responses follow a consistent structure:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

Request IDs

Every response includes an X-Request-Id header. You can also pass your own via X-Request-Id in the request — it will be echoed back and logged in the audit trail.

Rate limits

Each token is rate-limited per minute. When you hit the limit, the API returns 429 with a Retry-After header indicating when you can retry.

Destructive operations (delete intents) have an additional daily limit per token and a cooldown between consecutive deletes.

Migration write operations (start, cancel, retry) have a dedicated rate limit of 10 requests per minute per token, plus a server-wide concurrency cap that returns 503 when too many migrations are running globally.

Idempotency

All POST and PUT requests require an Idempotency-Key header. If you send the same key with the same body, the API replays the original response without creating duplicates.

Idempotency-Key: create-mailbox-alice-2024

If you send the same key with a different body, the API returns 409 Conflict.

Mailbox storage allocation

Every endpoint that creates a mailbox or invite — POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk — accepts an optional storage_allocation_mb integer.

Allocations are validated against the live pool minus existing dedicated mailboxes and pending dedicated invites. Bulk endpoints additionally validate the sum of allocations across the batch and reject the entire batch with 422 storage_pool_exceeded if it would over-commit. The pool refreshes when a dedicated mailbox is deleted, when an invite is redeemed (allocation moves to the new mailbox), and when a pending invite expires.

For invites the allocation is recorded on the access code and copied onto the new mailbox at redeem time. If the pool no longer fits the requested allocation at redeem time (e.g. another admin grew their dedicated allocation in the interim), the redeem gracefully downgrades the new mailbox to shared rather than failing — the recipient sees a notice on the success page.

Available endpoints

Internal support endpoints (HMAC auth)

These endpoints use HMAC-SHA256 authentication (not bearer tokens) and are used by the AI support pipeline:

The OpenAPI specification is available at /api/openapi.json for import into Postman, Insomnia, or code generators.

Quick fixes

• 401 "unauthenticated": Check that the Authorization: Bearer <token> header is present and the token has not been revoked or expired.
• 403 "plan_api_disabled": The requested scope is not available on your plan. Nano plans can only access Email Verifier endpoints. Upgrade for broader access.
• 403 "token_scope_blocked_by_plan": Your token has scopes that are not available on your current plan. Revoke the token and create a new one with allowed scopes.
• 422 "missing_idempotency_key": Add an Idempotency-Key header to POST and PUT requests.
• 429 rate limited: Wait for the duration in the Retry-After header before retrying.