Перейти к документации
База знаний

API отправки писем

Одно письмо или сто за вызов, сейчас или позже, и повтор без двойной отправки.

Подробности

  • POST /emails отправляет одно письмо, а POST /emails/batch до 100 независимых. Пакет не бывает «всё или ничего»: неверный адрес в пункте 7 проваливает пункт 7, остальные всё равно уходят, а ответ сообщает о каждом пункте отдельно.
  • Содержимое берётся ровно из одного источника: html и/или text, сохранённый шаблон по id или slug (закрепите версию, если текст ведёт кто-то другой) или существующий черновик. С письмом едут до 10 тегов, они возвращаются при каждом чтении.
  • scheduledAt придерживает письмо до 365 дней, как момент ISO 8601 или длительность вроде PT1H. cancellableForSeconds даёт немедленной отправке окно отмены до 900 секунд. И то и другое можно отменить, а запланированную отправку перенести, пока письмо не ушло.
  • Каждая отправка несёт Idempotency-Key, который закрепляется до того, как что-либо уйдёт, поэтому повтор после тайм-аута возвращает первый результат с Idempotency-Replayed: true. Тот же ключ с другим содержимым отклоняется как idempotency_key_reuse.
  • У каждой отправки есть id msg_ с момента приёма. GET /emails/{id} читает её, /events даёт историю по каждому получателю, а /tracking открытия и клики.
  • Добавьте translate, и письмо будет доставлено на языке получателя. Перевод делается при приёме запроса, поэтому запланированная отправка несёт одобренный вами текст, а если перевод не получается, отправка отклоняется, а не откатывается к оригиналу.
  • Вложения: до 20 файлов, встроенные в сумме до 5 МБ. Файл побольше отправляется указанием id файла из рабочего пространства и уходит ссылкой на скачивание.
  • Чего нет: тестового режима пока нет, поэтому каждый ключ доставляет по-настоящему, и у записи отправки нет статуса возврата. Возврат помечается в переписке и приходит вебхуком email.bounced, а GET /emails по-прежнему показывает sent.
  • Список подавления, раздел «Заблокированные адреса» в настройках, есть и в API. GET /suppressions читает его с поиском и фильтром по причине, POST /suppressions блокирует адрес вручную, а DELETE /suppressions/{id} снова разрешает адрес, кроме жёсткого отказа, который остаётся. SDK и сервер MCP делают то же самое, и каждое изменение вызывает вебхук suppression.added или suppression.removed.