API для email-рассылок

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

Наш API для массовых email-рассылок позволяет управлять списками контактов, создавать и отправлять разные типы сообщений, а также смотреть статистику.

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

 

Ключ доступа не следует передавать посторонним лицам или делать видимым в коде веб-страниц. Иначе кто-то другой сможет отправлять рассылки от вашего имени.

В чем польза Unisender API

Интеграция Unisender в сервис, которым вы постоянно пользуетесь, значительно упрощает решение задач по email-маркетингу для вашей компании. Вам не придётся постоянно вручную синхронизировать списки контактов, всё будет делаться автоматически:

• Все новые покупатели из интернет-магазина будут сразу добавляться в список контактов.
• Статусы контактов будут синхронизированы с вашей CRM.
• Статистика рассылок будет передаваться в системы анализа и data mining.

Быстрый старт

Мы подготовили библиотеку для класса PHP, чтобы вы могли быстро добавить возможность отправки сообщений в ваш веб-проект.

Также для настройки API используйте базовую инструкцию по созданию интеграции.

Принцип использования API

Вызов метода

Обращение к методам API для email-рассылок — это HTTPS-запрос к URL вида:

https://api.unisender.com/LANG/api/METHOD?format=json&api_key=KEY&arg1=ARG_1&argN=ARG_N

где:

Все параметры должны быть в кодировке UTF-8. В примере выше параметры указаны в GET-запросе, но можно передавать их и в POST. Более того, параметр api_key мы настоятельно рекомендуем передавать через POST, чтобы он не сохранялся в логах прокси-серверов.

Ответ приходит в виде объекта формата JSON.

Как запрос, так и ответ может быть сжат алгоритмами gzip или bzip2.

Результат успешного вызова метода

Если вызов успешен, то объект будет включать поле "result", содержимое которого зависит от вызванного метода, и не будет содержать поле "error".

Также при успешном вызове допустимо наличие поля "warnings", которое содержит массив объектов-предупреждений с единственным строковым полем "warning".

Пример ответа успешного вызова метода:

{

"result": {

"message_id":34423432

},

"warnings": [

{"warning":"probably not a mobile phone"}

]

}

Результат неуспешного вызова метода

Если при выполнении метода возникла ошибка, в объекте ответа вы увидите поле "error" с HTML-сообщением об ошибке, а также поле "code" со строковым кодом ошибки. Поле "result" в случае ошибки должно быть проигнорировано.

Пример ответа с ошибкой:

{

"code": "invalid_arg",

"error": "fields: This value \"mymail@@@@mail.ru\" is not a valid email address.",

"result": ""

}

Основные коды ошибок при работе с API

Список доступных методов

Работа со списками контактов
Работа с дополнительными полями и метками
Создание и отправка сообщений
Работа с шаблонами
Получение статистики
Работа с заметками

Работа со списками контактов:

• getLists — получить списки для рассылок с их кодами;
• createList — создать новый список контактов;
• updateList — изменить свойства списка рассылки;
• deleteList — удалить список контактов;
• subscribe — подписать адресата на один или несколько списков рассылки;
• exclude — исключить адресата из списков рассылки;
• unsubscribe — отписать адресата от рассылки;
• importContacts — массовый импорт и синхронизация контактов;
• exportContacts — экспорт данных по контактам;
• getTotalContactsCount — получить информацию о размере базы пользователя;
• getContactCount — получить количество контактов в списке;
• getContact — получить информацию об одном контакте.

Работа с дополнительными полями и метками:

• getFields — получить список пользовательских полей;
• createField — создать новое поле;
• updateField — изменить параметры поля;
• deleteField — удалить поле;
• getTags — получить список пользовательских меток;
• deleteTag — удалить метку.

Создание и отправка сообщений:

• createEmailMessage — создать email для рассылки;
• createSmsMessage — создать SMS для массовой рассылки;
• createCampaign — запланировать массовую отправку email или SMS сообщения;
• cancelCampaign — отменить запланированную ранее массовую рассылку;
• getActualMessageVersion — получить актуальную версию письма;
• sendSms — отправить SMS-сообщение;
• checkSms — проверить статус доставки SMS;
• sendEmail — упрощённая отправка индивидуальных email-сообщений;
• sendTestEmail — отправить тестовую email-рассылку (на собственный адрес);
• checkEmail — проверить статус доставки email;
• updateOptInEmail — изменить текст письма со ссылкой подтверждения подписки;
• getWebVersion — получить ссылку на веб-версию отправленного письма;
• deleteMessage — удалить сообщение;
• updateEmailMessage — редактировать email для массовой рассылки.

Работа с шаблонами:

• createEmailTemplate  — создать шаблон сообщения для массовой рассылки;
• updateEmailTemplate — редактировать существующий шаблон сообщения;
• deleteTemplate — удалить шаблон;
• getTemplate — получить информацию о шаблоне;
• getTemplates — получить список всех шаблонов, созданных в системе;
• listTemplates — получить список всех шаблонов без body.

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

• getCampaignDeliveryStats — получить отчёт о статусах доставки сообщений для заданной рассылки;
• getCampaignCommonStats — получить общие сведения о результатах доставки для заданной рассылки;
• getVisitedLinks — получить статистику переходов по ссылкам;
• getCampaigns — получить список рассылок;
• getCampaignStatus — получить статус рассылки;
• getMessages — получить список сообщений;
• getMessage — получить информацию об SMS или email-сообщении;
• listMessages — получить список сообщений без тела и вложений.

Работа с заметками:

• createSubsciberNote — создать заметку о контакте;
• updateSubcriberNote — редактировать заметку;
• deleteSubscriberNote — удалить заметку;
• getSubscriberNote — получить информацию о заметке;
• getSubscriberNotes — получить информацию о всех заметках контакта.

Порядок вызова методов

У вас может быть один или несколько списков контактов. Предполагается, что каждый список email-адресов соответствует определённой тематике рассылки, и адресат может быть подписан на один или несколько списков одновременно.

Прежде чем рассылать email или SMS по списку, нужно узнать код списка с помощью метода getLists либо создать новый список email-адресов с помощью метода createList.

Далее нужно добавить контакты в список либо массово с помощью метода importContacts, либо по одному с помощью метода subscribe.

Теперь можно отправлять сообщения. Рассылка создается с помощью метода createEmailMessage (или createSmsMessage). Обязательно укажите id списка с адресатами. В этом случае письмо будет предназначено для всех подписчиков из этого списка активных на момент вызова createEmailMessage или createSmsMessage.

Итак, рассылка создана, но пока не отправлена. Для отправки сообщения используйте метод createCampaign. Укажите message_id, который вы получили после отправки метода createEmailMessage (или createSmsMessage), и отправьте рассылку сразу или запланируйте на нужное время.

Если нужно отправить другое письмо по тому же списку, то снова вызываете createEmailMessage/crеateSmsMessage и далее действуете как описано выше.

Если текст письма менять не надо, а нужно отправить то же самое письмо по тому же списку ещё раз, можете снова вызывать createCampaign с таким же message_id. Рассылка будет отправлена повторно.

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

Система уведомлений о событиях (Webhooks)

Webhook — механизм оповещения пользователей системы о событиях, который используют для отслеживания изменения статусов писем в реальном времени.

События, о которых может уведомлять Webhook:

• изменение статуса письма (отправлено, доставлено, отклонено, прочитано, получатель перешел по ссылке);
• контакт отписался от списка/подписался на другой список;
• изменение статуса рассылки;
• изменение данных пользователя;
• добавление подтвержденного обратного адреса;
• изменение состояния счета;
• добавление нового пользователя (для реселлеров).

Вебхуками можно управлять в личном кабинете в «Настройках» на вкладке «Webhook».

Подробнее о системе уведомлений о событиях (Webhooks)

Полезные ссылки

Как выбрать сервис для рассылок. Часть 3. Язык, безопасность, API, цена. Советы экспертов
Интеграция Unisender по API. Полный справочник методов
Отправляем письма через API Unisender