Управление формами через Sendsay API
Форма — это инструмент сбора данных о клиентах: адресов, предпочтений, ответов на опросы. После заполнения данные попадают в анкету-формы, а после подтверждения — переносятся в основные анкеты-хранилища и становятся доступны для рассылок и сегментации.
Создавать и настраивать формы можно в разделе Сайт → Формы. Через API вы можете автоматизировать управление формами: создавать, изменять, удалять и настраивать их программно из ваших систем.
Формы подписки
Формы подписки — инструмент для привлечения новых подписчиков через сайт. Посетитель оставляет контактные данные, после чего попадает в базу и может получать рассылки. Формы поддерживают Double Opt-In: после заполнения система отправляет письмо с подтверждением, и только после перехода по ссылке контакт считается подтверждённым.
Создать форму подписки и получить код для установки на сайт можно в разделе Сайт → Формы — без написания кода.
Двухуровневое хранение данных
При заполнении любой формы данные проходят через два уровня хранения:
- Анкета-формы (
form_xxx) — первичные, неподтверждённые данные. Появляются сразу после заполнения формы. - Анкеты-хранилища (
base,customи другие) — подтверждённые данные. Переносятся после того, как посетитель перешёл по ссылке в письме подтверждения.
Данные из обоих уровней доступны для персонализации рассылок и работы со сценариями.
Описание ключевых параметров
| Параметр | Тип | Описание |
|---|---|---|
state | 0 | 1 | Состояние формы: 0 — отключена, 1 — активна |
preview | 0 | 1 | Предзаполнение формы ранее введёнными данными при возврате из-за ошибки |
only_once | 0 | 1 | Форма заполняется одним посетителем только один раз |
anketa | строка | Код анкеты-формы, в которую собираются данные |
group | строка | Список, в который попадают заполнившие форму |
origin | строка | Источник, присваиваемый новым контактам (member.origin) |
landing.webpage | число | ID веб-страницы для landing-page формы |
fill.draft | число | ID черновика fill-letter |
fill.webpage | число | ID веб-страницы fill-page |
fill.link | строка | URL для редиректа после заполнения |
welcome.draft | число | ID черновика welcome-letter |
welcome.webpage | число | ID веб-страницы welcome-page |
welcome.link | строка | URL для редиректа после подтверждения |
notify.email | массив | Список адресов для уведомлений о заполнении |
notify.draft | число | ID черновика уведомления |
Получить список форм — form.list
{
"action": "form.list"
}
Ответ:
{
"list": [
{
"id": 101,
"name": "Подписка на рассылку",
"state": 1,
"origin": "website",
"create.date": "2025-01-15 10:30:00",
"update.date": "2025-02-20 14:00:00"
},
{
"id": 102,
"name": "Подписка на новости блога",
"state": 1,
"origin": "website",
"create.date": "2025-02-01 09:00:00",
"update.date": "2025-02-18 16:45:00"
}
]
}
Прочитать конфигурацию формы — form.get
{
"action": "form.get",
"id": 101
}
Ответ:
{
"obj": {
"id": 101,
"name": "Подписка на рассылку",
"create.date": "2025-01-15 10:30:00",
"update.date": "2025-02-20 14:00:00",
"state": 1,
"preview": 0,
"only_once": 1,
"anketa": "form_subscribe",
"group": "new_subscribers",
"origin": "website",
"landing": {
"webpage": 500
},
"fill": {
"draft": 12345,
"link": "https://example.com/thank-you"
},
"welcome": {
"draft": 12346,
"webpage": 501
},
"notify": {
"email": ["admin@example.com"],
"draft": 12347
}
}
}
Создать или изменить форму — form.set
При изменении существующей формы обновляются только те поля, которые явно указаны в запросе. Чтобы удалить необязательный параметр, передайте пустое значение.
Создание новой формы
{
"action": "form.set",
"obj": {
"name": "Подписка на новости блога",
"state": 1,
"anketa": "form_blog_subscribe",
"group": "blog_subscribers",
"origin": "website",
"only_once": 1,
"preview": 0,
"fill": {
"draft": 12350,
"webpage": 510
},
"welcome": {
"draft": 12351,
"link": "https://example.com/subscribe-complete"
},
"notify": {
"email": ["marketing@example.com", "support@example.com"],
"draft": 12352
}
},
"return_fresh_obj": 1
}
Отключение существующей формы
{
"action": "form.set",
"id": 101,
"obj": {
"state": 0
}
}
Настройка уведомлений о заполнении
Параметр notify отвечает за уведомление о заполнении формы — отдельное письмо, которое уходит вам или коллегам (не подписчику). В уведомлении используются два поля: notify.email — список адресов получателей, notify.draft — ID черновика письма с уведомлением.
Чтобы задать уведомления, передайте оба поля в form.set:
{
"action": "form.set",
"id": 101,
"obj": {
"notify": {
"email": ["marketing@example.com", "support@example.com"],
"draft": 12352
}
}
}
Чтобы отключить уведомления, передайте пустой объект:
{
"action": "form.set",
"id": 101,
"obj": {
"notify": {}
}
}
Удалить форму — form.delete
{
"action": "form.delete",
"id": 102,
"keep_anketa": 0
}
| Параметр | Описание |
|---|---|
id | Идентификатор удаляемой формы |
keep_anketa | 0 — удалить привязанную анкету (по умолчанию), 1 — оставить анкету |
Вместе с формой удаляется привязанная анкета, если её код начинается на form_ и у анкеты не установлен флаг protected. Собранные данные клиентов при этом сохраняются.
Получить код формы для сайта — form.source
{
"action": "form.source",
"id": 101,
"js": 1,
"channel": "site"
}
| Параметр | Значения | Описание |
|---|---|---|
id | число | Идентификатор формы |
js | 0 | 1 | Генерировать код с JavaScript |
channel | site | email | amp | Где будет размещена форма |
Ответ:
{
"html": "<form action='https://sendsay.ru/form/101' method='POST'>...</form>",
"url": "https://sendsay.ru/form/101",
"url.fill": "https://sendsay.ru/form/101/fill",
"url.welcome": "https://sendsay.ru/form/101/welcome"
}
Для AMP-писем ответ дополнительно содержит:
{
"amp": "<form method='POST' action-xhr='...'>...</form>",
"amp.head": "<script async custom-element='amp-form' src='...'></script>"
}
Отправить письмо подтверждения — member.sendconfirm
Если контакт был внесён в базу с необходимостью подтверждения, но письмо не было отправлено сразу, его можно выслать позже.
Отправка одному контакту:
{
"action": "member.sendconfirm",
"confirm": 1,
"letter": "код_информационного_письма",
"email": "user@example.com"
}
Отправка по списку контактов:
{
"action": "member.sendconfirm",
"confirm": 1,
"letter": "код_информационного_письма",
"list": ["user1@example.com", "user2@example.com", "user3@example.com"],
"sync": 0
}
Отправка по сегменту:
{
"action": "member.sendconfirm",
"confirm": 1,
"letter": "код_информационного_письма",
"group": "unconfirmed_subscribers",
"sync": 0
}
Параметры вызова:
| Параметр | Описание |
|---|---|
confirm | 1 — высылка писем для подтверждения внесения в базу |
unsubcancel | 1 — высылка писем для удаления из глобального стоп-листа |
unsubsendercancel | 1 — высылка писем для удаления из стоп-листа по отправителю |
letter | Код информационного письма (обязательно). Должен иметь заполненный адрес отправителя и не находиться на модерации |
issue_name | Название создаваемого выпуска. Если пусто — используется тема письма |
email | Идентификатор одного контакта |
list | Массив идентификаторов контактов |
group | Код сегмента контактов |
group.filter | Фильтр отбора контактов |
addr_type | Тип идентификатора: email, msisdn, csid и другие |
sync | 0 — асинхронный запуск, 1 — синхронный |
Информационное письмо должно содержать ссылку подтверждения. Если контакт был внесён в базу с необходимостью подтверждения, но письмо не было отправлено, его можно отправить позже через member.sendconfirm.
Как перенести данные без подтверждения
В некоторых случаях нужно перенести данные из анкеты-формы в анкеты-хранилища без ожидания подтверждения от контакта:
{
"action": "form.transfer",
"id": 101,
"email": "user@example.com"
}
Этот вызов только переносит данные. Он не подтверждает регистрацию нового контакта и не вызывает события «Форма заполнена» или «Форма подтверждена». Используйте его только когда подтверждение не требуется.
Статистика форм
Статистику заполнения форм можно получить через stat.uni. Доступные события:
| Событие | Описание |
|---|---|
event.type: "fill" | Заполнение формы |
event.type: "confirm" | Подтверждение email (DOI) |
form.id | Идентификатор формы |
answer | Данные, введённые контактом |
origin.id | Источник трафика |
Получение статистики через Sendsay API
Справочник API-методов форм
| Метод | Описание |
|---|---|
form.list | Список всех форм |
form.get | Чтение конфигурации формы по ID |
form.set | Создание или изменение формы |
form.delete | Удаление формы (и, опционально, привязанной анкеты) |
form.source | Получение HTML/JS-кода формы для установки на сайт |
form.transfer | Перенос данных из анкеты-формы в анкеты-хранилища без подтверждения |
Читайте также:
Как собирать согласие на обработку персональных данных
Получение статистики через Sendsay API