Меры безопасности и намерения удаления

TrekMail API разработан так, чтобы предотвращать случайную потерю данных. Разрушительные операции требуют нескольких этапов подтверждения, ограничения частоты защищают от массовых ошибок, а каждое действие записывается в журнал.

Корзина. После подтверждения намерения удалить почтовый ящик он теперь перемещается в корзину на 7 дней (в панели она называется Недавно удалённые), а не уничтожается немедленно. Вы можете получить список удалённых ящиков и восстановить любой из них в течение этого срока:

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

По завершении срока хранения ежедневная задача окончательно удаляет ящики из корзины. При восстановлении заново проверяется лимит ящиков для домена. Агенты MCP используют инструменты restore_mailbox и list_trashed_mailboxes; теперь confirm_delete_intent допускает восстановление и не является необратимым. При удалении домена или аккаунта его ящики удаляются безвозвратно и не помещаются в корзину.

Двухэтапное удаление (намерения удаления)

Удаление почтового ящика и домена относится к самым значительным разрушительным операциям API. Для них применяется двухэтапный процесс:

Этап 1. Создайте намерение удаления

POST /api/v1/mailboxes/{id}:delete-intent

Так создаётся ограниченное по времени намерение с описанием того, что будет удалено. Ответ содержит:

• Факторы риска: предупреждения о правилах пересылки, псевдонимах и активных миграциях, которых коснётся удаление.
• Срок действия: намерение истекает через 10 минут. После этого нужно создать новое.
• URL подтверждения: URL, который следует вызвать на этапе 2.

На этом этапе данные не удаляются.

Этап 2. Подтвердите намерение

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

Когда корзина почтовых ящиков TrekMail включена, подтверждение перемещает ящик в раздел Недавно удалённые и возвращает завершённое намерение со значением status: "executed". Ящик можно восстановить в течение семи дней, если в момент восстановления лимит домена позволяет это сделать.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

По истечении срока восстановления ежедневная очистка TrekMail окончательно удалит ящик. До этого используйте список корзины или конечную точку восстановления. При удалении домена или аккаунта этот механизм восстановления ящиков не применяется.

Заголовок X-Confirm-Delete: true обязателен в запросе подтверждения и служит дополнительной проверкой безопасности.

Факторы риска

При создании намерения удаления API проверяет условия, которые могут означать, что продолжать не следует:

Изучите эти факторы перед подтверждением. API не блокирует подтверждение на основании факторов риска. Они носят только информационный характер.

Ограничения частоты разрушительных операций

Для разрушительных операций предусмотрено два дополнительных уровня ограничений помимо стандартного поминутного ограничения API:

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

При срабатывании оба ограничения возвращают 429 Too Many Requests с заголовком Retry-After.

Управление безопасностью MCP для локальных серверов

Если вы самостоятельно запускаете stdio-сервер MCP, его администратор может потребовать установить TREKMAIL_ALLOW_DESTRUCTIVE=true, прежде чем инструменты удаления станут доступны. Это локальная мера безопасности, а не переключатель функции продукта TrekMail. Размещённый MCP использует разрешения, одобренные во время OAuth.

Инструменты чтения остаются доступны в пределах выданных прав. Проверьте задачу и права агента, прежде чем разрешать удаление.

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

Конечные точки записи, которым нужен Idempotency-Key, указывают это в таблице конечных точек и спецификации OpenAPI. Перед повтором запроса используйте новый ключ для каждой логической операции:

Idempotency-Key: create-mailbox-alice-2024

• Одинаковые ключ и тело повторно возвращают исходный ответ, не выполняя операцию ещё раз.
• Одинаковый ключ с другим телом возвращает 409 Conflict.
• Разные токены используют независимые пространства ключей.

Сервер MCP создаёт устойчивые к повторам ключи идемпотентности для вызовов инструментов, поэтому повторный запрос не запускает уже завершённую операцию заново.

Защитные механизмы отправки

Для отправки почты через сервер MCP действует собственная двухуровневая защита, похожая на защиту разрушительных операций, но состоящая из двух независимых проверок:

Проверка 1. Управление локальным сервером

Для локального сервера MCP установите TREKMAIL_ALLOW_SENDING=true, чтобы разрешить инструмент send_message. Размещённый MCP использует разрешения, одобренные во время OAuth.

Проверка 2. Подтверждение каждого вызова

Даже если переменная среды включена, каждый вызов send_message должен содержать параметр confirm_send=true. Без него инструмент возвращает ошибку с просьбой к агенту подтвердить действие.

Зачем нужны две проверки?

Локальное управление один раз настраивает администратор сервера MCP. Проверка каждого вызова требует, чтобы агент осознанно принимал решение об отправке каждого письма. Ни одной проверки по отдельности недостаточно; письмо покинет сервер, только если пройдены обе.

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

Защитные механизмы миграции

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

Управление миграцией на локальном сервере

Для локального сервера MCP установите TREKMAIL_ALLOW_MIGRATION=true, чтобы разрешить инструменты записи миграции (start_migration, retry_migration, delete_migration). Размещённый MCP использует разрешения, одобренные во время OAuth.

cancel_migration доступен всегда, независимо от этой настройки. Это защитная операция, которая должна оставаться доступной для остановки неконтролируемой миграции.

Инструменты миграции только для чтения (list_migrations, get_migration) работают без дополнительных проверок. Для test_migration_connection требуется TREKMAIL_ALLOW_MIGRATION=true, поскольку инструмент устанавливает исходящие соединения IMAP.

Подтверждение каждого вызова миграции

Каждому инструменту записи миграции нужен параметр подтверждения:

• start_migration требует confirm_start=true
• cancel_migration требует confirm_cancel=true
• retry_migration требует confirm_retry=true

Без параметра подтверждения инструмент возвращает ошибку с просьбой к агенту подтвердить действие.

Общесерверный лимит параллельных операций

API устанавливает глобальный лимит одновременных миграций (по умолчанию: 20). Когда лимит достигнут, новые запросы миграции возвращают 503 со значениями migration_capacity_reached и retryable: true. Это защищает ресурсы сервера, когда множество аккаунтов мигрируют одновременно.

Журнал аудита

Каждое изменяющее данные действие API записывается в журнал аудита, доступный в панели в разделе ИИ-агенты и API → Журнал аудита. В число событий входят:

• Токен создан или отозван: кто и когда создал или отозвал операционный токен.
• Токен сообщений создан или отозван: кто создал или отозвал токен сообщений.
• Намерение создано: для определённого ящика было создано намерение удаления.
• Намерение подтверждено: запрос на удаление был принят.
• Удаление выполнено: ящик перемещён в раздел Недавно удалённые, и начался срок его восстановления.
• Намерение истекло: неподтверждённое намерение истекло через 10 минут.
• Ящик создан: новый ящик подготовлен через API.
• Приглашение создано: отправлено приглашение для настройки ящика.
• Пересылка обновлена: изменены правила пересылки для ящика.
• Повторная проверка DNS запущена: запрошена проверка DNS для домена.
• Миграция запущена: через API начата миграция почты.
• Миграция отменена: выполнявшаяся миграция отменена.
• Миграция запущена повторно: неудачная или отменённая миграция запущена снова.
• Миграция удалена: удалена запись о миграции.
• Сообщение прочитано: сообщения перечислены или прочитаны через API сообщений.
• Сообщение отправлено: письмо отправлено через API сообщений.
• Не удалось отправить сообщение: попытка отправить письмо завершилась ошибкой.
• Флаги сообщения обновлены: изменены флаги сообщения (прочитано/не прочитано, отмечено).
• Сообщение удалено: сообщение удалено из папки почтового ящика.
• Сообщение перемещено: сообщение перемещено между папками.
• Домен создан: через API добавлен домен.
• Домен удалён: через API удалён домен.
• Тикет создан: через API открыт тикет поддержки.
• На тикет дан ответ: в тикете опубликован ответ.
• Тикет закрыт: тикет закрыт.
• SMTP настроен: обновлены настройки SMTP.
• Соединение SMTP удалено: пользовательское соединение SMTP удалено.
• Тест SMTP поставлен в очередь: запущен тест соединения SMTP.
• Токен Cloudflare удалён: сохранённый токен Cloudflare удалён через API.

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

Каждое событие содержит использованный токен, затронутый ресурс, IP-адрес и идентификатор запроса.

Чтобы исследовать определённую активность, отфильтруйте журнал аудита по типу события, токену или диапазону дат.

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

• Намерение истекло до подтверждения: создайте новое намерение удаления. Намерения истекают через 10 минут.
• "Missing confirm header": добавьте заголовок X-Confirm-Delete: true в запрос подтверждения.
• Ошибка 429 при подтверждении удаления: достигнут дневной лимит или действует пауза. Подождите в течение срока, указанного в Retry-After.
• Самостоятельно размещённый агент MCP сообщает, что инструменты удаления отключены: локальный администратор может установить TREKMAIL_ALLOW_DESTRUCTIVE=true в среде этого процесса MCP.
• Самостоятельно размещённый агент MCP сообщает "Sending is disabled": локальный администратор может установить TREKMAIL_ALLOW_SENDING=true в среде этого процесса MCP.
• Агент MCP сообщает "Send not confirmed": агент должен передавать параметр confirm_send=true при каждом вызове send_message.
• Самостоятельно размещённый агент MCP сообщает, что инструменты миграции отключены: локальный администратор может установить TREKMAIL_ALLOW_MIGRATION=true в среде этого процесса MCP.
• Ошибка 503 "migration_capacity_reached": на сервере выполняется слишком много миграций. Подождите несколько минут и повторите попытку.
• Ошибка 409 "active migration running": отмените существующую миграцию или дождитесь её завершения, прежде чем запускать новую.

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

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