Опубликовано:

21 сентября 2026

Отправка транзакционных рассылок через Sendsay API

Транзакционная рассылка — это сообщение одному конкретному получателю в ответ на его действие: подтверждение регистрации, чек после покупки, уведомление о доставке, восстановление пароля.

Отправка через API используется, когда письмо должно формироваться и отправляться автоматически — например, сразу после оплаты заказа или запроса на восстановление пароля. Это позволяет интегрировать рассылку в работу сайта, приложения или CRM.

Через Sendsay API транзакционные письма отправляются вызовом issue.send с параметром group = personal.

Когда выбрать основное API, а когда Stream API?

Отработка одного транзакционного письма в основном API может занимать несколько секунд, но основное API даёт доступ почти ко всем настройкам issue.send (расширенная персонализация, ленты новостей и др.).

Если вам требуется отправлять более 10 писем в секунду на постоянной основе — используйте Stream API.

Требования для отправки

API-ключ — создайте саблогин и сгенерируйте для него ключ.
Черновик письма или содержимое письма, передаваемое прямо в запросе.

Два способа указания получателя и данных

Способ 1: email — адрес получателя

При указании получателя через параметр email система отправляет письмо на этот адрес.

Если контакт существует в базе CDP Sendsay, его данные из карточки подтягиваются автоматически и доступны в шаблоне через anketa.код_анкеты.код_вопроса. Если контакта в базе нет — письмо всё равно будет отправлено (при соответствующем тарифе и настройках аккаунта), но данные из карточки будут недоступны.

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "personal",
  "email": "client@test.com",
  "letter": {
    "draft.id": "order_confirmation"
  },
  "extra": {
    "OrderId": "A-12345",
    "Total": "4 500 ₽"
  },
  "sendwhen": "now"
}

В шаблоне доступны и данные получателя из базы, и переменные из extra:

[% anketa.info.firstname %], ваш заказ [% OrderId %] на сумму [% Total %] принят.

Способ 2: users.list — все данные передаются в запросе

Вместо email можно передать получателя и его данные через users.list.

В этом случае в users.list должен быть только один получатель, а данные из карточки контакта в Sendsay не используются.

users.list принимает JSON-массив, JSON-объект или CSV-строку.

JSON-массив (данные доступны через anketa.*):

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "personal",
  "letter": {
    "draft.id": "order_confirmation"
  },
  "users.list": [
    {
      "member": { "email": "client@test.com" },
      "name": "Анна",
      "OrderId": "A-12345",
      "Total": "4 500 ₽"
    }
  ],
  "sendwhen": "now"
}

В шаблоне все данные — через anketa:

[% anketa.name %], ваш заказ [% anketa.OrderId %] на сумму [% anketa.Total %] принят.

JSON-объект-АВО:

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "personal",
  "letter": {
    "draft.id": "order_confirmation"
  },
  "users.list": {
    "caption": [
      { "anketa": "member", "quest": "email" },
      { "anketa": "info", "quest": "firstname" }
    ],
    "rows": [["client@test.com", "Анна"]]
  },
  "sendwhen": "now"
}

Когда использовать users.list

Используйте users.list, если ваша система уже имеет все нужные данные о получателе и вы не хотите зависеть от состояния карточки контакта в CDP Sendsay.

Это особенно удобно для транзакционных писем, где данные (сумма заказа, ссылка на сброс пароля и т.д.) формируются на лету.

Персонализация через extra

Параметр extra содержит произвольные данные, передаваемые в выпуск. Они доступны в шаблонизаторе по имени ключа.

Важно

Чтобы избежать пересечений с именами, которые используются системой (anketa, lenta, date, form), рекомендуем начинать имена ваших ключей с большой буквы.

extra можно использовать вместе с обоими способами указания получателя — и с email, и с users.list.

Содержимое письма

С черновиком

Если письмо имеет фиксированный шаблон, создайте черновик в интерфейсе или через API и ссылайтесь на него через letter.draft.id.

Без черновика

Для динамических писем, где всё содержимое формируется на вашей стороне, можно передать его прямо в запросе.

Запрос

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "personal",
  "email": "client@test.com",
  "letter": {
    "subject": "Ваш заказ #A-12345 подтверждён",
    "from.name": "Интернет-магазин",
    "from.email": "orders@myshop.ru",
    "reply.email": "support@myshop.ru",
    "to.name": "Анна",
    "message": {
      "html": "<html><body><h1>Спасибо за заказ!</h1><p>Номер: A-12345</p></body></html>",
      "text": "Спасибо за заказ! Номер: A-12345"
    }
  },
  "sendwhen": "now"
}

Параметры содержимого (letter)

Параметр	Описание
`subject`	Тема письма (обязательно)
`from.name`	Имя отправителя
`from.email`	Адрес отправителя (обязательно, должен быть подтверждён)
`reply.email`	Адрес для ответов
`to.name`	Имя получателя (отображается в поле «Кому»)
`message.html`	HTML-версия письма
`message.text`	Текстовая версия письма
`message.amp`	AMP-версия письма (опционально)

Важно

Должна быть заполнена хотя бы одна версия — HTML или text.

Слабый черновик (weak_draft)

Вы можете использовать черновик как основу, но переопределить часть его параметров прямо в запросе. Для этого передайте weak_draft: 1:

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "personal",
  "email": "client@test.com",
  "weak_draft": 1,
  "letter": {
    "draft.id": "welcome_template",
    "subject": "Добро пожаловать, Анна!"
  },
  "sendwhen": "now"
}

При weak_draft: 1 параметры subject, from.email, from.name, reply.email, to.name и message.* из запроса имеют приоритет над значениями из черновика. Остальные настройки черновика сохраняются.

Прикреплённые файлы

Файлы передаются в массиве letter.attaches:

{
  "letter": {
    "draft.id": "invoice_template",
    "attaches": [
      {
        "name": "invoice.pdf",
        "content": "JVBERi0xLjQK...",
        "encoding": "base64"
      }
    ]
  }
}

Для двоичных файлов содержимое кодируется в base64 и указывается:

"encoding": "base64"

Для текстовых файлов (CSV, TXT) можно передать содержимое как есть в UTF-8 без указания encoding.

Защита от пустой персонализации (care_vars)

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

{
  "care_vars": ["anketa.info.firstname", "OrderId"]
}

Если значение любой из указанных переменных окажется пустым, письмо не будет отправлено. Работает как для данных получателя (anketa.код_анкеты.код_вопроса), так и для переданных в extra.

Дополнительные параметры

Параметр	Описание
`dkim.id`	DKIM-ключ для подписи
`label`	Метки выпуска для группировки в статистике (до 3 штук)
`customer.id`	Ваш внутренний идентификатор получателя — для связки со статистикой
`relink`	`1` — отслеживать клики, `0` — нет

Ответ

Для транзакционного выпуска ответ содержит track.id в корне:

{
  "track.id": 67890
}

После отправки транзакционного письма в отчёте track.get для данного track.id будет доступен номер письма (letter). Используя letter в stat.uni, можно получить информацию по конкретному транзакционному письму.

Группировка писем в выпуски

Транзакционные письма автоматически группируются в выпуски для формирования статистики. Правила группировки:

Если используется черновик — письма группируются по номеру черновика и dkim.id. Название черновика становится названием выпуска.
Если черновик не используется — группировка происходит по комбинации меток (label) и dkim.id.
Дополнительно учитываются: день отправки, саблогин, наличие AMP-версии.

Пример: полный транзакционный запрос

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "personal",
  "email": "test@test.com",
  "letter": {
    "draft.id": "password_reset"
  },
  "extra": {
    "ResetLink": "https://myshop.ru/reset?token=abc123"
  },
  "dkim.id": "myshop_dkim",
  "customer.id": "user_7890",
  "label": ["password_reset"],
  "care_vars": ["ResetLink", "anketa.info.firstname"],
  "sendwhen": "now",
  "relink": 0
}

В черновике password_reset используются и extra-переменные, и данные получателя:

[% anketa.info.firstname %], вот ссылка для сброса пароля: [% ResetLink %]

Особенности работы транзакционных выпусков

Адрес отправителя (from.email) должен быть заранее подтверждён в аккаунте. Не допускается использование адресов на бесплатных почтовых доменах (mail.ru, gmail.com, yandex.ru).
Письма не отправляются на адреса, которые находятся в стоп-листе или имеют постоянные ошибки доставки (если не указан ignore_stoplist).
Повторный запрос с тем же request.id вернёт результат предыдущего вызова, а не создаст дубликат.

Требования для отправки​

Два способа указания получателя и данных​

Способ 1: email — адрес получателя​

Способ 2: users.list — все данные передаются в запросе​

Персонализация через extra​

Содержимое письма​

С черновиком​

Без черновика​

Запрос​

Параметры содержимого (letter)​

Слабый черновик (weak_draft)​

Прикреплённые файлы​

Защита от пустой персонализации (care_vars)​

Дополнительные параметры​

Ответ​

Группировка писем в выпуски​

Пример: полный транзакционный запрос​

Особенности работы транзакционных выпусков​