Настройка почтового клиента через 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, настроенное пространство имен и элемент items[] для каждого общего ящика, делегированного этому обычному ящику;
• password_included: false как явную гарантию безопасности.

Каждый делегированный элемент содержит постоянные 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.native_access_enabled равно false, а items пуст. Если доступ включен, но 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 запрашивает пароль ящика при установке. TrekMail возвращает 409 mail_client_setup_not_ready, а не создает вводящий в заблуждение профиль при недоступной исходящей почте.

Инструменты 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.