Mail Client Setup via API and MCP

TrekMail exposes the same Apps & devices connection data used by the dashboard through REST and MCP. Both interfaces are read-only and require mailbox read access.

They never return the mailbox password or credentials for a custom SMTP provider. The user enters the mailbox password directly in their mail app. Even when a domain routes outgoing messages through a custom provider, external mail apps submit to TrekMail's public SMTP endpoint; TrekMail applies the private domain route behind it.

Get connection settings

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

Required internal scope: mailboxes:read. A token's optional domain_ids and mailbox_ids constraints are enforced.

The response contains:

• incoming IMAP host, SSL port, username, and readiness;
• outgoing SMTP host, SSL port, username, and readiness;
• the DAV server URL for calendars and contacts, its connection readiness, and whether the returned address is branded;
• the same localized three-step Gmail, Outlook, Apple Mail, Thunderbird, and generic IMAP guides shown in Apps & devices;
• sending.mode: platform, profile, or not_configured;
• sending.reason: a stable machine-readable reason when outgoing mail is not ready;
• apple_mail_profile.available, which is true only when both receiving and sending are ready;
• shared_mailboxes.native_access_enabled, the configured namespace, and one items[] entry for every shared mailbox delegated to this regular mailbox;
• password_included: false as an explicit safety guarantee.

Each delegated shared-mailbox item contains durable native_access_status/native_access_ready, exact standard paths under folders, server-enforced operations, and effective send_as_ready/send_as_reason. can_send remains the administrator-assigned Can reply permission; it can be true while SMTP is unavailable, so automation must check both readiness fields. A member mailbox that is inactive, sign-in suspended, or direct-login disabled leaves the shared mailbox discoverable but returns mailbox_unavailable, mailbox_login_suspended, or direct_login_unavailable as its Send As reason. The legacy folder field remains the exact Inbox path. Wait for native_access_ready=true before guiding a user through setup.

SMTP transports a reply or forward but does not save its Sent copy. sent_copy.smtp_saves_copy is therefore false; configure the client to append the copy to sent_copy.folder (the same value as folders.sent) so the whole team can see it. folders.archive and folders.junk are exact move targets when a client does not map Archive or Spam automatically. Moving to Junk does not by itself promise server-side spam-classifier training.

Always request this endpoint with the regular member mailbox id and authenticate the mail client with that member's own address and password. Do not create a second account or attempt direct authentication with the shared address.

When native access is disabled, shared_mailboxes.native_access_enabled is false and items is empty. When it is enabled but items is empty, the regular mailbox currently has no active shared-mailbox membership. No shared or member password is ever included in either case.

The optional lang parameter accepts the same 13 languages as the Apple profile endpoint. If it is omitted, TrekMail uses Accept-Language and then the default locale. Each guide has a stable id, three localized steps, and an action: use_server_settings or download_apple_profile.

connection_status=receiving_only is not a successful full setup. Configure or restore the domain's outgoing route before instructing the user to connect a client that validates both servers.

connection_status=unavailable means the mailbox lifecycle changed and it can no longer authenticate directly. Do not use the returned server coordinates or offer an Apple Mail profile; refresh mailbox state instead.

Download 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 attachment. Supported lang values are en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar, and he. If lang is omitted, TrekMail uses Accept-Language and then the default locale.

The profile contains IMAP and SMTP settings but no password fields. Apple asks the user for the mailbox password during installation. TrekMail returns 409 mail_client_setup_not_ready instead of generating a misleading profile while outgoing mail is unavailable.

MCP tools

The tools use the same REST endpoints and authorization rules:

MCP transports return structured tool content rather than a browser download. Decode content_base64 as bytes and save it using file_name; do not reinterpret it as JSON or UTF-8 before decoding.

Both tools require the hosted OAuth scope mail:read, which expands to the internal mailboxes:read scope. They are marked read-only and do not depend on any destructive-operation environment flag in the self-hosted stdio server.

Errors

The setup endpoint may return these sending.reason values: mailbox_unavailable, direct_login_unavailable, domain_unavailable, domain_deprovisioning, account_suspended, email_verification_required, mailbox_sending_disabled, smtp_not_configured, managed_smtp_not_in_plan, managed_smtp_entitlement_inactive, smtp_profile_unavailable, or smtp_route_invalid.