Mail client setup via API and MCP

Give a user the same password-free server settings, sending status, and app-specific guidance shown in Apps & devices.

Passwords stay with the user. Neither endpoint nor either MCP tool returns a mailbox password or a custom SMTP provider secret. The user enters the mailbox password directly in the email app.

Retrieve setup information

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

The response includes the IMAP and SMTP host, port, security, username, real sending readiness, and localized three-step guides for Gmail, Outlook, Apple Mail, Thunderbird, and another IMAP app.

Treat receiving_only as incomplete. Configure or restore outgoing mail before telling a user to connect an app that checks both servers.

Generate an Apple Mail profile

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

The response is a .mobileconfig download. The profile contains the address and server settings, but never a password. TrekMail returns 409 mail_client_setup_not_ready if outgoing mail is not ready.

MCP tools

Tool	What it returns
`get_mail_client_setup`	Password-free settings, current sending readiness, and five localized guides.
`get_apple_mail_profile`	A filename, media type, and base64-encoded Apple configuration profile.

Decode content_base64 into bytes and save it with the returned filename. Do not treat the profile itself as JSON or UTF-8 text.

Access and language

The REST endpoints require mailboxes:read and enforce domain and mailbox token constraints.
The hosted MCP tools require the OAuth scope mail:read.
The optional language value supports all 13 TrekMail interface languages. Without it, TrekMail checks Accept-Language and then uses the default locale.
Both MCP tools are read-only and do not need destructive-operation flags.

Common errors

`not_found`	The mailbox does not exist or is outside the token constraints.
`mailbox_unavailable`	The mailbox is inactive.
`direct_login_unavailable`	A shared mailbox has no separate password login.
`mail_client_setup_not_ready`	Outgoing mail is not ready for an Apple profile; inspect the returned reason.
`forbidden`	The token or current plan does not permit mailbox read access.

For the end-user flow, see Connect TrekMail to Any Email App.

Keep reading

←

Connected Accounts via API and MCP

Manage connected external mailboxes and target them in message calls through the TrekMail message API and MCP tools — endpoints, scopes, and external_account_id.

Managing Contacts via API and MCP

Create, import, export, search, and organize contacts and groups in TrekMail through the message API and MCP tools — endpoints, scopes, and pagination.

→