Инструкция по созданию API интеграций email и sms рассылок с UniSender

Ниже описаны рекомендации по разработке модуля (плагина) для CMS и CRM систем, который обеспечит интеграцию между вашей CMS или CRM системой и Unisender.

Возможности интеграции

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

регистрироваться в Unisender или привязывать уже существующею учетную запись Unisender к модулю;
импортировать email и другие поля контактов из вашей системы в Unisender для дальнейших рассылок по ним;
создавать письма для рассылок;
отправлять рассылку по импортированным email;
получать статистику по рассылкам писем: количество доставленных, прочитанных писем и количество переходов по ссылкам.

Если при разработке у вас возникли вопросы по этому документу или вы хотите разработать интеграцию, которая отличается от описанной выше, вы можете обратиться на наш почтовый ящик plugins@unisender.com за консультацией.

Вход существующего пользователя Unisender

Отобразить форму с полем API-ключ и информацию, как его получить и включить в Unisender.
При подтверждении формы вызвать метод getLists.
Если метод возвращает информацию о списках без ошибок, отобразить сообщение
«Вы успешно вошли в систему».
Перейти к пункту «Выбор списка и доп. полей для импорта контактов».

Регистрация пользователя

Отобразить форму с полями Email и Пароль.
При подтверждении заполнения формы отправить данные из полей формы методом register.
Если метод отработал, вы получите API-ключ пользователя.
Сохранить полученный API-ключ в вашем приложении.
Отобразить пользователю сообщение о том, что регистрация прошла успешно.
Перейти к пункту «Выбор списка и доп. полей для импорта контактов».

Выбор списка и доп. полей для импорта контактов

Отобразить окно «Выберите список для импорта контактов или создайте новый», в котором отображаются названия списков, полученные методом getLists, а также окно для ввода названия нового списка.
Если пользователь выбрал список, вы должны сохранить его id в вашей системе (далее id списка понадобится для импорта и создания письма).
Если пользователь ввел название нового списка, вы должны его создать в Unisender методом createList и сохранить id полученного списка в системе.
Отобразить сообщение «Список выбран».
После подтверждения прочтения сообщения отобразить окно с маппингом (соответствие полей вашей системы и Unisender) полей контактов вашей системы и Unisender. Окно должно отображать доступные поля для импорта из вашей системы и поля Unisender. Поля Unisender можно получить методом getFields. Если пользователь хочет создать новое поле в Unisender нужно воспользоваться методом createField.
При маппинге полей нужно согласовать типы полей.
После маппинга полей пользователем нужно отобразить сообщение об успешном завершении маппинга.
Перейти к пункту «Создание письма для рассылки».

Импорт контактов рекомендуем проводить непосредственно перед созданием рассылки.

Создание письма для рассылки

Получить список подтвержденных адресов пользователя getCheckedEmail.
Если пользователь хочет отправить рассылку от неподтвержденного ранее адреса, подтвердить адрес отправителя методом validateSender.
После вызова метода validateSender отобразить сообщение «Вам на адрес отправлено письмо-подтверждение, после перехода по ссылке вы сможете отправлять рассылки с этого адреса».
Создать письмо для отправки методом createEmailMessage. При создании письма указать список, выбранный на шаге «Выбор списка и доп. полей для импорта контактов». С помощью параметра attachments можно добавить вложения, максимальный размер — 500 Кб.
Сохранить полученный id письма
Предложить проверить отображение письма в почтовом ящике пользователя. Если пользователь согласен, отправить тестовое письмо методом sendTestEmail.

Отправка рассылки и получение статистики

Пользователь может выбрать один из способов отправки:

сразу;
запланировать отправку.

2. Если пользователь подтвердил отправку (нажал на кнопку «Отправить рассылку» или «Запланировать отправку»), ваша система должна импортировать контакты в выбранный список на шаге «Выбор списка и доп. полей для импорта контактов», используя метод importContacts. При вызове метода importContacts в параметре fields указываются поля Unisender, куда нужно импортировать данные, а в параметре data — данные из полей вашей системы. Импортировать можно не более 500 контактов за вызов. После импорта нужно отобразить сообщение об успешном завершении импорта.

3. Вызвать метод createCampaign, в котором передать:- message_id — идентификатор письма, созданного на шаге «Создание письма для рассылки»;
- start_time — время отправки в зависимости от выбранного способа отправки;
- contacts_url — необязательный параметр, используется, если надо отправить рассылку не по всему списку, а только конкретному сегменту, содержит ссылку на файл с контактами, по которым должна отправиться рассылка;
- track_read = 1;
- track_links = 1.

4. В случае, если пользователь выберет способ отправки «отправить сразу», показать сообщение «Рассылка отправлена», если выберет «запланировать отправку», то «Отправка рассылки запланирована».

Получение статуса и статистики рассылки

Получить текущий статус рассылки можно методом getCampaignStatus.

Получить статистику по рассылке можно методом getCampaignCommonStats.

Инструкция по созданию интеграций с CMS и CRM