Первые шаги
Пользовательские данные
- Обзор адаптивного email-редактора
- Создание оформления для письма
- Создание сквозных модулей
- Настройка адаптивности
- Настройка Smart-элементов
- Оформление промовкладки для Gmail
- Добавление Rolloverʼа
- Добавление фона в письмо
- Добавление анкорных ссылок
- Библиотека блоков (Модули)
- Добавление блока "Видео"
- Добавление таблицы в письмо
- Работа с блоком "Баннер"
- Добавление пользовательских шрифтов
- Добавление кастомных иконок соцсетей
- Работа с блоком "Соцсети"
- Создание кнопки CTA
- Редактирование HTML и CSS
- Робота с блоком "Изображения"
- Работа с блоком “Таймер"
- Настройка блока "Меню"
- Создание футера
- Использование ИИ в email-редакторе
Омниканальность
- SDK для мобильных приложений
- Управление ключами доступа к мобильному SDK
- Подключение мобильного приложения
- Создание Google проекта для Mob Push
- Создание мобильных push-сообщений
- Настройка аналитики доставляемости и кликов
- Планирование мобильных push-уведомлений
- Настройка универсальных ссылок (deeplinks & Universal links)
- Отправка тестовых сообщений из отладки запросов
- Настройка виджетов для сайта
- Вызов виджета
- Сохранение данных из виджетов в поля контактов
- Защита от раздражения
- Действия после заполнения формы
- Расширение для тестирования форм в Google Chrome
- Создание pop-up-форм с помощью Google Tag Manager или WordPress
- Отправка событий из форм подписки в Google Analytics
- Замена системного сценария Double Opt-In
- Настройка геоданных для правил вызова виджетов
Автоматизация
- Двойное подтверждение подписки
- Приветственная серия
- Приветственная серия с сегментацией по категориям
- Запуск сценария после импорта контактов
- Регулярный сценарий для группы
- Поздравление с днем рождения
- Привязка сценария к кнопке
- Согласование переменных события со сценарием на примере сценария "Заказ доставлен"
- Сбор отзывов о заказе
- Реактивация клиентов и подписчиков
- Отправка рассылки непрочитавшим
- Настройка дополнительных рассылок
Персонализация
- Подстановка промокода из файла
- Подстановка промокода с использованием API
- Принципы генерации промокодов с помощью PHP/JAVA
- Подстановка промокода с помощью персонализации
- Загрузка промокодов для использования в сценарии
- Генерация промокодов в сценарии
- Отправка промокода с помощью препроцессора
- HTTP-запрос для передачи промокода из сообщения в карточку контакта
Аналитика
- Отчёт по email-рассылке
- Отчет по SMS-рассылке
- Отчет по рассылке Web Push
- Отчет по Viber-рассылке
- Отчет по рассылке Mob Push
- Отчет по рассылке App Inbox
- Отчет по взаимодействию с виджетами
- Отчет по триггерной рассылке
- Отчет по AMP-рассылке
- Отчет по мультиязычной рассылке
- Настройка передачи UTM-меток
- Визуализация дохода
- Отслеживание эффективности рассылок в Google Analytics
Мультиязычность
Отслеживание событий и поведения
- Разветвление сценария в зависимости от параметров события
- Отслеживание активности на сайте при помощи Generate event
- Валидация параметров события
- Отслеживание активности клиентов в мобильных приложениях
- Подстановка данных из событий в сообщения
- События для запуска триггерных рассылок
- Вебхуки для отслеживания активности
Товарные рекомендации
API
Смена системы
Документы
Интеграция
Интеграция с API – частые вопросы
Где искать всю техническую документацию?
Вся техническая документация по формату данных, стандартам и кодам ошибок, а также всегда актуальное описание ресурсов API и примеры кода для их вызова находятся на ресурсе "API Reference".
Здесь мы постараемся дать ответы на часто задаваемые вопросы о том, как пользоваться API или как решить конкретную проблему, с более развернутыми описаниями и примерами, чем в описании методов.
Как проверить, что API работает, а параметры доступа правильные
Самый простой вариант – это получить информацию о вашем аккаунте: Get account info.
Рассмотрим на примере приложения Postman, которое предназначено для легкого тестирования API. Скачайте приложение и установите на компьютер. Чтобы история запросов сохранилась, нужно авторизоваться, но для быстрого теста можно обойтись и без регистрации в сервисе.
Для начала в параметрах во вкладке Authorization в строке Type выберите Basic Auth:
Чтобы авторизоваться, нужно:
- ввести любое значение для поля Username,
- ввести значение вашего API-ключа в поле Password.
Затем:
- Выберите метод. В нашем случае это GET.
- Введите ресурс. В нашем случае это Get account info.
- Нажмите на кнопку Send для отправки запроса.
Так будет выглядеть запрос для получения информации о вашем аккаунте:
Как отписать контакт, если отписка прошла в личном кабинете пользователя на сайте?
Для управления отпиской используйте ресурс API Add emails to unsubscribed list или Remove emails from unsubscribed list.
Важно! Вы отписываете не конкретный контакт, а только email пользователя, другие медиаканалы (SMS, Viber, push) остаются доступны. Если в организации электронный адрес используют несколько контактов, то все они перестануть получать массовые рассылки после отписки.
1. Для добавления емейла в список отписавшихся существует следующий метод: Add emails to unsubscribed list.
Тело запроса выглядит так:
{
"emails" : [ "test1@mail.com", "test2@mail.com" ]
}
emails – это список адресов, которые будут помечены как отписавшиеся.
2. Для удаления емейла из списка отписавшихся используется Remove emails from unsubscribed list.
Тело запроса аналогичное предыдущему рассмотренному ресурсу: вы вводите список адресов, которые будут удалены из отписавшихся.
Рассмотрим ресурс Add emails to unsubscribed list на примере в Postman:
- Задайте конфигурации:
- Выберите метод запроса POST
- Введите ресурс Add emails to unsubscribed list
- В разделе Body выберите raw и формат передачи данных JSON (application/json):
- Укажите тело запроса в формате:
{
"emails" : [ "...", ... ]
}
- Нажмите Send для отправки запроса:
Как использовать динамический контент в письмах?
Реализовать отправку письма с динамическим контентом можно двумя способами. Первый способ предполагает простую подстановку данных в тело письма из запроса, передаваемого при помощи API ресурса Generate event. Массив params может содержать произвольное количество объектов вида:
...
{
"name": "название поля",
"value": "значение поля"
}
...
Для подстановки данных необходимо воспользоваться velocity.
Допустим, передан такой запрос:
{
"eventTypeKey": "testEvent",
"keyValue": "example@email.com",
"params": [{
"name": "discount",
"value": "5%"
},{
"name": "link",
"value": "https://example.site.com/items_for_sale"
}
]
}
В сообщении необходимо использовать записи вида $!data.get('discount') и $!data.get('link'), где динамически будут подставляться персональные значения скидки и ссылки, переданные в запросе.
Чтобы контент, передаваемый ресурсом Generate event, подставлялся в тело сообщения, нужно подготовить сценарий с использованием этого письма.
Второй способ предполагает отправку сообщений сразу, без использования сценария. Для этого используйте ресурс API Send prepared message, где {id} – идентификатор письма, в которое будут подставляться данные при отправке получателю.
Тело запроса в минимальном виде:
{
"recipients" : [ {
"locator" : "...",
"jsonParam" : "..."
} ]
}
recipients – массив адресов получателей сообщения.
locator – получатель. Например, email-адрес для email сообщений, номер телефона для SMS или Viber.
jsonParam – данные в виде json для подстановки в письмо.
Метод позволяет сгенерировать разный контент для каждого конкретного получателя. Для этого передача данных организована парами "емейл + набор параметров". Параметры передаются в виде произвольной json-структуры, ко всем полям которой в теле письма можно обратиться так: $data.get('field_name').
Есть возможность:
- Задать условие отображения какого-либо блока html-кода: #if($data.get('field_name').equals('0')) ... #end.
- Организовать цикл по элементам массива: #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... #end.
- Производить в теле письма арифметические операции со значениями полей. Обратите внимание, что двойные кавычки внутри json-структуры с параметрами должны экранироваться: "jsonParam" : "{\"field1\":\"value1\", ... }".
Более подробно о ресурсе написано в статье "Использование API ресурса smartsend".
Как использовать event-ы для триггеров, например, "Ваш заказ оформлен"
С помощью API очень удобно отправлять триггеры, используя метод API Generate event. Все внешние данные, которые поступают в сообщения, попадают в объект data. Чтобы вывести нужный параметр, прописываем $!data.get('имя параметра'). Для этого Вам необходимо:
- Подготовить тело запроса.
Минимальное тело запроса имеет вид:
{ "eventTypeKey": "...", "keyValue": "...", "params": [{ "name": "...", "value": "..." }, ... ] }
, где
eventTypeKey – идентификатор-ключ типа события. Если в системе нет типа события с таким ключом, то он создастся автоматически;
keyValue – идентификатор события, может совпадать с идентификатором или email-ом контакта;
name – имя параметра;
params – список параметров.
- Создать письмо с динамическим контентом, которое вы хотите отправлять (Сообщения → Сообщения → Создать Email).
Обратите внимание! Значение в кавычках после $!data.get должно соответствовать значению name в массиве параметров params, который вы будете передавать в запросе.
- Создать сценарий, чтобы контент, передаваемый ресурсом Generate event, подставлялся в тело сообщения (Триггеры → Сценарии → Добавить сценарий).
- Создать событие (Триггеры → Типы событий → Добавить тип события) с ключом, который будет использован в запросе (поле eventTypeKey), и привязать к событию сценарий, созданный на предыдущем этапе.
Предварительно создавать событие в аккаунте не обязательно.
После того как вы передадите первый запрос, событие в аккаунте создастся автоматически.
Для тестирования вызовите запрос в Postman.
- Задайте конфигурации:
- Выберите метод запроса POST
- Введите ресурс Generate event
- В разделе Body выберите raw и формат передачи данных JSON (application/json).
- Укажите тело запроса в формате:
После нажатия на кнопку Send запрос будет отправлен, и в течение минуты мы получим письмо вида:
После успешной отправки запроса, вы можете проверить правильность выполнения:
1) передачи события в систему: Триггеры → История событий;
2) отправки письма: Рассылки → Одиночные;
3) получения письма с правильно подставленными элементами: Письмо во входящих.
Как передавать заказы по API?
Для передачи заказов необходимо использовать ресурс Add orders. В запросе можно передать от 1 до 1000 заказов. Чтобы подставлять в письма товары, в заказах нужно передавать массив items с данными этих товаров. Формат запроса и описание всех полей доступны здесь. Если данные товаров в письмах не нужны либо вы передаете заказы только для RFM-анализа, массив можно не передавать.
Пример тела запроса:
{
"orders": [{
"externalOrderId": "100500",
"externalCustomerId": "12345",
"totalCost": 1000,
"status": "INITIALIZED",
"date": "2017-03-08T09:30:00+02:00",
"email": "mail@example.com",
"phone": "380942583691",
"firstName": "John",
"lastName": "Smith",
"currency": "USD",
"shipping": 10,
"discount": 0,
"deliveryMethod": "express",
"paymentMethod": "cash",
"deliveryAddress": "First str. 1",
"items": [{
"externalItemId": "200600",
"name": "Super Device",
"category": "devices",
"quantity": 1,
"cost": 990,
"url": "http://example.com/item/200600",
"imageUrl": "http://example.com/item/200600/image.png",
"description": "High quality"
}]
}]
}
Каждый заказ должен содержать обязательные поля, они выделены жирным. Остальные поля – опциональные. Успешный ответ на запрос будет содержать статус 200.
Для заказов можно использовать несколько статусов:
- Для только что созданного заказа – INITIALIZED.
- Для заказа в процессе доставки – IN_PROGRESS.
- Для оплаченного и доставленного заказа – DELIVERED.
- Для отмененных заказов – CANCELLED.
Важно! Для формирования RFM используются только заказы в статусе DELIVERED.
Чтобы обновить статус или другие данные заказа, передавайте обновленный заказ с тем же externalOrderId. По этому параметру в системе определяется уникальность заказов.
Проверить, попал ли заказ в систему и корректно ли переданы поля, можно в личном кабинете в разделе Триггеры → Заказы. Щелкнув на ID заказа, вы увидите все поля в формате JSON.
Как получить статус отправленного сообщения через API?
Если вы отправляете одиночные сообщения ресурсами Send prepared message, Send email message, Send SMS message, Send viber message,, то отправка происходит в асинхронном режиме. А именно: после запроса к API ваше сообщение ставится в очередь на отправку и через некоторое время (обычно в течение нескольких секунд) отправляется. В ответ на каждый из этих запросов вы получите подобную структуру:
{
"id": "0",
"results": {
"id": "0",
"locator": "test@mail.com",
"status": "OK",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
}
}
Затем, чтобы получить статус этого сообщения и любого сообщения, отправленного через любой канал, необходимо вызвать GET-запрос Get single message status.
Параметр ids – это список идентификаторов requestId, разделённых запятой. Вы получите такой ответ:
{
"results": {
"status": "DELIVERED",
"requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",
"failed": "false",
"delivered": "true"
}
}
Подробнее о данных из этого ответа и в частности о статусах сообщения можно прочитать здесь: "статусы".
Как интегрировать форму подписки через API?
Для интеграции формы подписки необходимо вызвать ресурс Subscribe contact. Минимальное тело запроса выглядит так:
{
"contact" : {
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
}
}
Таким образом в системе появится один контакт с email-ом.
Чтобы задать имя контакта, необходимо добавить в тело запроса поле firstName в объекте contact:
{
"contact" : {
"firstName" : "...",
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
}
}
Чтобы указать, в какие группы попадёт подписавшийся контакт, нужно добавить к запросу поле groups – массив строковых значений, названий групп. Если какие-то из групп не существуют в системе, они будут созданы автоматически:
{
"contact" : {
"firstName" : "...",
"channels" : [ {
"type" : "email",
"value" : "test@mail.com"
} ]
},
"groups" : [ "Subscribers" ]
}
После вызова этого ресурса в системе автоматически генерируется одно из двух событий: subscribeFromAPI – в случае, если создался новый контакт; и subscribeUpdateFromAPI – в случае, если такой контакт существует. Эти события вы можете увидеть в разделе Триггеры → История событий.
К любому типу события можно привязать сценарий, который будет запущен в момент генерации этого события. Целесообразно отправить новому контакту письмо для подтверждения подписки.
Чтобы убедиться, что новый контакт создан, вы можете найти его: перейти в Контакты → Все контакты, и затем ввести в строку поиска нужный емейл.
Вы увидите, что емейл контакта будет серого цвета, – это означает, что он не активен и требует подтверждения от владельца.
На такие адреса невозможно отправить рассылку, они могут получать только письма для подтверждения подписки и другие транзакционные сообщения, например, письмо о брошенной корзине или подтверждение оформленного заказа.
Как передать значения дополнительных полей контакта через API?
Рассмотрим обновление дополнительных полей на примере ресурса Add/update contacts – создание/обновление контактов. Минимальное тело этого запроса с дополнительными полями выглядит так:
{
"contacts": [{
"channels": [{
"type": "email",
"value": "test@mail.com"
}],
"fields": [{
"id": 15868,
"value": "ж"
}]
}],
"customFieldsIDs": [12345]
}
channels – это список медиа-каналов контакта; в данном примере передаётся один медиаканал – емейл
fields – это список дополнительных полей, передаваемых попарно: идентификатор поля + значение
Получить идентификаторы всех дополнительных полей, которые существуют в вашей организации, можно двумя способами.
Первый – посмотреть идентификаторы в Меню аккаунта → Настройки → Дополнительные поля.
Второй – вызвать ресурс Get catalog list. Это GET-метод без параметров, который вернет вам структуру, подобную этой:
{
"addressBook": {
"addressBookId": "7200",
"name": "Основной",
"fieldGroups": {
"name": "Personal",
"fields": [
{
"id": "15867",
"name": "День рождения",
"description": {
"type": "date",
"required": "false",
"readonly": "false"
}
},
{
"id": "15868",
"name": "Пол",
"description": {
"type": "combobox",
"allowedValues": {
"possibleValues": [
"м",
"ж"
]
},
"required": "false",
"readonly": "false"
}
}
]
}
}
}
список fields – это и есть список всех ваших дополнительных полей. Кроме прочей информации, каждый объект этого списка содержит идентификатор поля, который вам нужно использовать при передаче его значения.
Протестируйте API на реальных рассылках