Пароли почтовых приложений через API и MCP

REST API и MCP позволяют получать список паролей приложений обычного ящика, создавать, заменять и отзывать их, менять режим входа почтовых программ и задавать настройку аккаунта для будущих ящиков. Эта страница служит справочником для интеграций. Инструкции для панели и веб-почты: Пароли приложений для почтовых устройств.

Пароль приложения открывает IMAP, SMTP на портах 465 и 587, ManageSieve и CalDAV/CardDAV. Он никогда не открывает новую веб-почту или панель. Классическая веб-почта входит через IMAP и принимает пароли приложений. 2FA ящика защищает только вход в новую веб-почту; почтовые программы и классическая веб-почта никогда не запрашивают её код.

У функции нет отдельного ограничения по тарифу ящика. Существующие разрешения тарифов для API и MCP продолжают действовать; см. Разрешения и области доступа API.

Аутентификация, области доступа и разрешения участников

Используйте Bearer-токен в REST-запросах к /api/v1. Запись в формате JSON использует Content-Type: application/json и заголовок Idempotency-Key.

Разрешение задавать пароль проверяется в роли участника, дополнительно к области доступа API токена. Это относится к токенам участников и коннекторам, авторизованным участниками. Токену владельца не нужна дополнительная область доступа для задания пароля. Отсутствие разрешения участника возвращает 403 scope_blocked_by_membership.

Размещённые OAuth-коннекторы могут использовать соответствующие области доступа возможностей REST. В старых наборах mail:read предоставляет mailboxes:read и account:read; mail:write также предоставляет mailboxes:write. Расширение областей доступа никогда не отменяет правила разрешений участников или ограничение «только владелец».

Ограничения токена domain_ids и mailbox_ids действуют и для массовых выборок. Endpoint паролей приложений и оба endpoint режимов возвращают 404 not_found, когда функция выключена, после аутентификации и проверок middleware. Недоступный или отсутствующий ящик также возвращает 404, поэтому не считайте любой 404 признаком состояния функции.

Краткий список endpoint

Пути ниже включают префикс /api/v1. {mailbox} обозначает ID обычного ящика; {id} обозначает ID принадлежащей ему записи пароля приложения.

Все операции записи в этой таблице требуют Idempotency-Key. Endpoint пароля выполняет существующую операцию административного сброса, отдельную от замены пароля приложения.

Список паролей приложений и поля записи

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

Ответ содержит поля верхнего уровня mailbox_id, client_auth_mode, limit, active_count и data, массив записей. limit равен 25 активным паролям на ящик. Активные записи идут первыми, начиная с самых новых; отозванные видны 90 дней. Ни один ответ со списком не содержит секретного значения.

Каждая запись содержит:

Публичные причины отзыва: revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared и mailbox_trashed. Список не включает учётные данные, созданные платформой для внутреннего использования.

Создание пароля приложения

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

Поле name обязательно: от 1 до 64 печатных символов. Последовательности пробельных символов заменяются одним пробелом. Ящик должен быть активным обычным ящиком без приостановки входа и с менее чем 25 активными паролями приложений.

Ответ 201 содержит полную запись в data, добавляет data.password и включает message. Например, поля учётных данных в ответе:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

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

Пароль возвращается только один раз. Не записывайте его в журналы приложения. Пользователь вводит его прямо в почтовую программу с полным адресом ящика в качестве имени пользователя. Создание и замена отправляют на ящик и его адрес восстановления, если задан, уведомление с названием пароля, но без самого пароля. Исключение составляет первый пароль приложения, выданный вместе с новым ящиком (см. ниже).

Используйте API настройки почтового клиента для получения параметров подключения. Скачанный профиль Apple не содержит пароля; пользователь вводит пароль приложения по запросу macOS или iOS при установке.

Первый пароль приложения вместе с новым ящиком

POST /api/v1/mailboxes и POST /api/v1/mailboxes:bulk принимают необязательный логический параметр create_app_password. При значении true каждый созданный ящик также получает первый пароль приложения, который возвращается один раз в поле app_password: поля записи, описанные выше, плюс password. Он называется Created with the mailbox, и уведомление по email о нём не отправляется, потому что ящик новый, а вызывающая сторона только что получила его пароль. Без этого поля (по умолчанию false) ответ не меняется. Пока пароли приложений не включены, поле игнорируется.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

Тогда ответ 201 содержит one_time_password, пароль ящика для веб-почты, и app_password.password для почтовых программ. В массовом ответе у каждой созданной строки свой app_password. Если выдать пароль не удалось, app_password равен null (при одиночном создании также добавляется _app_password_warning); ящик всё равно создаётся, и пароль можно создать через описанный выше эндпоинт, описанный выше. Точный повтор одиночного создания с тем же Idempotency-Key возвращает тот же ответ вместе с обоими паролями и не выдаёт второй пароль приложения. Повтор массового запроса не содержит паролей, как и в случае one_time_password.

Замена или отзыв пароля

Для замены тело JSON не требуется:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

Ответ 200 содержит новую полную запись в data, её однократно выдаваемый data.password, поле верхнего уровня replaced_id с ID старой записи и message. У замены новый data.id и прежнее название. Старая запись отзывается с revoked_reason: "rotated", её пароль сразу перестаёт работать, а программы с ним отключаются. Укажите новый пароль на устройстве.

Чтобы отозвать пароль без выпуска замены:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

Тело не требуется. Ответ 200 содержит status: "revoked" и полную отозванную запись в data. Программа теряет доступ; другие устройства с действующими паролями приложений переподключаются самостоятельно. Отзыв нельзя отменить. Попытка заменить или отозвать уже отозванную запись новым запросом возвращает 409 conflict.

Изменение режима входа почтовых программ одного ящика

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

Поле mode обязательно и принимает:

• app_password_only: почтовым программам нужен пароль приложения. Подключения с паролем ящика отключаются; программы с действующим паролем приложения переподключаются самостоятельно.
• password_or_app_password: почтовые программы принимают пароль ящика или приложения.

Ответ 200 содержит mailbox_id, client_auth_mode и message. Повторная установка текущего режима возвращает 200 и ничего не меняет. Изменение режима не отзывает существующие пароли приложений.

Создайте пароли для устройств до того, как сделать их обязательными. При отклонении входа с паролем ящика может появиться сообщение: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Вход не выполнен. Этот ящик принимает только пароли приложений: создайте пароль в веб-почте в разделе Настройки > Пароли приложений.) Некоторые программы показывают только общую ошибку пароля.

У общих ящиков нет прямого входа, и этот endpoint возвращает для них 422 mailbox_not_eligible. Системные ящики платформы нельзя переключать на app_password_only; возвращается 422 system_mailbox_protected.

Ни один режим не меняет вход в новую веб-почту, Все ящики, токены Message API, импорт в ящик, почтовые правила или пересылку. Участники общего ящика используют учётные данные и режим своего обычного ящика.

Массовое изменение режимов

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Передайте mode и ровно один селектор:

Ограничения аккаунта и токена сужают любую выборку. Явно указанный недоступный или неизвестный ID возвращает 404, а не частично применяет выборку. Неизвестный домен или домен другого аккаунта возвращает 422 validation_error. Отсутствие селектора или несколько селекторов возвращают 422 invalid_selection.

Выборке могут соответствовать не более 1000 ящиков. Более крупная выборка возвращает 422 selection_too_large до любых изменений. Сузьте выборку домена или отправляйте явные списки партиями.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched считает выбранные ящики; updated считает фактические изменения режима; skipped считает общие ящики, ящики в удалённых или в процессе удаления и, при требовании паролей приложений, системные ящики платформы. Для ящиков на паузе или с приостановленным входом режим можно изменить заранее, до восстановления доступа. Ящики с уже нужным режимом учитываются в matched, но не в updated или skipped, поэтому операцию безопасно повторять. Приостановленные аккаунты получают отказ 403.

Чтение состояния ящика и настройка аккаунта по умолчанию

Когда пароли приложений включены, GET /api/v1/mailboxes и GET /api/v1/mailboxes/{mailbox} включают в ресурсы ящиков эти поля:

• client_auth_mode: app_password_only или password_or_app_password.
• app_passwords_count: целочисленное число активных видимых паролей приложений, без внутренних учётных данных платформы.

Оба поля отсутствуют, когда функция выключена. У общих ящиков нет пригодного для прямого входа режима или паролей приложений; запрашивайте учётные данные обычного ящика участника.

GET /api/v1/account требует account:read. Обычные поля верхнего уровня остаются доступны: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits и created_at. Поле new_mailbox_client_auth_mode добавляется только когда пароли приложений включены и платформа применяет настройку аккаунта к новым ящикам. В остальных случаях GET остаётся доступным без этого поля.

Изменять настройку по умолчанию может только владелец аккаунта:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

Обязательное поле принимает те же два режима. Это единственное поле аккаунта, доступное здесь для записи. Ответ содержит поля верхнего уровня id, new_mailbox_client_auth_mode и message. PATCH возвращает 404, если не выполнены оба условия отображения поля, и 403 scope_blocked_by_membership для любого токена участника или коннектора, авторизованного участником.

Токен владельца, ограниченный через domain_ids или mailbox_ids, возвращает 403 token_resource_constrained. Используйте токен владельца без ограничений ресурсов или измените настройку по умолчанию в настройках аккаунта.

Настройка действует для будущих ящиков, созданных в панели, массово, по приглашениям, через API или агентами. Она никогда не меняет существующие ящики. При создании одного ящика через API можно явно передать client_auth_mode в POST /api/v1/mailboxes; если поле пропущено, применяется настройка аккаунта. Существующие ящики сохраняют password_or_app_password после запуска функции. По умолчанию новые ящики используют app_password_only, пока владелец аккаунта не изменит настройку.

Сброс пароля ящика автоматически отзывает пароли приложений

POST /api/v1/mailboxes/{mailbox}/password требует mailboxes:write, то же разрешение участника задавать пароль и Idempotency-Key. Тело требует поле password, новый пароль ящика, соответствующий политике паролей ящиков. Это не endpoint создания пароля приложения.

Каждый успешный административный сброс через этот endpoint, включая изменение пароля агентом MCP, отзывает все пароли приложений с причиной mailbox_password_reset. Отказаться от отзыва нельзя. Пока функция включена, ответ содержит app_passwords_revoked, целочисленное число отозванных паролей, вместе со status, sync_pending и message:

• 200, status: "updated", sync_pending: false, если синхронизация с почтовым сервером завершена.
• 202, status: "update_pending", sync_pending: true, если пароль сохранён и синхронизация ожидается. Пароли приложений уже отозваны к этому моменту.

Сброс также отзывает существующие токены сообщений ящика. Это следствие сброса пароля ящика, а не замены отдельного пароля приложения или изменения режима почтовых программ.

Самостоятельная смена пароля в веб-почте отзывает пароли приложений только при выборе Также отозвать все пароли приложений. Восстановление пароля, приостановка входа, преобразование в общий ящик и перемещение в Недавно удалённые отзывают их все. Восстановление доступа или ящика не восстанавливает отозванные пароли. См. Приостановка входа в ящик через API.

Идемпотентность и однократно выдаваемые пароли

Используйте новый Idempotency-Key для каждой намеренной операции записи и повторяйте его только при повторной отправке того же метода, пути и тела из-за ошибки транспорта. Ключи обязательны, длина не более 255 символов. Успешные ответы кэшируются на стандартные 24 часа; повторное использование ключа для другого запроса возвращает 409 idempotency_mismatch.

Повтор запроса создания или замены пароля приложения возвращает те же безопасные идентификаторы, но без data.password. Он включает _idempotency_replay_warning и заголовок ответа X-Idempotency-Replayed: true. Повтор не позволяет вернуть потерянный пароль. Используйте возвращённый data.id, чтобы заменить активную запись с новым ключом и получить пригодную замену. Сохраните новый ID после замены.

Повтор успешного отзыва с тем же ключом возвращает сохранённый результат. Новый запрос отзыва этой записи возвращает 409 conflict. Изменения режима можно повторять, но каждое намеренное изменение должно иметь новый ключ: старый ключ после переключения режимов может вернуть старый ответ вместо выполнения новой операции.

Лимиты запросов и ошибки

Создание ограничено 60 операциями в час на аккаунт, а замена ограничена 30 операциями в час на аккаунт. Эти лимиты аккаунта общие для API и MCP, а не отдельные для каждого токена. Массовое изменение режима дополнительно ограничено 10 запросами в минуту. К маршрутам также применяется обычный лимит API, по умолчанию 60 запросов в минуту на учётные данные. Превышение лимита возвращает 429 rate_limited; соблюдайте заголовок Retry-After перед повтором.

Ошибки используют стандартный объект error с полями code, message, hint, request_id и retryable. Обрабатывайте машиночитаемый код, а не сравнивайте текст сообщения.

Инструменты MCP и разрешение изменяющих операций

MCP использует те же правила авторизации REST и поля ответа. Прямые инструменты:

Инструменты создания ящиков create_mailbox_generated_password и bulk_create_mailboxes принимают тот же необязательный параметр create_app_password, что и REST.

Инструменты записи также принимают необязательный idempotency_key. REST использует поле тела mode для изменения режима ящика; инструмент MCP называет этот параметр client_auth_mode. У его массовых селекторов те же правила доступа и предел 1000 ящиков, что и в REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

На самостоятельно размещённом сервере каждая операция записи выше требует TREKMAIL_ALLOW_DESTRUCTIVE=true. Создание учётных данных также требует этот флаг, поскольку предоставляет доступ к ящику. Получение списка и чтение аккаунта не требуют флага. Перед вызовом записи попросите пользователя одобрить предполагаемое изменение учётных данных или доступа. Прямые инструменты, возвращающие пароль, инструктируют агента показать пароль один раз, предложить пользователю вставить его в программу и никогда не сохранять его в файлах или памяти и не повторять в последующих сообщениях или вызовах инструментов.

Профили каталогов ChatGPT/OpenAI и Claude

Для создания и замены эти профили предоставляют защищённую ссылку настройки в панели вместо выдачи пароля в чате. Создание ящика там тоже выполняется по ссылке в панель, поэтому первый пароль приложения пользователь получает на карточке Ящик создан в панели, а не через create_app_password. Адрес назначения: /app/mailboxes/{mailbox_id}/security#app-passwords; пользователь входит и завершает действие там.

Профиль OpenAI предоставляет get_mailbox_app_password_setup_link и get_mailbox_app_password_replacement_setup_link. Профиль Claude сохраняет названия create_mailbox_app_password и rotate_mailbox_app_password, но возвращает защищённую ссылку настройки вместо data.password. Не обещайте пароль от этих инструментов каталога и не просите пользователя вставить его в беседу.

Для параметров подключения используйте get_mail_client_setup. Общая настройка коннектора: Подключение AI-агентов. Ящики White Label используют ту же функцию API и брендированные серверы веб-почты и почты; в инструкциях для пользователей называйте эти учётные данные пароль приложения.