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

Массовая рассылка — это выпуск, который отправляется сразу большой аудитории: промоакция, дайджест, новостная рассылка. Список получателей определяется до начала отправки. Отправка через API позволяет запускать такие рассылки автоматически — например, из CRM, интернет-магазина или другой внешней системы.

Через Sendsay API массовые рассылки отправляются вызовом issue.send. Доступны два способа:

• выпуск по списку или сегменту контактов;
• экспресс-выпуск с передачей списка получателей прямо в запросе.

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

• API-ключ — создайте саблогин и сгенерируйте для него ключ.
• Черновик письма — создайте заранее через интерфейс или вызовом issue.draft.set.
• Список получателей — список или сегмент получателей в Sendsay, или файл с адресами (для экспресс-выпуска).

Адрес API

Все вызовы основного API отправляются методом POST на:

https://api.sendsay.ru/api/v100/json/account

где account — код вашего аккаунта (он совпадает с основным логином).

Тело запроса — JSON в кодировке UTF-8. В каждом запросе передаётся API-ключ и код действия.

Выпуск по списку или сегменту контактов

Типовой сценарий: рассылка уходит всем, кто входит в указанный список или сегмент.

Запрос

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "group_code",
  "letter": {
    "draft.id": "123"
  },
  "sendwhen": "now",
  "relink": 1
}

Параметры

Параметр	Описание
action	Всегда issue.send
group	Код списка или сегмента контактов
letter.draft.id	ID или алиас черновика письма
sendwhen	Время отправки: now — немедленно, или дата в формате YYYY-MM-DD hh:mm — отложенный выпуск
relink	1 — преобразовывать ссылки для отслеживания кликов, 0 — нет

Ответ

Вызов issue.send для массового выпуска — асинхронный. В ответе возвращается номер трекера:

{
  "track.id": 12345
}

Через track.id можно отслеживать статус выпуска вызовом track.get. Также можно настроить колбек, который сработает по завершении выпуска.

Экспресс-выпуск

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

Адреса и данные передаются прямо в запросе через users.list или по ссылке через users.url. Параметр users.list поддерживает несколько форматов. Формат определяется автоматически по типу значения:

• Если значение — массив → JSON-массив.
• Если значение — объект → JSON-объект (АВО или КД).
• Если значение — строка ZIP с файлом workbook.xml → XLSX.
• Если значение — строка ZIP без workbook.xml → CSV (первый файл архива).
• Если значение — строка без ZIP → CSV.

Формат: JSON-массив (только Экспресс-выпуск)

Массив объектов, каждый из которых описывает одного получателя. Данные трактуются по модели Ключей Данных (КД) и могут иметь любую вложенную структуру.

Адрес получателя задаётся ключом member.email (для SMS — member.cellphone).

В шаблоне письма доступ к данным — через префикс anketa:

[% anketa.member.email %],
[% anketa.City %],
[% anketa.personal.fio.name %]

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "masssending",
  "letter": {
    "draft.id": "123"
  },
  "users.list": [
    {
      "member": { "email": "client1@test.com" },
      "City": "Москва",
      "personal": {
        "fio": { "name": "Анна", "surname": "Иванова" }
      },
      "bonuses": [100, 200, 500]
    },
    {
      "member": { "email": "client2@test.com" },
      "City": "Казань",
      "personal": {
        "fio": { "name": "Иван", "surname": "Петров" }
      },
      "bonuses": [50, 150]
    }
  ],
  "sendwhen": "now",
  "relink": 1
}

Важно

JSON-массив доступен только для экспресс-выпуска. Для импорта контактов (member.import) этот формат не поддерживается.

Формат: JSON-объект-АВО

Объект с массивом caption (описание соответствия столбцов анкетам) и массивом rows (данные). Каждая ячейка содержит одно значение — не массив и не объект.

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "masssending",
  "letter": {
    "draft.id": "123"
  },
  "users.list": {
    "caption": [
      { "anketa": "member", "quest": "email" },
      { "anketa": "info", "quest": "firstname" },
      { "anketa": "info", "quest": "city" }
    ],
    "rows": [
      ["anna@example.com", "Анна", "Москва"],
      ["ivan@example.com", "Иван", "Казань"],
      ["olga@example.com", "Ольга", "Самара"]
    ]
  },
  "sendwhen": "now",
  "relink": 1
}

Формат: JSON-объект-КД (только импорт)

Аналогичная структура с caption и rows, но caption описывает ключи данных (datakey) вместо анкет.

Импорт и добавление контактов через Sendsay API

Формат: CSV (строка)

Текстовые данные в формате CSV. Разделитель — запятая или точка с запятой. Первая строка — заголовок с описанием столбцов.

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "masssending",
  "letter": {
    "draft.id": "123"
  },
  "users.list": "member.email,info.firstname,info.city\nclient1@example.com,Анна,Москва\nclient2@example.com,Иван,Казань\nclient3@example.com,Ольга,Самара",
  "sendwhen": "now",
  "relink": 1
}

Если в значении ячейки встречается разделитель или кавычки, значение берётся в кавычки, а кавычки внутри удваиваются:

member.email,info.company,info.phone
test@test.ru,"ЗАО ""Рога и копыта""",+70000000000
test2@test.ru,"Рога, копыта и хвосты",+70000000000

Также данные можно передать ссылкой через users.url — формат определяется по Content-Type ответа и содержимому.

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

С черновиком

Нужно заранее подготовить черновик в интерфейсе CDP Sendsay или через API (issue.draft.set) и ссылаться на него по ID или алиасу:

{
  "letter": {
    "draft.id": "spring_promo"
  }
}

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

Содержимое письма можно передать прямо в запросе — тема, отправитель, HTML и текстовая версии:

{
  "letter": {
    "subject": "Весенняя акция — скидки до 50%",
    "from.name": "Интернет-магазин",
    "from.email": "test@test.ru",
    "reply.email": "support@test.ru",
    "message": {
      "html": "<html><body><h1>Весенняя распродажа!</h1></body></html>",
      "text": "Весенняя распродажа! Скидки до 50%."
    }
  }
}

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

Важно

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

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

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

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "promo_subscribers",
  "weak_draft": 1,
  "letter": {
    "draft.id": "spring_promo",
    "subject": "Только сегодня — скидки до 70%!"
  },
  "sendwhen": "now",
  "relink": 1
}

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

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

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

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

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

"encoding": "base64"

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

Дополнительные параметры выпуска

Параметр	Описание
label	Метка или массив меток (до 10 штук, до 32 байт каждая) для классификации выпуска в статистике
dkim.id	ID DKIM-ключа для подписи письма
issue_exclude	Код группы-исключения: контакты из этой группы не получат письмо
issue_exclude_filter	Фильтр исключения — условие, по которому контакты исключаются из рассылки
issue_include_filter	Фильтр включения — дополнительное условие отбора получателей
care_vars	Массив ключей персонализации: если значение пусто, письмо не отправляется
ignore_stoplist	1 — отправить даже если адрес в стоп-листе (дополнительная функция, для подключения )

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

Общие данные для всех получателей — extra

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

Важно

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

{
  "extra": {
    "PromoCode": "SPRING2026",
    "City": {
      "rus": { "long": "Санкт-Петербург", "short": "СПБ" },
      "eng": { "long": "Saint Petersburg", "short": "LED" }
    },
    "Prices": [990, 1490, 2990]
  }
}

В черновике:

Ваш промокод: [% PromoCode %]
Город: [% City.rus.long %]
Тариф «Базовый»: [% Prices[0] %] ₽

Данные из extra могут быть дополнены из черновика (указанные в запросе имеют приоритет) и из внешних источников данных в процессе выпуска.

Индивидуальные данные контакта — anketa

Для подстановки персональных данных конкретного получателя используются данные из его профиля в CDP Sendsay. Они доступны в шаблонизаторе через зарезервированное имя anketa в формате anketa.код_анкеты.код_вопроса:

Здравствуйте, [% anketa.info.firstname %]! Ваш город: [% anketa.info.city %].

Эти значения подтягиваются автоматически из базы контактов — их не нужно передавать в extra.

Отслеживание статуса выпуска

После отправки issue.send вы получаете track.id. Чтобы проверить статус выпуска, используйте запрос:

{
  "apikey": "ваш-api-ключ",
  "action": "track.get",
  "id": 12345
}

В ответе вернётся текущее состояние выпуска (формируется, доставляется, завершён) и дополнительная информация о ходе выполнения.

Управление текущим выпуском

Пока выпуск не завершён, им можно управлять через личный кабинет платформы или через API. В каждом вызове параметр id принимает либо идентификатор конкретного задания (из issue.running.list), либо "all" для действия над всеми текущими выпусками.

Список текущих выпусков

{
  "apikey": "ваш-api-ключ",
  "action": "issue.running.list"
}

В ответе — массив list с информацией о каждом выпуске:

• идентификатор задания (id),
• номер выпуска (issue.id),
• номер трекера (track.id),
• состояние формирования (processing) и доставки (delivering),
• наличие приостановки (paused).

Действия

Действие	Вызов	Описание
Приостановить	issue.running.pause	Приостанавливает формирование и доставку. Возобновление возможно в течение 3 дней, после чего данные удаляются
Возобновить	issue.running.resume	Возобновляет формирование и доставку приостановленных выпусков
Досрочно запустить отложенные части	issue.running.start	Начинает доставку всех отложенных частей растянутого выпуска, независимо от запланированного времени
Прекратить	issue.running.delete	Прекращает выпуск без возможности возобновления. Трекер переходит в состояние «Отменено»

Пример: приостановить конкретный выпуск

{
  "apikey": "ваш-api-ключ",
  "action": "issue.running.pause",
  "id": "идентификатор_задания"
}

Пример: прекратить все текущие выпуски

{
  "apikey": "ваш-api-ключ",
  "action": "issue.running.delete",
  "id": "all"
}

Важно

issue.running.pause приостанавливает только те выпуски, которые уже существуют на момент вызова. Новые выпуски продолжат приниматься и выпускаться.

Для глобальной приостановки всех выпусков (включая будущие) используйте параметр issue.paused через sys.settings.set.

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

{
  "apikey": "ваш-api-ключ",
  "action": "issue.send",
  "group": "promo_subscribers",
  "letter": {
    "draft.id": "456"
  },
  "sendwhen": "2026-03-01 10:00",
  "label": ["promo", "march"],
  "dkim.id": "my_dkim",
  "relink": 1,
  "extra": {
    "PromoCode": "MARCH2026",
    "DiscountPercent": 15
  },
  "care_vars": ["anketa.info.firstname"]
}

Этот запрос создаст отложенный выпуск на 1 марта 2026 в 10:00, по группе promo_subscribers, с черновиком 456. Общие переменные PromoCode и DiscountPercent будут одинаковы для всех, а anketa.info.firstname подтянется из карточки каждого контакта. Письма, где anketa.info.firstname пуста, будут отменены.

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

• Выпуски с новых аккаунтов проходят ручную модерацию, в целях проверки качества рассылок.
• Повторный вызов issue.send с тем же request.id не создаст дубликат — система вернёт результат предыдущего запроса.
• Для отправки по расписанию (ежедневно, еженедельно) используйте действия по расписанию — cron.*.
• Последовательность обработки параллельных вызовов не гарантирована: если один запрос зависит от другого, дождитесь завершения первого.