Mail client setup via API and MCP
Give a user the same password-free server settings, sending status, delegated shared-mailbox folders, and app-specific guidance shown in Apps & devices.
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.
For a regular mailbox that belongs to team inboxes, shared_mailboxes reports durable access readiness, exact Inbox/Sent/Archive/Junk paths, read/flag/folder/move/delete/send-as capabilities, and effective send_as_ready/send_as_reason. The Can reply permission may be present while SMTP is unavailable, so check both readiness fields. An inactive, sign-in-suspended, or direct-login-disabled member mailbox remains discoverable but returns the corresponding mailbox_unavailable, mailbox_login_suspended, or direct_login_unavailable Send As reason. The member signs in with their own address and password; no shared or member password is returned.
SMTP does not save a Sent copy. Configure the client to append it to sent_copy.folder so replies and forwards remain visible to the team. Moving a message to folders.junk is supported, but does not promise spam-classifier training.
Treat receiving_only as incomplete. Configure or restore outgoing mail before telling a user to connect an app that checks both servers.
Treat unavailable as unusable: the mailbox lifecycle no longer permits direct authentication. Refresh mailbox state instead of offering its settings or an Apple Mail profile.
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-configThe 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, delegated shared-mailbox folders, 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:readand 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-Languageand 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 | The id belongs to a shared mailbox. Request setup for a regular member mailbox and inspect shared_mailboxes.items. |
mailbox_login_suspended | Sign-in is suspended for this mailbox. It still receives mail, but there are no client settings to hand out until sign-in is restored. |
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 end-user flows, see Connect TrekMail to Any Email App and Use a Shared Mailbox in Your Mail App.