TrekMail REST API Overview for Developers

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 244 registered routes and a 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 a 235-tool catalog: 173 infrastructure/operations tools and 62 message tools. Hosted HTTP MCP exposes at most 234 because local file upload is intentionally stdio-only. Only tools allowed by the current credential and safety settings are registered, keeping narrow project connections compact.
• 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).
• Outbound deliverability + bounce insights — pull the same sent/delivered/hard/soft rollup your dashboard shows, plus per-recipient hard/soft bounces with the receiver's SMTP status code and response. See Deliverability and Bounces.
• Mailbox storage usage — list_mailboxes and get_mailbox now return used_mb, quota_mb, allocation_mb, and is_pooled, so an agent can spot mailboxes approaching their limit without dashboard access.
• Per-domain White Label branding — configure a domain's brand identity, logos, and branded dashboard/webmail hosts, read back the CNAME records to create, and verify DNS, entirely over the API or MCP. See White Label Branding API and MCP Guide.

Drive API and file automation

Drive is now part of the public API surface. The Drive API exposes 43 REST endpoints for Account Drive and mailbox Drive: spaces, usage, folder browsing, uploads, file and folder management, Trash, bulk actions, public share links, sync-device password management (rclone / Cyberduck / X-Plore / DAVx⁵ / Documents / FolderSync), and read-only Drive Storage Add-on status.

Drive uses eleven 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, drive:addon:read, drive:devices:read, and drive:devices:write. 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 — Email Verifier. Add a Drive Storage Add-on and the full Drive API + 42 MCP tools come with it.
  • Starter — Full Drive, full Email Verifier, and read-only across the rest (domains, mailboxes, migrations, tickets, etc.). Writes for those run from the dashboard.
  • Pro / Agency — Everything: read, write, create, delete across every family, plus message tokens for email read/send.
• Connecting an AI agent? Add https://trekmail.net/mcp as a remote MCP server in any compatible client. If it supports browser authorization, no manual token is needed. See Connecting AI Agents (MCP) for remote, CLI/desktop, bridge, and self-hosted options.
• Writing your own integration? Create a tm_live_ token under AI Agents & API → Tokens → Create token and send it as Authorization: Bearer …. See Creating and Managing API Tokens.
• New to the API? Click Start tour at the top of the AI Agents & API page for a short walkthrough of connection methods, token management, connected apps, and the audit log.

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.

Message tokens use separate limits. The defaults are 30 read requests per minute per token, 60 send requests per minute per token, 5,000 successful reads per day per token, and 100 API sends per day across one mailbox. A second send safety counter defaults to 500 per token per day; the lower mailbox cap normally applies first. These API safeguards do not replace your plan's managed-SMTP limits or an external provider's own limits.

Idempotency

State-changing endpoints marked as idempotent require an Idempotency-Key header. This covers creates, updates, sends, and deletes where an automatic retry could otherwise duplicate work. Read-like POST actions such as provider detection or a connection test do not require one; check the endpoint table or OpenAPI specification. 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.

Forwarding addresses

GET /api/v1/domains/{id}/forwarding-addresses returns more than the list, because two things about a forwarding address are invisible in the address itself:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 300, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "agency",
                "paused_until": null, "paused_reason": null }
}

• limits.max is per domain and depends on the plan — 300 on Agency, 25 elsewhere.
• delivery.active is whether these rules are moving mail right now. It is false on a plan below requires_plan, and false while paused_until is set (the account passed its hourly sending rate; see Sending Limits per Plan). A rule can be is_active: true and still not deliver, so read delivery, not just is_active, before reporting that forwarding works.

Creating on a plan that cannot deliver is allowed and returns 201: the rule is stored and starts working on upgrade. That mirrors the dashboard, which shows such rules as saved and inactive.

Rejections come back as 422 with error.code set to validation_error or limit_exceeded — an address already in use on the domain, a recipient on the same domain (which would loop), a recipient domain with no working MX, or the per-domain budget being full.

POST and DELETE on these endpoints require an Idempotency-Key; PATCH does not.

Delivery history

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log returns what actually happened to recent mail, newest first:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome is one of delivered, deferred (temporary failure, still retrying), failed (the recipient's server rejected it) and blocked — the last meaning our spam filter stopped the message before forwarding, so it never reached the recipient at all. Treating blocked as a bounce would send someone chasing the receiving server for a problem that happened on ours.

limit (1–200, default 100) is the only parameter. The window is the plan's retention — 30 days on Agency, 7 elsewhere — and nothing older exists to ask for, because forwarded events are pruned.

Shared (team) mailboxes

A shared mailbox is a team inbox such as support@ or sales@ that members open through their own regular mailbox account — in Webmail and, when native access is enabled, as a delegated IMAP folder. There is no shared password or separate login. Access is flat: every member can read, and a single can_send flag controls whether that member can reply as the address (true) or is read-only (false). There are no member roles.

GET /api/v1/mailboxes and GET /api/v1/mailboxes/{id} now return mailbox_type ("user" or "shared") and a boolean is_shared; shared mailboxes also include shared_member_count. Use those fields to tell a team inbox apart from a normal one before calling the member endpoints.

The member endpoints reuse your existing mailboxes:read / mailboxes:write scopes — there is no separate shared-mailbox scope.

To discover native mail-app access, call GET /api/v1/mailboxes/{member_mailbox_id}/client-setup for a regular member mailbox. Its shared_mailboxes object reports durable native readiness, effective Send As readiness/reason, exact Inbox/Sent/Archive/Junk paths, and allowed operations. can_send is the assigned Can reply permission, not proof that SMTP is currently ready. The endpoint never returns a password. Calling it with the shared mailbox id returns 422 direct_login_unavailable because the shared address cannot authenticate directly.

Removing a member, changing can_send, or converting a shared mailbox to regular synchronizes mail-server permissions when native access is enabled. A 503 native_access_sync_failed response is retryable and guarantees that the membership, permission, or mailbox type was kept unchanged rather than partially applying the operation.

Available endpoints

Drive has its own reference and is not repeated here — see Drive API Overview. The account-level SMTP endpoints kept for backward compatibility are described under Per-domain SMTP routing rather than listed as current.

The Cloudflare endpoints follow the same flow as the dashboard: validate a token, list zones, connect domains, preview the DNS changes, then apply them. Both /cloudflare/preview and /cloudflare/apply accept two optional per-domain controls:

• included_records — an allowlist of which records to touch, keyed by domain ID: { "123": ["mx_primary", "spf_record"] }. Records you leave out are skipped, so you can apply only MX and SPF and come back for DKIM later. Omit the field to apply every record.
• confirmed_conflicts — when preview flags a record that already exists with a different value, list its record ID here (same { domain_id: [record_ids] } shape) to authorise replacing it.

The record IDs (mx_primary, spf_record, dkim_primary, dmarc_main, …) come straight from the preview response, so a typical agent calls preview first and feeds the IDs it wants back into apply:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

Per-domain SMTP routing and the account default

SMTP is configured per domain. Each domain picks one of three routes — managed platform sending, a saved SMTP profile (your own provider, reusable across domains), or "not configured" — and a single account-wide default decides which route new domains start on.

Per-domain endpoints (smtp:read / smtp:write):

A few notes on the route body:

• smtp_mode=platform selects managed sending; smtp_mode=profile requires smtp_connection_id; not_configured clears the route.
• smtp_mode=inherit makes the domain live-follow the account default — whenever the default changes, this domain changes with it. The web UI always writes concrete routes, but the backend still supports inherit, which is why GET returns effective_smtp_mode showing what inherit currently resolves to.
• set_account_default: true is the API equivalent of the dashboard's Make this the account default toggle (new domains start on this route). apply_to_all: true is the Apply to all domains button (a one-time switch of every domain to this route).

Account-wide default endpoints (smtp:read / smtp:write):

Deleting a profile that was the account default resets the default to the plan baseline.

Legacy endpoints. The account-level GET/PUT /api/v1/smtp (and DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}) remain for backward compatibility but no longer control per-domain routing — use the per-domain and /smtp/default endpoints above. The legacy MCP tools get_smtp_config / update_smtp_config are deprecated for the same reason.

Per-domain White Label branding

Branding is configured per domain (domains:read / domains:write). A domain runs its own brand (mode=custom), inherits the account default (mode=inherit), or is off. Settings always save; the branded dashboard.yourbrand.com / mail.yourbrand.com hosts only go live once the White Label add-on is active (without it they stay draft). The branded hosts point a CNAME at wl.trekmail.net.

PATCH is a partial merge — omitted fields are preserved. If branding is currently off you must pass mode to re-enable it, and a custom sender_email must be on a domain with a verified DKIM key. The full walkthrough — including the autonomous "set brand → read CNAMEs → apply_cloudflare_dns → verify → poll" agent flow — is in the White Label Branding API and MCP Guide.

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 isn't on your plan. Nano covers Email Verifier (and Drive if you've bought the Drive Storage Add-on). Upgrade to Starter or higher for the rest of the API.
• 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.

Sending email — body, headers, deliverability

POST /api/v1/messages/send takes the request shape {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• body.text and body.html are both optional, but at least one is required. If you provide only body.text we auto-generate an HTML alternative using <p> paragraphs (blank lines split paragraphs; single newlines become <br>) so the message renders as ordinary email in every modern client. If you need monospace, send the literal <pre>...</pre> in body.html.
• headers is an optional object of user-supplied outbound headers. The whitelist is List-Unsubscribe, List-Unsubscribe-Post, Reply-To, and any X-* custom tracking header. Other names (From, Subject, Message-Id, Authentication-Results, etc.) are platform-managed and rejected with 422. Values containing CR/LF are also rejected (header injection protection). Values are capped at 998 chars per RFC 2822.
• For bulk/automation use cases, see the Bulk-sender deliverability headers section for List-Unsubscribe setup and the account-wide auto_list_unsubscribe toggle.