TrekMail REST API Overview for Developers

Open TrekMail in Claude, choose Connect, sign in and approve access. You do not need to create an API token. To review permissions or disconnect, open AI Agents & API, Tokens, Connected apps.

Your own White Label brand: use the MCP address shown in your branded dashboard and name the connector after your brand. Add it as a custom connector; the public TrekMail listing signs in on TrekMail and does not replace your branded connection.

The TrekMail API lets you manage domains, mailboxes, forwarding, DNS, email migrations, and webmail operations from an HTTP client or AI agent. That includes reading and sending mail, drafts, scheduling, folders, contacts, calendars, identities, templates, and blocked senders. Authenticated requests use a bearer token, responses are JSON, and API activity is audited.

Read email with one key

On Pro and Agency, choose Read email when creating an API key. The explicit scope is mailboxes:messages:read; mailboxes:read only lists mailbox addresses and setup details. Select all mailboxes to include current and future mailboxes, or restrict access to selected domains and mailboxes. Existing keys gain no new permission automatically.

Use the account key with the GET routes below. Sending, deletion and other changes still require separate message credentials and permissions. Hosted MCP accepts OAuth, not tm_live_ or tm_msg_. A token-type error tells the agent which endpoint or authorization method to use.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

What you get

• REST API v1 with a JSON request/response format.
• Bearer token authentication: no cookies or sessions for authenticated API calls.
• Idempotency keys on the write operations that require them, preventing duplicate work during retries.
• Per-token rate limiting with Retry-After headers.
• Audit Log visible in your dashboard under AI Agents & API, Audit Log.
• MCP server with a catalog filtered to the credential, transport, and safety settings of the current connection. A narrow project connection therefore sees only the tools it can use.
• Domain aliases: connect receive-only addresses on a secondary domain to the same local parts on a primary domain, with saved-versus-live delivery states and safe removal. See Domain Aliases via API and MCP.
• Credential types: account keys for infrastructure and explicit mailbox message reads, and mailbox tokens for full email operations such as reading, sending, drafting, scheduling, contacts, calendars, identities, templates, and folders.
• Outbound deliverability and bounce insights: pull the sent, delivered, hard-bounce, and soft-bounce rollup from the dashboard, plus per-recipient SMTP codes and responses. See Deliverability and Bounces.
• Mail app passwords: manage separate passwords for IMAP, SMTP, calendars and contacts, and set which passwords mail apps accept. These do not replace API bearer tokens or Message API tokens. See Mail App Passwords via API and MCP.
• Mailbox storage usage: list_mailboxes and get_mailbox return used_mb, quota_mb, allocation_mb, and is_pooled, so an agent can spot mailboxes approaching their limit without dashboard access.
• White Label administration: inspect setup, manage per-domain branding, invite clients, control roles and domains, suspend or restore access, and review activity through API or MCP. See the branding guide and team-management guide.

Drive API and file automation

Drive is part of the public API surface. It covers Account Drive and mailbox Drive spaces, usage, folder browsing, uploads, file and folder management, Trash, bulk actions, public share links, sync-device password management, 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 for full Drive API and MCP access.
  • Starter: Full Drive, full Email Verifier, and read-only access across the remaining infrastructure areas. Use the dashboard for those write actions.
  • Pro / Agency: Full base API access, including message tokens. White Label scopes are added while its trial or paid add-on is active.
• 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 and cannot be displayed again.

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. Message sends have one exception: once a send's delivery has failed (on a sending limit, for example), the API no longer replays its earlier 202, so the same message can be sent again later with the same content. If you pass your own X-Request-Id, give that attempt a new one: the API also treats a send from the same mailbox with the same X-Request-Id as a repeat, so the old one only gets the original, failed delivery back and nothing is sent. A retry of a send that is still pending or was delivered is still answered with the original response.

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 check each dedicated item against what is left when that item is created: items that fit are created, and those that no longer fit fail individually with reason storage_pool_exceeded (207 partial success, or 422 when every item fails). In a domain under a White Label client storage limit, a fixed size must also fit what that limit has left: a single create or invite returns 422 client_storage_limit_exceeded with limit_mb, allocated_mb, available_mb, and requested_mb in details (a key confined to some domains gets only available_mb and requested_mb when the limit also covers a domain outside its reach), and a bulk item fails with reason client_storage_limit_exceeded. 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.

To change an existing mailbox, send PATCH /api/v1/mailboxes/{id}/storage with storage_allocation_mb set to a fixed size in MB, or to null for shared storage. It needs mailboxes:write and an Idempotency-Key, works on active and paused mailboxes, and runs the same checks as the dashboard's Edit storage: storage_pool_exceeded when the account's free storage is too small and, in a domain under a client storage limit, client_storage_limit_exceeded, or client_storage_below_usage when the new size is below what the mailbox already stores. Shared storage is never refused for its size. A mailbox in Recently deleted or being deleted returns 422 mailbox_unavailable. The MCP tool is set_mailbox_storage.

White Label client storage limits live under /api/v1/white-label/client-limits; see Manage White Label Teams with API and MCP. A key confined to some domains sees only its share of the account in GET /api/v1/account: usage counts only its domains and mailboxes, limits.max_storage_mb is the client's limit when all of its domains share one that covers no other domain, and client_limit holds that limit (id, storage_limit_mb, allocated_mb, used_bytes) or null. Other callers get the response unchanged.

New regular mailboxes, including bulk creation, invites and AI-agent provisioning, follow Account settings > New mailboxes > Mail apps need app passwords, on by default. Changing it does not switch existing mailboxes. POST /api/v1/mailboxes can choose a client_auth_mode of app_password_only or password_or_app_password; if omitted, the account setting applies. Mailbox list and detail resources report client_auth_mode and app_passwords_count (active app passwords). Shared mailboxes have no app passwords or sign-in mode of their own.

The six MCP tools for app-password management are list_mailbox_app_passwords, create_mailbox_app_password, rotate_mailbox_app_password, revoke_mailbox_app_password, set_mailbox_client_auth_mode, update_account. update_account: Set new_mailbox_client_auth_mode for future mailboxes; existing mailboxes keep their mode. Requires mailboxes:write, an unrestricted owner token or connector, and TREKMAIL_ALLOW_DESTRUCTIVE=true in self-hosted stdio.

Mailbox Drive access

Every mailbox carries a drive_access level that decides how much of Drive the person using it reaches in webmail. It is returned on the mailbox resource and can be set with PATCH /api/v1/mailboxes/{id} or, for many mailboxes at once, POST /api/v1/mailboxes:drive-access.

Storage is pooled across the account, so this is the control for how much of that pool a single person can fill with files.

Mailbox sign-in suspension

A mailbox can have its sign-in suspended while it carries on receiving mail: webmail, IMAP, SMTP and device passwords are refused and open sessions end, but delivery is untouched, so nothing bounces and everything is waiting when sign-in is restored. Set it with POST /api/v1/mailboxes/{id}:suspend-login (and :resume-login), or across many mailboxes with POST /api/v1/mailboxes:login-access.

The mailbox resource reports it as login_suspended, login_suspended_at and login_suspended_reason. Read login_suspended for whether the person can sign in, and status for whether the mailbox itself is running, a suspended mailbox stays active, because it is still accepting mail. :pause is the other thing: it sets status to disabled and stops delivery as well.

Suspension permanently revokes all app passwords. Restoring sign-in does not restore them. An admin setting a new mailbox password through the dashboard, API or AI agent also revokes all app passwords, as do password recovery, conversion to shared, and moving to Recently deleted. Restoring a deleted mailbox does not bring them back.

See Suspending Mailbox Sign-In via API.

The bulk endpoint takes exactly one selector, mailbox_ids, domain_id, or all, and returns what it did:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

domain_id is the selector to reach for when a domain is one customer. Mailboxes already on the requested level count as matched but not updated, so the call is safe to repeat.

Shared mailboxes are refused on the single endpoint with 422 drive_access_not_applicable and skipped (and counted) by the bulk one: they have no webmail user of their own, so members open them with their own level and a value stored on the shared row would change nothing.

The restriction applies to the API as well as the interface. A restricted mailbox's Drive space is absent from GET /api/v1/drive/spaces, its files answer 404 by id, and a sync device cannot be created for it.

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": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max is per domain and depends on the plan, 100 on Pro, 300 on Agency, and 25 saved-but-inactive on Nano or Starter.
• 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 has its own team inbox. can_read is the Read permission; can_send is Send as. Opening shared folders needs Read. Sending through the Message API from the shared inbox needs both. There is no shared password or separate sign-in, and 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.

Converting back removes every member. Set a new webmail password, then create app passwords for mail apps on the Security tab.

Permission changes can return 422 no_access_left when both permissions would be off, 422 send_only_disabled when the requested Read change is unavailable, or 422 last_reader when the last active reader would lose access. Use Remove to end all access, and give another active member Read before removing the last reader. Each of these errors also returns shared_mailbox_id, member_id for an existing member, and a hint naming the request that fixes it.

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

shared_mailboxes.items[] includes only memberships with Read when native folder access is enabled. delegated_send_addresses is a separate list of available team From addresses, each with id, email, and display_name; it can be empty. It grants no folder access and is not a sending-readiness check. These addresses are not Message API identities. Use the returned hosts, including for White Label, rather than copying a platform hostname.

Removing a member, changing can_read / 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.
• This route changes only its own domain. To make a route the account default (the dashboard's Make this the account default), use PUT /api/v1/smtp/default below; add apply_to_all: true to also switch every domain to it (Apply to all domains).

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

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

A key limited to some domains or mailboxes gets 403 token_resource_constrained from PUT /api/v1/smtp/default, from the legacy PUT and DELETE /api/v1/smtp, and when it deletes a saved profile, because each of these changes the route of domains it may not reach. A key limited to some domains gets the same answer when it edits a profile that a domain outside its list also uses.

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.

White Label branding, clients, and team access

Branding is configured per domain with branding:read / branding:write. A domain runs its own brand (mode=custom), inherits the account default (mode=inherit), or is off. An active White Label trial or paid add-on is required. After cancellation, the owner keeps read-only recovery access during the displayed grace window. Read the domain's dns_records and publish those returned records exactly. Do not derive hostnames or CNAME targets from an example.

PATCH is a partial merge, so omitted fields are preserved. If branding is currently off, pass mode to re-enable it. A custom sender_email must be on a domain with a verified DKIM key. mail_zone_enabled serves mail apps and DAV sync under the brand's own domain. It belongs to the brand rather than a single domain, so it needs mode=custom or scope=account_default; an inherit domain returns 422 inherited_brand. Read mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url, and mail_zone.dav_ready to track provisioning and use only a ready DAV address. For the full agent workflow, see the White Label Branding API and MCP Guide.

The account-level White Label surface adds 18 routes under /api/v1/white-label: status and setup progress, a live access catalog, member listing and lifecycle actions, client storage limits, account activity, and per-member action/sign-in history. It uses members:read, members:write, and activity:read. Access is always the intersection of account entitlement, the person's current membership, the credential grant, and any domain constraint. See Manage White Label Teams with API and MCP for the route table and state transitions.

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.
• 403 "scope_blocked_by_entitlement": A stored White Label grant is unavailable because the add-on is inactive or the operation is a write during grace. Reactivate White Label, then retry with the same credential.
• 403 "scope_blocked_by_membership": The current member role is narrower than the requested action. Ask the owner to change it; reauthorizing alone cannot widen membership.
• 422 "missing_idempotency_key": Add an Idempotency-Key header to the write operation named by the endpoint reference.
• 403 "mailbox_sending_paused": Sending from that mailbox has been stopped because its outbound mail stopped looking like its owner, usually a password in the wrong hands. Reading, listing and every other endpoint still work; only sending is refused, and retrying will not clear it. The mailbox password needs changing, after which support switches sending back on. See Why Can't I Send Email?.
• 403 "account_sending_on_hold": Sending from the whole account is held while TrekMail reviews it. Receiving and every other endpoint keep working; retrying will not clear it. Contact support to have the hold reviewed.
• 403 "mailbox_send_disabled": Sending is switched off for this one mailbox. Reading and every other endpoint keep working; retrying will not clear it. Usually the mailbox falls outside the plan: its domain is beyond the number of domains the plan includes, or the mailbox is beyond the plan's mailboxes per domain (the oldest domains and mailboxes keep sending). This happens after a move to a smaller plan. It can also be a mailbox created before its domain finished setup. Upgrading turns sending back on at once; after you remove the extra domains or mailboxes, or once the domain finishes setup, it comes back within a day. If none of this applies, contact support.
• 403 "account_email_unverified": Sending is blocked until the account owner verifies their sign-in email. Accounts registered on or after 19 February 2026 have 7 days to do it, and the same 7 days start again when a verified sign-in email is replaced with a new one. Reading and every other endpoint keep working; retrying will not clear it. Open the link in the verification email, or use Resend verification email in the dashboard banner; sending works again as soon as the address is verified. See Why Can't I Send Email?.
• 429 rate limited: Wait for the duration in the Retry-After header before retrying. The per-mailbox daily API cap also answers rate_limited, but with retryable set to false, dimension set to api_mailbox_daily, and a resets_at time: retrying sooner will not work, so wait until then.
• 429 "sending_limit_exceeded": A sending allowance is used up. dimension says which one and resets_at says when it renews. Retrying earlier cannot work, so retryable is false. GET /api/v1/messages/sending-limits shows in remaining_today how many more recipients the mailbox can reach today. When the lowest allowance is the account-wide total, limit_today is null and remaining_today is null until that total is spent (then 0); an ops token reads the total from GET /api/v1/sending-limits. If dimension is recipients_per_message, split the message into smaller ones instead. In the first 24 hours after the account's first payment the causes include new_payer, and GET /api/v1/sending-limits gives the moment the plan's full limits apply in full_limits_at. See Sending Limits per Plan.

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.

A 202 means the message was accepted, not yet sent. Sending allowances are checked again when the message leaves the queue, so check the outcome with GET /api/v1/messages/deliveries/{request_id}, using the request_id from the 202. Any message token for the same mailbox can check it, not only the token that sent the message; an unknown request_id returns 404. If a limit stopped it, status is failed and failure names the limit (dimension) and when it renews (resets_at). A failed send can be sent again later with the same content. If you pass your own X-Request-Id, use a new one for it, since the old one only returns the original delivery. A scheduled message that reaches a limit when it is due is held as limit_reached and kept for 7 days: list these with GET /api/v1/messages/scheduled?status=limit_reached, send one later by giving it a new scheduled_for with PATCH /api/v1/messages/scheduled/{id}, or remove it with DELETE.