Доставляемость и возвраты через API и MCP

На вкладке Статистика каждого домена в панели TrekMail представлены два вида данных о возвратах:

1. Сводка за 30 дней: количество отправленных и доставленных писем, мягких и жёстких возвратов, а также показатели доставки и возвратов.
2. Список по получателям: последние 50 возвратов исходящих писем с кодом состояния и ответом SMTP принимающего сервера, позволяющие понять, почему конкретное письмо не было доставлено.

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

Доступные данные

Для всех трёх требуются права domains:read (или mailboxes:read для списка по почтовому ящику). Доступ только для чтения. Ключ идемпотентности не нужен.

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

REST API: краткие примеры

Сводка домена

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/deliverability?days=30" | jq .

{
  "data": {
    "from": "2026-04-26T00:00:00+00:00",
    "to":   "2026-05-26T23:59:59+00:00",
    "sent": 4180,
    "delivered": 4112,
    "soft_bounce": 22,
    "hard_bounce": 46,
    "forwarding_bounces_excluded": 7,
    "delivery_rate": 0.9837,
    "bounce_rate": 0.0163,
    "status": "good"
  }
}

status соответствует тому же индикатору из трёх состояний, который отображается в панели:

• good: доля возвратов ниже 2%.
• warning: доля возвратов от 2% до 5%.
• poor: доля возвратов не ниже 5%. Проверьте и очистите список рассылки.

forwarding_bounces_excluded показывает, сколько связанных с пересылкой возвратов было исключено из расчёта показателей (как и в панели, где они считаются артефактами маршрутизации, а не проблемами со списком отправителя).

Список возвратов по получателям

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/domains/123/bounces?days=7&type=hard&limit=50" | jq .

{
  "data": [
    {
      "id": 994821,
      "occurred_at": "2026-05-26T18:14:02+00:00",
      "recipient_email": "lost@example.com",
      "event_type": "hard_bounce",
      "smtp_status_code": "550",
      "smtp_response": "5.1.1 The email account that you tried to reach does not exist.",
      "mailbox_id": 7741,
      "domain_id": 123
    }
  ],
  "pagination": { "total": 17, "limit": 50, "offset": 0 }
}

Параметры запроса

Список по почтовому ящику

Для анализа репутации отдельного отправителя ограничьте запрос одним почтовым ящиком:

curl -sS -H "Authorization: Bearer $TM_TOKEN" \
  "https://trekmail.net/api/v1/mailboxes/7741/bounces?days=14&type=soft" | jq .

Структура ответа такая же, как у эндпоинта домена.

Конфиденциальность ответов SMTP

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

Инструменты MCP

Все три инструмента принимают те же параметры, что и эндпоинты REST. Они работают только на чтение и не изменяют почту или настройки учётной записи.

get_domain_deliverability

{
  "name": "get_domain_deliverability",
  "arguments": {
    "domain_id": 123,
    "days": 30
  }
}

list_domain_bounces

{
  "name": "list_domain_bounces",
  "arguments": {
    "domain_id": 123,
    "type": "hard",
    "days": 7,
    "limit": 100
  }
}

list_mailbox_bounces

{
  "name": "list_mailbox_bounces",
  "arguments": {
    "mailbox_id": 7741,
    "recipient": "@example.com",
    "limit": 50
  }
}

Заголовки доставляемости для массовых отправителей

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

Для отдельного сообщения (точная настройка). Передайте их через поле headers запроса POST /api/v1/messages/send:

{
  "to": ["recipient@example.com"],
  "subject": "...",
  "body": {"text": "..."},
  "headers": {
    "List-Unsubscribe": "<mailto:bounces@mydomain.com?subject=unsubscribe>, <https://mydomain.com/u/abc123>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
}

Поле headers принимает небольшой список разрешённых значений: List-Unsubscribe, List-Unsubscribe-Post, Reply-To и любой пользовательский заголовок отслеживания X-*. Внедрение заголовков (CR/LF) и управляемые заголовки (From, Subject, Date, Message-Id, Authentication-Results, DKIM-Signature и другие) отклоняются с кодом 422.

Для всей учётной записи (однократная настройка). Если все исходящие сообщения этой учётной записи автоматизированы, можно включить параметр auto_list_unsubscribe. Тогда платформа добавит заголовок List-Unsubscribe только с адресом mailto к каждому исходящему сообщению, в котором его ещё нет. Заголовок List-Unsubscribe-Post не добавляется, поэтому этот резервный вариант не обеспечивает отписку одним нажатием по RFC 8058. Для соответствующей требованиям провайдеров отписки одним нажатием передавайте оба заголовка в каждом сообщении со своим эндпоинтом HTTPS для отписки, как в примере выше. Заголовки, указанные вызывающей стороной, всегда имеют приоритет. По умолчанию параметр ВЫКЛЮЧЕН, а существующие учётные записи не меняются.

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

Сценарии для ИИ-агентов

Эти эндпоинты позволяют реализовать несколько полезных процессов:

• Еженедельная сводка репутации. Каждый понедельник вызывайте get_domain_deliverability для каждого домена учётной записи и публикуйте сводку в Slack или Teams. Показывайте только домены, у которых status имеет значение warning или poor.
• Очистка списка по возвратам. Вызовите list_domain_bounces?type=hard&days=14, удалите повторяющиеся значения recipient_email, затем исключите эти адреса из списка рассылки. Жёсткие возвраты обычно означают, что адрес получателя больше не существует, а повторная отправка напрасно расходует ресурс доставляемости.
• Анализ по отправителю. Если bounce_rate одного почтового ящика резко вырос, вызовите для него list_mailbox_bounces и сгруппируйте результаты по smtp_status_code. Всплеск кодов 550 может означать, что список адресов устарел; всплеск кодов 421 может означать, что принимающий почтовый сервер ограничил частоту ваших запросов.
• Расследование службы поддержки. Если пользователь сообщает, что письмо не пришло, попросите агента вызвать list_domain_bounces?recipient=<their-address>. Ответ SMTP может подсказать следующее действие, например освободить переполненный ящик получателя, снять блокировку со стороны получателя или исправить отклонение DMARC.

Управление версиями

Эти эндпоинты следуют тому же контракту версий, что и остальная часть API v1: допускаются только совместимые добавления, а несовместимые переименования полей требуют пространства имён v2/.

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

• Показатели спама: телеметрия защиты от входящего спама (get_spam_metrics, get_spam_summary).
• Проверка адресов: очистка списка до отправки, чтобы предотвратить возвраты.
• Обзор API: аутентификация, права доступа, ограничения частоты и идемпотентность.