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

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

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

• REST API v1 с форматом запросов и ответов JSON.
• Аутентификация с bearer-токеном: для аутентифицированных вызовов API не используются cookie или сессии.
• Ключи идемпотентности для операций записи, где они обязательны, чтобы повторные попытки не создавали дубликаты.
• Ограничение частоты запросов для каждого токена с заголовками Retry-After.
• Журнал аудита, доступный в панели управления в разделе ИИ-агенты и API → Журнал аудита.
• Сервер MCP с каталогом, отфильтрованным по учетным данным, транспорту и настройкам безопасности текущего подключения. Поэтому узкое подключение проекта видит только доступные ему инструменты.
• Псевдонимы доменов: связывайте адреса только для приема на дополнительном домене с теми же локальными частями на основном домене, учитывая сохраненное и фактическое состояния доставки и безопасное отключение. См. Псевдонимы доменов через API и MCP.
• Архитектура с двумя токенами: отдельные операционные токены для инфраструктуры и токены сообщений для полного набора почтовых операций, включая чтение, отправку, создание черновиков, планирование, контакты, календари, идентификаторы отправителя, шаблоны и папки.
• Данные об исходящей доставляемости и возвратах: получайте сводку об отправленных, доставленных, окончательно и временно возвращенных письмах из панели управления, а также SMTP-коды и ответы для каждого получателя. См. Доставляемость и возвраты.
• Использование хранилища почтовых ящиков: 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 воспроизведет исходный ответ без создания дубликатов.

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.

Распределение проверяется по фактическому свободному пулу с вычетом существующих выделенных почтовых ящиков и ожидающих выделенных приглашений. Массовые конечные точки дополнительно проверяют сумму объемов во всей партии и отклоняют всю партию с ошибкой 422 storage_pool_exceeded, если она приведет к перерасходу. Пул обновляется после удаления выделенного почтового ящика, активации приглашения (объем переходит новому ящику) и истечения срока ожидающего приглашения.

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

Доступ почтового ящика к 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.

Массовая конечная точка принимает ровно один селектор, 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 дней на остальных тарифах. Более старых данных нет, поскольку события переадресации удаляются.

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

Общий почтовый ящик представляет собой командный входящий ящик, например support@ или sales@, который участники открывают через свои обычные аккаунты почтовых ящиков в Webmail, а при включенном нативном доступе также как делегированную папку IMAP. У него нет общего пароля или отдельного входа. Доступ одинаков для всех: каждый участник может читать, а единый флаг can_send определяет, может ли он отвечать от имени адреса (true) или имеет доступ только для чтения (false). Ролей участников нет.

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

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

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

Удаление участника, изменение 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.
• set_account_default: true является эквивалентом переключателя Сделать настройкой аккаунта по умолчанию в панели управления (новые домены начинают с этого маршрута). apply_to_all: true соответствует кнопке Применить ко всем доменам (однократно переводит каждый домен на этот маршрут).

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

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

Устаревшие конечные точки. Операции 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 на уровне аккаунта добавляет 13 маршрутов в /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": Отправка из этого почтового ящика остановлена, потому что исходящая почта перестала быть похожа на письма владельца, обычно из-за попадания пароля в чужие руки. Чтение, перечисление и все остальные конечные точки продолжают работать; отклоняется только отправка, и повторные попытки не снимут блокировку. Нужно изменить пароль почтового ящика, после чего поддержка снова включает отправку. См. Почему я не могу отправлять письма?.
• Ограничение частоты 429: Перед повторной попыткой подождите время, указанное в заголовке Retry-After.

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

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.

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

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