Настройка почтового клиента через API и MCP

TrekMail предоставляет через REST и MCP те же данные подключения из раздела Приложения и устройства, которые используются в панели управления. Оба интерфейса доступны только для чтения и требуют права чтения почтового ящика.

Они никогда не возвращают пароль ящика, пароль приложения или учётные данные стороннего SMTP-провайдера. Пользователь вводит в почтовом приложении пароль приложения или пароль ящика, если ящик ещё принимает его. Даже если исходящие сообщения домена проходят через стороннего провайдера, внешние приложения отправляют их на публичный SMTP endpoint TrekMail; затем TrekMail применяет закрытый маршрут домена.

Получение настроек подключения

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

Необходимая внутренняя область: mailboxes:read. Необязательные ограничения токена domain_ids и mailbox_ids применяются автоматически.

Ответ содержит:

• хост входящего IMAP, порт SSL, имя пользователя и состояние готовности;
• хост исходящего SMTP, порт SSL, имя пользователя и состояние готовности;
• URL сервера DAV для календарей и контактов, готовность подключения и признак фирменного адреса;
• те же локализованные трехэтапные инструкции для Gmail, Outlook, Apple Mail, Thunderbird и обычного IMAP, что показаны в разделе Приложения и устройства;
• sending.mode: platform, profile или not_configured;
• sending.reason: стабильную машиночитаемую причину, если исходящая почта не готова;
• apple_mail_profile.available, равное true только при готовности приема и отправки;
• shared_mailboxes.native_access_enabled, namespace, items[];
• authentication.client_auth_mode: app_password_only или password_or_app_password;
• authentication.accepted_passwords: соответственно ["app_password"] или ["mailbox_password", "app_password"];
• authentication.app_passwords_endpoint: endpoint управления паролями приложений ящика;
• password_included: false как явную гарантию безопасности.

shared_mailboxes.items[] содержит только участников с правом Чтение, когда общие папки в почтовых приложениях включены. delegated_send_addresses представляет собой отдельный список доступных адресов команды в поле От с полями id, email и display_name; он может быть пустым. Он не даёт доступа к папкам и не проверяет готовность отправки. Эти адреса не являются идентификаторами Message API. Используйте полученные серверы, в том числе в White Label, вместо имени сервера платформы.

Каждый делегированный элемент содержит постоянные native_access_status/native_access_ready, точные стандартные пути в folders, заданные сервером operations и фактические send_as_ready/send_as_reason. can_send по-прежнему обозначает назначенное администратором разрешение Отправка от имени; оно может быть true при недоступном SMTP, поэтому автоматизация должна проверять оба поля готовности. Неактивный ящик участника, приостановленный вход или отключенный прямой вход не скрывает общий ящик, но возвращает mailbox_unavailable, mailbox_login_suspended или direct_login_unavailable как причину недоступности отправки от имени общего адреса. Устаревшее поле folder сохраняет точный путь к Входящим. Дождитесь native_access_ready=true, прежде чем давать инструкции по настройке.

SMTP передает ответ или пересланное письмо, но не сохраняет копию в Отправленных. Поэтому sent_copy.smtp_saves_copy равно false; настройте клиент на добавление копии в sent_copy.folder (то же значение, что у folders.sent), чтобы ее видела вся команда. folders.archive и folders.junk задают точные назначения, если клиент не сопоставляет Архив или Спам автоматически. Перемещение в Спам само по себе не гарантирует обучение серверного классификатора.

Всегда запрашивайте этот endpoint с ID обычного ящика участника и используйте в клиенте собственный адрес участника и пароль приложения или пароль ящика, если он принимается. Не создавайте вторую учётную запись и не пытайтесь войти напрямую с общим адресом.

Список папок shared_mailboxes описывает нативный доступ тех, кто может читать общий ящик. Если items пуст, проверьте нативный доступ и Чтение. Пустой список не доказывает, что убраны все права на общие адреса. Пароль не возвращается.

Необязательный параметр lang принимает те же 13 языков, что endpoint профиля Apple. Если он пропущен, TrekMail использует Accept-Language, затем локаль по умолчанию. У каждой инструкции есть стабильный id, три локализованных steps и action: use_server_settings или download_apple_profile.

connection_status=receiving_only не означает успешную полную настройку. Настройте или восстановите исходящий маршрут домена, прежде чем предлагать подключить клиент, проверяющий оба сервера.

connection_status=unavailable означает, что жизненный цикл ящика изменился и прямая аутентификация больше невозможна. Не используйте возвращенные координаты серверов и не предлагайте профиль Apple Mail; вместо этого обновите состояние ящика.

Скачивание профиля Apple Mail

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

Ответ представляет собой вложение .mobileconfig. Поддерживаются значения lang: en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar и he. Без lang TrekMail использует Accept-Language, затем локаль по умолчанию.

Профиль содержит настройки IMAP и SMTP, но не поля пароля. Apple запрашивает пароль при установке: для app_password_only используйте пароль приложения, а для password_or_app_password любой из двух принимаемых паролей. TrekMail возвращает 409 mail_client_setup_not_ready, а не создаёт вводящий в заблуждение профиль при недоступной исходящей почте.

Создайте пароль приложения в веб-почте в разделе Настройки, Пароли приложений или в панели управления: Почтовые ящики, (ящик), Безопасность, Пароли приложений. Endpoint настройки доступен только для чтения и не создаёт пароль. Об endpoint REST и инструментах MCP для управления паролями и режимом входа см. Пароли приложений через API и MCP.

Инструменты MCP

Инструменты используют те же REST endpoints и правила авторизации:

Транспорт MCP возвращает структурированное содержимое инструмента, а не загрузку браузера. Декодируйте content_base64 в байты и сохраните с именем file_name; не интерпретируйте его как JSON или UTF-8 до декодирования.

Оба инструмента требуют размещенную область OAuth mail:read, которая расширяется до внутренней mailboxes:read. Они доступны только для чтения и не зависят от переменной окружения для разрушительных операций в самостоятельно размещенном stdio-сервере.

Ошибки

Endpoint настройки может вернуть значения sending.reason: 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 или smtp_route_invalid.