Разработка

Чек-лист транзакционного email API для продакшена

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

Готовность транзакционной почты к продакшену

Запуская email API для транзакционных писем, нужно проверить три разных уровня: приём провайдером (API принимает ваш запрос), доставку (принимающий сервер принимает письмо) и попадание во «Входящие» (письмо доходит до пользователя). Готовой к продакшену системе нужны подтверждённые DNS-записи, надёжная стратегия идемпотентности против повторных отправок, полноценная обработка вебхуков для событий доставки и модель затрат, которая масштабируется вместе с объёмом. Если что-то из этого не работает, вы рискуете потерять данные или навредить репутации.

1. Подтверждение домена и DNS

Отправка писем с неподтверждённого домена — верный способ сработать на спам-фильтры или получить прямой отказ от принимающего MTA (Mail Transfer Agent). Нужно доказать, что домен отправки принадлежит вам.

Обязательная тройка: SPF, DKIM и DMARC

  • SPF (Sender Policy Framework): DNS-запись со списком IP-адресов или сервисов, которым разрешено отправлять почту от имени вашего домена. Без неё получатели не могут проверить, не подделывает ли отправитель ваш домен. Подробнее — в нашем термине глоссария SPF.
  • DKIM (DomainKeys Identified Mail): добавляет в заголовок письма криптографическую подпись. Так гарантируется, что содержимое не изменили в пути.
  • DMARC (Domain-based Message Authentication, Reporting, and Conformance): сообщает получателю, что делать, если проверка SPF или DKIM не пройдена (none, quarantine или reject).

Прежде чем переключаться на продакшен, проверьте, что эти записи корректно распространились, с помощью инструмента вроде SendHQ Email DNS Checker. Подробный разбор — в нашем руководстве по DKIM, SPF и DMARC.

Чек-лист проверки

  • SPF-запись включает все источники отправки.
  • Открытые ключи DKIM опубликованы в DNS и соответствуют закрытым ключам, используемым API.
  • Политика DMARC задана (начните с p=none для мониторинга, затем перейдите к p=reject).
  • Обратный DNS (rDNS) настроен для ваших IP-адресов отправки (если вы используете выделенные IP-адреса).

2. Интеграция с API и надёжность

Транзакционные письма — события критического пути (сброс пароля, счета, 2FA). Если относиться к email API как к HTTP-вызову по принципу «отправил и забыл», инциденты в продакшене гарантированы.

Идемпотентность и защита от дублей

Сетевые тайм-ауты неизбежны. Если приложение отправило запрос в email API, но соединение оборвалось до получения ответа, логика повторов может отправить одно и то же письмо дважды. Это особенно опасно для ИИ-агентов и автоматизированных процессов.

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

{
  "idempotency_key": "req_88234abc123",
  "to": "user@example.com",
  "template_id": "welcome_email",
  "variables": {
    "name": "Alice"
  }
}

ИИ-агенты и взаимодействие A2A

При интеграции с ИИ-агентами (через MCP-серверы или аналогичные механизмы) относитесь к отправке письма как к внешнему побочному эффекту. Агенты могут зацикливаться или галлюцинировать триггеры. Никогда не позволяйте агенту запускать отправку в продакшене без одной из следующих мер:

  1. Человек в контуре (HITL): этап ручного согласования в вашем интерфейсе.
  2. Строгое ограничение частоты запросов: квота на пользователя или агента, чтобы исключить случайный спам.
  3. Ограничения через шаблоны: агенты обязаны использовать хранимые шаблоны, в которых можно менять только переменные, — так агент не сможет написать произвольный (и потенциально вредный) текст.

3. Обработка ошибок и наблюдаемость

Система должна различать временные ошибки (можно повторить) и постоянные ошибки (повторять нельзя).

Классификация ошибок

Error TypeExampleAction
Transient429 Too Many Requests, 503 Service UnavailableExponential backoff retry
Permanent400 Bad Request (Invalid Email), 401 UnauthorizedLog error, alert developer, do not retry
Delivery550 User Unknown, 554 Message RejectedUpdate suppression list, notify user

Интеграция вебхуков

Ответ API сообщает лишь, принял ли провайдер письмо. Чтобы узнать, было ли оно доставлено, нужны вебхуки. Отслеживайте в базе данных следующие события:

  • Sent: провайдер передал письмо MTA.
  • Delivered: принимающий сервер принял письмо.
  • Bounced: принимающий сервер отклонил письмо (жёсткий отказ — постоянный, мягкий отказ — временный).
  • Complained: пользователь пометил письмо как спам.

Пример полезной нагрузки вебхука для события доставки:

{
  "event": "delivered",
  "message_id": "msg_12345",
  "timestamp": "2026-09-15T10:00:00Z",
  "recipient": "user@example.com"
}

4. Анализ затрат и компромиссы при выборе провайдера

Выбор провайдера — это компромисс между удобством для разработчиков (DX), стоимостью и затратами на инфраструктуру. По данным о ценах на сентябрь 2026 года, разброс стоимости значителен.

Сравнение цен провайдеров

  • Amazon SES: самый дешёвый вариант для больших объёмов. При оплате по факту — 0.10 USD за 1 000 писем (цены Amazon SES). Новые многоуровневые тарифы (21 июля 2026 г.): Essentials (0.16 USD/1 тыс.), Pro (0.22 USD/1 тыс. + 105 USD/мес. за регион) и Enterprise (0.23 USD/1 тыс. + 500 USD/мес.).
  • Resend: ставка на DX. Бесплатный тариф — 3 000 писем в месяц (не более 100 в день). Pro — 20 USD/мес. за 50 000 писем, превышение — 0.90 USD за 1 000 (цены Resend).
  • SendGrid: Essentials — от 19.95 USD/мес. Бесплатный тариф теперь — 60-дневный пробный период (цены SendGrid).
  • Mailgun: 15 USD/мес. за 10 000 писем, превышение — от 1.80 до 1.10 USD за 1 000 (цены Mailgun).
  • Postmark: 15 USD/мес. за 10 000 писем, превышение — от 1.80 до 1.20 USD за 1 000 (цены Postmark).

«Разрыв на масштабе»

Возьмём стоимость отправки 50 000 транзакционных писем. В Amazon SES с оплатой по факту это около 5 USD. На многоуровневых тарифах Postmark тот же объём стоит примерно 66 USD. Для большинства стартапов удобство специализированного API стоит этой наценки, но для ИИ-агентов с большими объёмами модель SES часто становится необходимостью.

5. Итоговый чек-лист перед продакшеном

Перед развёртыванием в продакшене пройдите по этому итоговому списку проверок:

Инфраструктура

  • DNS-записи (SPF, DKIM, DMARC) проверены и активны.
  • API-ключи в рамках рабочего пространства хранятся в защищённом хранилище секретов (не в коде).
  • Эндпоинты вебхуков общедоступны, защищены и могут обрабатывать одновременные всплески трафика.

Логика

  • Ключи идемпотентности реализованы для всех запросов на отправку.
  • Логика повторных попыток использует экспоненциальную задержку (exponential backoff) для ошибок 429 и 5xx.
  • Стоп-листы обрабатываются (не пытайтесь повторно отправлять письма на адреса с жёстким отказом).
  • Триггеры ИИ-агента имеют этап одобрения человеком или строгие лимиты запросов.

Мониторинг

  • Настроены оповещения о всплесках ответов API 4xx/5xx.
  • Панель управления отслеживает долю доставок и долю отказов.
  • Телеметрия собирается в минимально необходимом объёме и соответствует региональным законам (например, хранение только в EU).

Итоги

Транзакционная почта — побочный эффект, который легко может подорвать надёжность приложения или репутацию домена. Разделяя приём провайдером и доставку и уделяя внимание идемпотентности и подтверждению DNS, вы строите систему, устойчивую к сетевым сбоям и отказам провайдеров. Если вашей команде нужен простой способ отправлять письма с подтверждённых доменов и инфраструктура, готовая к работе с агентами, узнайте о возможностях на https://sendhq.cc.