Connected Accounts via API and MCP

Connected accounts let a webmail mailbox read and send from external mailboxes — Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365, or any IMAP server. The message API and the MCP tools expose the same capability programmatically: you can list, add, test, edit, and remove connected accounts, and you can point ordinary message calls (list, read, send, flags, move, delete, folders) at a connected account instead of the token's own mailbox.

In plain English: mailbox_id chooses the TrekMail mailbox the agent may act for, while external_account_id chooses Gmail or another connected inbox inside it. They are not interchangeable.

Plans, limits, and catalog size

The full product surface currently has 259 REST API routes and 248 stdio MCP tools: 186 operations tools plus 62 message tools. Connected-account management contributes seven message tools. A scoped token only receives the tools it can actually use; it does not load the full catalog.

Before you start

• Connected accounts are a webmail feature and use the message token surface (/api/v1/messages/...), authorized by a message token with the scopes below — not a dashboard API token.
• Plan limits apply per mailbox: Starter 5, Pro 10, Agency 30. The Nano plan does not include connected accounts.
• Every endpoint is scoped to the token's own mailbox. A token can only see and manage its own connected accounts — never another mailbox's.
• Credentials and OAuth tokens are always masked in responses. You can write a password or app password; you can never read one back.
• Outlook.com and Microsoft 365 accounts connect through Microsoft sign-in (OAuth) in the webmail UI. The API can manage and use them once connected, but it does not perform the interactive Microsoft consent step.

Scopes

Targeting a connected account in a message call requires the same scope that call already needs (for example, listing its messages needs messages:read; sending needs messages:send).

Managing connected accounts

Base path: /api/v1/messages/external-accounts

Add an account

POST /api/v1/messages/external-accounts
Scope: messages:write

Request body:

Call POST /external-accounts/detect first to fill in provider and the server settings automatically. The store call runs a live IMAP + SMTP test before saving — a 422 with an error category (auth, tls, network, transient_throttle) means the credentials didn't work and nothing was stored.

Targeting a connected account in message calls

Every message endpoint that operates on a mailbox accepts an optional external_account_id. Provide it to run the call against that connected account instead of the token's own mailbox; omit it to use the mailbox itself. This applies to listing, reading, sending, replying, flags, move, delete, and folder listing.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

Sending with only external_account_id goes out through that account's own SMTP server (its provider's SPF/DKIM). Supplying a source-bound identity_id instead uses that Send As identity's domain or saved-profile route, while still saving the Sent copy in the connected inbox. The account must be healthy (status: active); a disconnected account returns an error asking you to reconnect it. See Send As Addresses via API and MCP.

MCP tools

The same capability is available to AI agents over MCP (both the private stdio server and the public MCP server):

The message tools — list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all, and prepare_forward — accept the optional external_account_id argument. Sending, drafting, and scheduling also accept a source-bound identity_id returned by list_identities.

Because the manage tools open outbound connections to arbitrary mail servers with user-supplied credentials, they follow the same safety posture as the rest of the connected-accounts feature: host allow-listing, blocked private ranges, a port allow-list, and per-host connection ceilings.