Обзор REST API TrekMail для разработчиков

Откройте TrekMail в Claude, нажмите Connect, войдите и разрешите доступ. Создавать API-токен не нужно. Проверить разрешения или отключить приложение можно в ИИ-агенты и API, Токены, Подключённые приложения.

Свой бренд White Label: используйте MCP-адрес из кабинета своего бренда и назовите подключение именем бренда. Добавьте его как custom connector: публичная карточка TrekMail выполняет вход на TrekMail и не заменяет подключение вашего бренда.

API TrekMail позволяет управлять доменами, почтовыми ящиками, переадресацией, DNS, переносом почты и операциями веб-почты из HTTP-клиента или с помощью ИИ-агента. Сюда входят чтение и отправка писем, черновики, планирование отправки, папки, контакты, календари, идентификаторы отправителя, шаблоны и заблокированные отправители. Аутентифицированные запросы используют bearer-токен, ответы возвращаются в JSON, а действия API регистрируются в журнале аудита.

Чтение почты одним ключом

На Pro и Agency при создании API-ключа выберите «Чтение почты». Явное разрешение: mailboxes:messages:read; mailboxes:read показывает только адреса ящиков и сведения для настройки. Выберите все ящики, чтобы включить существующие и будущие, либо ограничьте доступ выбранными доменами и ящиками. Существующие ключи автоматически не получают новых прав.

Используйте ключ аккаунта с GET-маршрутами ниже. Для отправки, удаления и других изменений нужны отдельные токены сообщений и разрешения. Hosted MCP принимает OAuth, а не tm_live_ или tm_msg_. Ошибка типа токена подсказывает агенту нужный маршрут или способ авторизации.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Что вы получаете

• REST API v1 с форматом запросов и ответов JSON.
• Аутентификация с bearer-токеном: для аутентифицированных вызовов API не используются cookie или сессии.
• Ключи идемпотентности для операций записи, где они обязательны, чтобы повторные попытки не создавали дубликаты.
• Ограничение частоты запросов для каждого токена с заголовками Retry-After.
• Журнал аудита, доступный в панели управления в разделе ИИ-агенты и API, Журнал аудита.
• Сервер MCP с каталогом, отфильтрованным по учетным данным, транспорту и настройкам безопасности текущего подключения. Поэтому узкое подключение проекта видит только доступные ему инструменты.
• Псевдонимы доменов: связывайте адреса только для приема на дополнительном домене с теми же локальными частями на основном домене, учитывая сохраненное и фактическое состояния доставки и безопасное отключение. См. Псевдонимы доменов через API и MCP.
• Архитектура с двумя токенами: отдельные операционные токены для инфраструктуры и токены сообщений для полного набора почтовых операций, включая чтение, отправку, создание черновиков, планирование, контакты, календари, идентификаторы отправителя, шаблоны и папки.
• Данные об исходящей доставляемости и возвратах: получайте сводку об отправленных, доставленных, окончательно и временно возвращенных письмах из панели управления, а также SMTP-коды и ответы для каждого получателя. См. Доставляемость и возвраты.
• Пароли приложений для почтовых программ: управляйте отдельными паролями для IMAP, SMTP, календарей и контактов и выбирайте, какие пароли принимают почтовые программы. Они не заменяют Bearer-токены API или токены Message API. См. Пароли приложений через API и MCP.
• Использование хранилища почтовых ящиков: list_mailboxes и get_mailbox возвращают used_mb, quota_mb, allocation_mb и is_pooled, поэтому агент может обнаружить ящики, приближающиеся к лимиту, без доступа к панели управления.
• Администрирование White Label: проверяйте настройку, управляйте брендингом для каждого домена, приглашайте клиентов, контролируйте роли и домены, приостанавливайте или восстанавливайте доступ и просматривайте активность через API или MCP. См. руководство по брендингу и руководство по управлению командой.

API Drive и автоматизация файлов

Drive входит в общедоступную поверхность API. Она охватывает пространство Drive аккаунта и пространства Drive почтовых ящиков, использование хранилища, просмотр папок, загрузку, управление файлами и папками, корзину, массовые действия, публичные ссылки общего доступа, управление паролями устройств синхронизации и доступный только для чтения статус дополнения Drive Storage.

Drive использует одиннадцать областей действия операционного токена: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read и drive:devices:write. Операции оплаты для дополнения Drive, включая покупку, изменение размера и отмену, остаются доступными только в панели управления и не предоставляются как операции записи API или MCP.

Начните с обзора API Drive или быстрого старта API Drive.

Архитектура с двумя токенами

API использует два независимых типа токенов. В зависимости от задачи можно использовать один или оба:

У операционных токенов и токенов сообщений разные области действия и отдельные лимиты запросов. Один агент может одновременно использовать оба токена, если настроить их в окружении сервера MCP.

Токены сообщений доступны на тарифах Pro и Agency.

Перед началом работы

• Все тарифы имеют доступ к API:
  • Nano: Email Verifier. Подключите дополнение Drive Storage для полного доступа к API и MCP Drive.
  • Starter: полный Drive, полный Email Verifier и доступ только для чтения во всех остальных областях инфраструктуры. Для соответствующих операций записи используйте панель управления.
  • Pro / Agency: полный доступ к базовому API, включая токены сообщений. Области действия White Label добавляются, пока действует пробный период или платное дополнение.
• Подключаете ИИ-агента? Добавьте https://trekmail.net/mcp как удаленный сервер MCP в любом совместимом клиенте. Если клиент поддерживает авторизацию через браузер, токен вручную не нужен. В статье Подключение ИИ-агентов (MCP) описаны удаленный вариант, CLI/приложение для компьютера, мост и самостоятельный хостинг.
• Создаете собственную интеграцию? Создайте токен tm_live_ в разделе ИИ-агенты и API, Токены, Создать токен и передавайте его как Authorization: Bearer …. См. Создание токенов API и управление ими.
• Впервые работаете с API? Нажмите Начать обзор в верхней части страницы ИИ-агенты и API, чтобы пройти краткое знакомство со способами подключения, управлением токенами, подключенными приложениями и журналом аудита.

Как работает аутентификация

Каждый запрос должен содержать ваш токен в заголовке Authorization:

Authorization: Bearer tm_live_abc123...

Операционные токены начинаются с tm_live_, а токены сообщений с tm_msg_. Оба показываются один раз при создании и больше не могут быть отображены.

Если токен отсутствует, отозван или просрочен, API возвращает 401 с кодом ошибки unauthenticated.

Базовый URL и управление версиями

Все конечные точки находятся по адресу:

https://trekmail.net/api/v1

Базовый URL указан в разделе Краткая справка панели ИИ-агенты и API. Версия входит в путь URL. Если когда-либо появится v2, v1 продолжит работать.

Формат ответа

Успешные ответы возвращают JSON с ключом data для одного ресурса или список с постраничной навигацией:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Ответы с ошибками имеют единообразную структуру:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

Идентификаторы запросов

Каждый ответ содержит заголовок X-Request-Id. Также можно передать собственный идентификатор в заголовке запроса X-Request-Id. Он будет возвращен в ответе и записан в журнал аудита.

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

Для каждого токена действует поминутное ограничение частоты запросов. При достижении лимита API возвращает 429 с заголовком Retry-After, который указывает, когда можно повторить запрос.

Для разрушительных операций (намерений удаления) установлен дополнительный дневной лимит на токен и пауза между последовательными удалениями.

Для операций записи при переносе (запуск, отмена, повторная попытка) действует отдельный лимит в 10 запросов в минуту на токен, а также общий лимит одновременных операций на сервере, который возвращает 503, если во всей системе выполняется слишком много переносов.

Токены сообщений используют отдельные лимиты. По умолчанию разрешено 30 запросов чтения в минуту на токен, 60 запросов отправки в минуту на токен, 5,000 успешных чтений в день на токен и 100 отправок через API в день для одного почтового ящика. Второй счетчик безопасности отправки по умолчанию допускает 500 операций на токен в день; обычно раньше срабатывает меньший лимит почтового ящика. Эти меры безопасности API не заменяют ограничения управляемого SMTP вашего тарифа или собственные ограничения внешнего поставщика.

Идемпотентность

Конечные точки, изменяющие состояние и отмеченные как идемпотентные, требуют заголовок Idempotency-Key. Сюда относятся операции создания, обновления, отправки и удаления, где автоматическая повторная попытка иначе могла бы продублировать работу. Подобные чтению действия POST, например определение поставщика или проверка подключения, не требуют этого заголовка; уточняйте в таблице конечных точек или спецификации OpenAPI. Если отправить тот же ключ с тем же телом, API воспроизведет исходный ответ без создания дубликатов. Исключение составляют отправки писем, доставка которых не удалась (например, из-за лимита отправки): для них API больше не воспроизводит прежний ответ 202, поэтому то же письмо можно позже отправить снова с тем же содержимым. Если вы передаете собственный X-Request-Id, для этой попытки укажите новый: отправку из того же ящика с тем же X-Request-Id API тоже считает повтором, поэтому со старым вы получите лишь исходную неудавшуюся доставку, и ничего отправлено не будет. Повторный запрос для отправки, которая еще ожидает или уже доставлена, по-прежнему получает исходный ответ.

Idempotency-Key: create-mailbox-alice-2024

Если отправить тот же ключ с другим телом, API вернет 409 Conflict.

Распределение хранилища почтового ящика

Каждая конечная точка, создающая почтовый ящик или приглашение, POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk, принимает необязательное целое число storage_allocation_mb.

Распределение проверяется по фактическому свободному пулу с вычетом существующих выделенных почтовых ящиков и ожидающих выделенных приглашений. Массовые конечные точки проверяют каждый элемент с выделенным объёмом по остатку на момент его создания: подходящие создаются, а те, что уже не помещаются, отклоняются по отдельности с причиной storage_pool_exceeded (207 частичный успех или 422, если не прошёл ни один). В домене с лимитом хранилища клиента White Label фиксированный размер должен еще и помещаться в остаток этого лимита: одиночное создание или приглашение возвращает 422 client_storage_limit_exceeded с limit_mb, allocated_mb, available_mb и requested_mb в details (ключ, ограниченный частью доменов, получает только available_mb и requested_mb, если лимит действует и на недоступный ему домен), а элемент массового запроса отклоняется с причиной client_storage_limit_exceeded. Пул обновляется после удаления выделенного почтового ящика, активации приглашения (объем переходит новому ящику) и истечения срока ожидающего приглашения.

Для приглашений объем записывается в коде доступа и при активации копируется в новый почтовый ящик. Если к моменту активации в пуле уже недостаточно места для запрошенного объема (например, другой администратор тем временем увеличил выделенный объем), новый ящик без ошибки переводится на общий пул вместо отказа, а получатель видит уведомление на странице успешной активации.

Чтобы изменить существующий ящик, отправьте PATCH /api/v1/mailboxes/{id}/storage, указав в storage_allocation_mb фиксированный размер в MB или null для общего хранилища. Нужны mailboxes:write и Idempotency-Key. Запрос работает для активных и приостановленных ящиков и выполняет те же проверки, что Изменить хранилище в панели: storage_pool_exceeded, если свободного места в аккаунте не хватает, в домене с лимитом хранилища клиента client_storage_limit_exceeded, или client_storage_below_usage, если новый размер меньше того, что ящик уже хранит. Общее хранилище никогда не отклоняется из-за размера. Ящик в разделе Недавно удалённые или в процессе удаления возвращает 422 mailbox_unavailable. Инструмент MCP называется set_mailbox_storage.

Лимиты хранилища клиентов White Label находятся в /api/v1/white-label/client-limits; смотрите Управление командами White Label с помощью API и MCP. Ключ, ограниченный частью доменов, видит в GET /api/v1/account только свою часть аккаунта: usage считает только его домены и ящики, limits.max_storage_mb равен лимиту клиента, если у всех его доменов один общий лимит, не действующий на другие домены, а client_limit содержит этот лимит (id, storage_limit_mb, allocated_mb, used_bytes) или null. Остальные вызывающие стороны получают ответ без изменений.

Новые обычные ящики, в том числе созданные массово, по приглашениям и AI-агентами, используют настройку Настройки аккаунта > Новые ящики > Почтовым программам нужны пароли приложений, включённую по умолчанию. Её изменение не переключает существующие ящики. В POST /api/v1/mailboxes можно указать client_auth_mode: app_password_only или password_or_app_password; если поле не задано, применяется настройка аккаунта. Ресурсы списка и отдельного ящика возвращают client_auth_mode и app_passwords_count (число активных паролей приложений). У общих ящиков нет собственных паролей приложений или режима входа.

Шесть инструментов MCP для управления паролями приложений: list_mailbox_app_passwords, create_mailbox_app_password, rotate_mailbox_app_password, revoke_mailbox_app_password, set_mailbox_client_auth_mode, update_account. update_account: Задать new_mailbox_client_auth_mode для будущих ящиков; существующие ящики сохраняют свой режим. Требуются mailboxes:write, токен или коннектор владельца без ограничений ресурсов и TREKMAIL_ALLOW_DESTRUCTIVE=true для собственного stdio-сервера.

Доступ почтового ящика к Drive

У каждого почтового ящика есть уровень drive_access, определяющий доступ пользователя к Drive в веб-почте. Он возвращается в ресурсе почтового ящика и задается через PATCH /api/v1/mailboxes/{id} или для нескольких ящиков сразу через POST /api/v1/mailboxes:drive-access.

Хранилище объединено в общий пул аккаунта, поэтому этот параметр определяет, какую часть пула один пользователь может заполнить файлами.

Приостановка входа в почтовый ящик

Вход в почтовый ящик можно приостановить, сохранив прием почты: веб-почта, IMAP, SMTP и пароли устройств перестают работать, а открытые сессии завершаются, но доставка не меняется, поэтому возвратов нет и все письма будут ждать восстановления входа. Установите это через POST /api/v1/mailboxes/{id}:suspend-login (а отмените через :resume-login) или для нескольких ящиков через POST /api/v1/mailboxes:login-access.

Ресурс почтового ящика сообщает об этом полями login_suspended, login_suspended_at и login_suspended_reason. Проверяйте login_suspended, чтобы узнать, может ли пользователь войти, а status, чтобы узнать, работает ли сам ящик: приостановленный ящик сохраняет состояние active, поскольку продолжает принимать почту. :pause действует иначе: устанавливает status в disabled и также останавливает доставку.

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

См. Приостановка входа в почтовый ящик через API.

Массовая конечная точка принимает ровно один селектор, mailbox_ids, domain_id или all, и возвращает результат своих действий:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

Используйте domain_id как селектор, когда один домен соответствует одному клиенту. Почтовые ящики, уже имеющие запрошенный уровень, учитываются как matched, но не как updated, поэтому вызов можно безопасно повторять.

Общие почтовые ящики отклоняются одиночной конечной точкой с ошибкой 422 drive_access_not_applicable, а массовая конечная точка пропускает и подсчитывает их: у них нет собственного пользователя веб-почты, участники открывают их со своим уровнем доступа, поэтому значение в строке общего ящика ничего бы не изменило.

Ограничение действует и в API, и в интерфейсе. Пространство Drive ограниченного почтового ящика отсутствует в GET /api/v1/drive/spaces, его файлы возвращают 404 при запросе по идентификатору, а создать для него устройство синхронизации нельзя.

Адреса переадресации

GET /api/v1/domains/{id}/forwarding-addresses возвращает не только список, поскольку два свойства адреса переадресации не видны в самом адресе:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max задается для домена и зависит от тарифа: 100 на Pro, 300 на Agency и 25 сохраненных, но неактивных адресов на Nano или Starter.
• delivery.active показывает, пересылают ли эти правила почту прямо сейчас. Значение равно false на тарифе ниже requires_plan и остается false, пока установлено paused_until (аккаунт превысил почасовой лимит отправки; см. Лимиты отправки по тарифам). Правило может иметь is_active: true и все равно не доставлять почту, поэтому перед сообщением о работе переадресации проверяйте delivery, а не только is_active.

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

Отказы возвращаются с кодом 422, а error.code получает значение validation_error или limit_exceeded. Причиной может быть уже занятый в домене адрес, получатель в том же домене (что создало бы цикл), домен получателя без рабочего MX или исчерпанный лимит домена.

Запросы POST и DELETE к этим конечным точкам требуют Idempotency-Key, а PATCH не требует.

История доставки

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log возвращает фактический результат обработки недавней почты, начиная с самых новых событий:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

Значение outcome может быть delivered, deferred (временная ошибка, попытки продолжаются), failed (сервер получателя отклонил письмо) или blocked. Последнее означает, что наш спам-фильтр остановил сообщение до переадресации, поэтому оно вообще не дошло до получателя. Если считать blocked возвратом, кто-то будет искать на принимающем сервере проблему, возникшую на нашей стороне.

limit (от 1 до 200, по умолчанию 100) является единственным параметром. Окно соответствует сроку хранения тарифа: 30 дней на Agency и 7 дней на остальных тарифах. Более старых данных нет, поскольку события переадресации удаляются.

Общие почтовые ящики команды

У общего ящика свои входящие команды. can_read означает Чтение, can_send означает Отправка от имени. Для открытия общих папок нужно Чтение. Для отправки из общего ящика через Message API нужны оба права. Нет общего пароля, отдельного входа или ролей участников.

GET /api/v1/mailboxes и GET /api/v1/mailboxes/{id} теперь возвращают mailbox_type ("user" или "shared") и логическое поле is_shared; общие почтовые ящики также содержат shared_member_count. Используйте эти поля, чтобы отличить командный входящий ящик от обычного перед вызовом конечных точек участников.

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

Изменение прав может вернуть 422 no_access_left, если оба права окажутся выключены, 422 send_only_disabled, если запрошенное изменение права Чтение недоступно, или 422 last_reader, если доступ потеряет последний активный читатель. Чтобы убрать весь доступ, используйте Удалить. Перед удалением последнего читателя дайте право Чтение другому активному участнику. Каждая из этих ошибок также возвращает shared_mailbox_id, member_id для существующего участника и hint с запросом, который исправляет проблему.

Конечные точки участников используют существующие области mailboxes:read / mailboxes:write. Отдельной области для общих почтовых ящиков нет.

Чтобы узнать о нативном доступе из почтового приложения, вызовите GET /api/v1/mailboxes/{member_mailbox_id}/client-setup для обычного почтового ящика участника. Объект shared_mailboxes сообщает устойчивую готовность нативного доступа, фактическую готовность отправки от имени общего адреса и её причину, точные пути Inbox/Sent/Archive/Junk и разрешенные операции. can_send означает назначенное разрешение Отправка от имени, но не доказывает, что SMTP сейчас готов. Конечная точка никогда не возвращает пароль. Вызов с идентификатором общего почтового ящика возвращает 422 direct_login_unavailable, потому что общий адрес не может проходить аутентификацию напрямую.

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

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

Доступные конечные точки

Для Drive существует отдельный справочник, который здесь не повторяется, см. Обзор API Drive. Конечные точки SMTP на уровне аккаунта, сохраненные для обратной совместимости, описаны в разделе Маршрутизация SMTP для домена, а не перечислены как актуальные.

Конечные точки Cloudflare повторяют процесс из панели управления: проверка токена, перечисление зон, подключение доменов, предварительный просмотр изменений DNS и их применение. И /cloudflare/preview, и /cloudflare/apply принимают два необязательных параметра для каждого домена:

• included_records: список разрешенных к изменению записей с ключами по идентификатору домена: { "123": ["mx_primary", "spf_record"] }. Пропущенные записи не затрагиваются, поэтому можно применить только MX и SPF, а к DKIM вернуться позже. Не указывайте поле, чтобы применить все записи.
• confirmed_conflicts: когда предварительный просмотр отмечает существующую запись с другим значением, укажите здесь ее идентификатор (в той же форме { domain_id: [record_ids] }), чтобы разрешить замену.

Идентификаторы записей (mx_primary, spf_record, dkim_primary, dmarc_main, …) поступают непосредственно из ответа предварительного просмотра, поэтому обычный агент сначала вызывает предварительный просмотр и передает выбранные идентификаторы обратно в операцию применения:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

Маршрутизация SMTP для домена и настройка аккаунта по умолчанию

SMTP настраивается для каждого домена. Каждый домен выбирает один из трех маршрутов: управляемую отправку платформы, сохраненный профиль SMTP (ваш собственный поставщик, многократно используемый для разных доменов) или вариант «не настроено». Единая настройка аккаунта по умолчанию определяет начальный маршрут новых доменов.

Конечные точки домена (smtp:read / smtp:write):

Несколько замечаний о теле маршрута:

• smtp_mode=platform выбирает управляемую отправку; smtp_mode=profile требует smtp_connection_id; not_configured очищает маршрут.
• smtp_mode=inherit заставляет домен в реальном времени следовать настройке аккаунта по умолчанию: при каждом ее изменении этот домен меняется вместе с ней. Веб-интерфейс всегда записывает конкретные маршруты, но серверная часть по-прежнему поддерживает inherit, поэтому GET возвращает effective_smtp_mode, показывающий текущее фактическое значение inherit.
• Этот маршрут меняет только свой домен. Чтобы сделать маршрут стандартом учетной записи (Сделать настройкой аккаунта по умолчанию в панели управления), используйте PUT /api/v1/smtp/default ниже; добавьте apply_to_all: true, чтобы заодно переключить на него все домены (Применить ко всем доменам).

Конечные точки настройки аккаунта по умолчанию (smtp:read / smtp:write):

Удаление профиля, который был настройкой аккаунта по умолчанию, сбрасывает ее на базовый вариант тарифа.

Ключ, ограниченный частью доменов или ящиков, получает 403 token_resource_constrained от PUT /api/v1/smtp/default, от устаревших PUT и DELETE /api/v1/smtp и при удалении сохраненного профиля: каждое из этих действий меняет маршрут доменов, к которым у ключа может не быть доступа. Ключ, ограниченный частью доменов, получает тот же ответ, когда изменяет профиль, которым пользуется и домен вне его списка.

Устаревшие конечные точки. Операции GET/PUT /api/v1/smtp на уровне аккаунта (а также DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}) сохраняются для обратной совместимости, но больше не управляют маршрутизацией для доменов: используйте конечные точки домена и /smtp/default, описанные выше. Устаревшие инструменты MCP get_smtp_config / update_smtp_config не рекомендуются по той же причине.

Брендинг White Label, клиенты и доступ команды

Брендинг настраивается для каждого домена с областями branding:read / branding:write. Домен использует собственный бренд (mode=custom), наследует настройку аккаунта по умолчанию (mode=inherit) или отключает брендинг. Требуется активный пробный период White Label или платное дополнение. После отмены владелец сохраняет доступ только для чтения и восстановления в течение показанного льготного периода. Прочитайте dns_records домена и опубликуйте именно возвращенные записи. Не выводите имена хостов или целевые значения CNAME из примера.

PATCH выполняет частичное слияние, поэтому пропущенные поля сохраняются. Если брендинг сейчас отключен, передайте mode, чтобы включить его снова. Пользовательский sender_email должен принадлежать домену с подтвержденным ключом DKIM. mail_zone_enabled обслуживает почтовые приложения и синхронизацию DAV на собственном домене бренда. Параметр относится к бренду, а не к отдельному домену, поэтому требует mode=custom или scope=account_default; домен inherit возвращает 422 inherited_brand. Для отслеживания подготовки читайте mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url и mail_zone.dav_ready и используйте только готовый адрес DAV. Полный процесс для агента описан в руководстве по API и MCP для брендинга White Label.

Поверхность White Label на уровне аккаунта добавляет 18 маршрутов в /api/v1/white-label: состояние и прогресс настройки, актуальный каталог доступа, список участников и действия жизненного цикла, лимиты хранилища клиентов, активность аккаунта и историю действий и входов каждого участника. Она использует members:read, members:write и activity:read. Доступ всегда представляет собой пересечение прав аккаунта, текущего членства пользователя, разрешений учетных данных и ограничений домена. Таблица маршрутов и переходы состояний приведены в статье Управление командами White Label с помощью API и MCP.

Спецификация OpenAPI доступна по адресу /api/openapi.json для импорта в Postman, Insomnia или генераторы кода.

Быстрые решения

• 401 "unauthenticated": Проверьте наличие заголовка Authorization: Bearer <token> и убедитесь, что токен не отозван и не просрочен.
• 403 "plan_api_disabled": Запрошенная область недоступна на вашем тарифе. Nano включает Email Verifier (и Drive, если приобретено дополнение Drive Storage). Для остальной части API перейдите на Starter или более высокий тариф.
• 403 "token_scope_blocked_by_plan": У токена есть области, недоступные на текущем тарифе. Отзовите токен и создайте новый с разрешенными областями.
• 403 "scope_blocked_by_entitlement": Сохраненное разрешение White Label недоступно, поскольку дополнение неактивно или в льготный период выполняется операция записи. Повторно активируйте White Label, затем заново выдайте или авторизуйте учетные данные.
• 403 "scope_blocked_by_membership": Текущая роль участника уже, чем запрошенное действие. Попросите владельца изменить ее; одной повторной авторизацией расширить членство нельзя.
• 422 "missing_idempotency_key": Добавьте заголовок Idempotency-Key к операции записи, указанной в справочнике конечных точек.
• 403 "mailbox_sending_paused": Отправка из этого почтового ящика остановлена, потому что исходящая почта перестала быть похожа на письма владельца, обычно из-за попадания пароля в чужие руки. Чтение, перечисление и все остальные конечные точки продолжают работать; отклоняется только отправка, и повторные попытки не снимут блокировку. Нужно изменить пароль почтового ящика, после чего поддержка снова включает отправку. См. Почему я не могу отправлять письма?.
• 403 "account_sending_on_hold": Отправка со всего аккаунта удержана на время проверки TrekMail. Получение писем и все остальные конечные точки продолжают работать; повторные попытки ничего не изменят. Чтобы проверку завершили, обратитесь в поддержку.
• 403 "mailbox_send_disabled": Отправка выключена только для этого почтового ящика. Чтение и все остальные конечные точки продолжают работать; повторные попытки ничего не изменят. Обычно ящик выходит за пределы тарифа: его домен сверх числа доменов, которое включает тариф, или сам ящик сверх числа ящиков на домен по тарифу (самые старые домены и ящики продолжают отправлять). Так бывает после перехода на меньший тариф. Ещё это может быть ящик, созданный до того, как его домен закончил настройку. Переход на тариф выше включает отправку сразу; после удаления лишних доменов или ящиков, а также когда домен закончит настройку, отправка вернётся в течение суток. Если ничего из этого не подходит, обратитесь в поддержку.
• 403 "account_email_unverified": Отправка заблокирована, пока владелец аккаунта не подтвердит свой адрес для входа. У аккаунтов, зарегистрированных 19 февраля 2026 года и позже, на это есть 7 дней, и те же 7 дней начинаются заново, когда подтверждённый адрес для входа заменяют новым. Чтение и все остальные конечные точки продолжают работать; повторные попытки ничего не изменят. Откройте ссылку из письма подтверждения или нажмите Отправить письмо подтверждения повторно в баннере панели управления; отправка заработает сразу после подтверждения адреса. См. Почему я не могу отправлять письма?.
• Ограничение частоты 429: Перед повторной попыткой подождите время, указанное в заголовке Retry-After. Когда исчерпан суточный лимит API на почтовый ящик, тоже возвращается код rate_limited, но retryable равно false, dimension равно api_mailbox_daily, а в resets_at указано время: повторять запрос раньше бесполезно, поэтому дождитесь этого времени.
• 429 "sending_limit_exceeded": Исчерпан один из лимитов отправки. dimension показывает, какой именно, а resets_at показывает, когда он обновится. Повторный запрос до этого времени не пройдет, поэтому retryable равно false. GET /api/v1/messages/sending-limits показывает в remaining_today, скольким еще получателям ящик может отправить письма сегодня. Когда самым низким оказывается общий суточный лимит аккаунта, limit_today равен null, и remaining_today тоже, пока этот лимит не исчерпан (после этого там 0); сам лимит операционный токен получает через GET /api/v1/sending-limits. Если dimension равно recipients_per_message, разделите письмо на несколько писем поменьше. В первые 24 часа после первой оплаты аккаунта среди причин есть new_payer, а GET /api/v1/sending-limits возвращает в full_limits_at момент, когда начнут действовать полные лимиты тарифа. См. Лимиты отправки по тарифам.

Отправка писем: тело, заголовки и доставляемость

POST /api/v1/messages/send принимает запрос вида {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• body.text и body.html необязательны, но нужно указать хотя бы одно из них. Если передан только body.text, мы автоматически создаем альтернативу HTML с абзацами <p> (пустые строки разделяют абзацы, одиночные переводы строк становятся <br>), чтобы письмо отображалось как обычное во всех современных клиентах. Если нужен моноширинный текст, передайте буквальный <pre>...</pre> в body.html.
• headers является необязательным объектом пользовательских заголовков исходящей почты. Список разрешенных значений включает List-Unsubscribe, List-Unsubscribe-Post, Reply-To и любой пользовательский заголовок отслеживания X-*. Остальные имена (From, Subject, Message-Id, Authentication-Results и другие) управляются платформой и отклоняются с кодом 422. Значения с CR/LF также отклоняются для защиты от внедрения заголовков. Длина каждого значения ограничена 998 символами согласно RFC 2822.
• Для массовой отправки и автоматизации см. раздел Заголовки доставляемости для массовых отправителей, где описана настройка List-Unsubscribe и общий для аккаунта переключатель auto_list_unsubscribe.

Ответ 202 означает, что письмо принято, но еще не отправлено. Лимиты отправки проверяются повторно, когда письмо выходит из очереди, поэтому узнавайте результат через GET /api/v1/messages/deliveries/{request_id}, указав request_id из ответа 202. Проверить результат можно любым токеном сообщений того же ящика, а не только тем, которым письмо было отправлено; для неизвестного request_id возвращается 404. Если письмо остановил лимит, status будет failed, а в failure будут указаны лимит (dimension) и время его обновления (resets_at). Неудавшуюся отправку можно позже повторить с тем же содержимым. Если вы передаете собственный X-Request-Id, укажите для повтора новый: старый вернет лишь исходную доставку. Запланированное письмо, которое в момент отправки достигло лимита, задерживается со статусом limit_reached и хранится 7 дней: список таких писем можно получить через GET /api/v1/messages/scheduled?status=limit_reached, отправить письмо позже можно, задав новое scheduled_for через PATCH /api/v1/messages/scheduled/{id}, а удалить его можно через DELETE.

Связанные статьи

• Создание токенов API и управление ими
• Подключение ИИ-агентов (MCP)
• Области API и разрешения тарифов
• Защитные ограничения и намерения удаления