Интеграция с UniSender по API

UniSender API — это специальный интерфейс для разработчиков, позволяющий интегрировать возможности электронной рассылки практически с любым открытым веб-сервисом или desktop-приложением. Наш API предоставляет возможности для управления списками подписчиков, создания и отправки разных типов сообщений, получения доступа к статистике, а также для работы партнёров.

Работа с API бесплатна для всех аккаунтов без исключения, достаточно самостоятельно включить доступ и получить ключ к нему в Личном кабинете. Ключ доступа не следует передавать другим или делать видимым в коде веб-страниц, т.к. в этом случае кто-нибудь может воспользоваться им и отправлять сообщения от вашего имени.

Доступ к API может работать в тестовом или рабочем режиме. В тестовом режиме действия, могущие привести к изменению данных, снятию денег или отправке сообщений, сообщают об успешном завершении, но на самом деле не выполняются. Этот режим удобно использовать при первоначальной настройке. Режим можно самостоятельно переключить в Личном кабинете. Кроме того, можно включить тестовый режим вместо рабочего для отдельного запроса, добавив параметр &test_mode=1.

UniSender API для вашего бизнеса

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

  • Автоматическое добавление всех новых покупателей вашего Интернет-магазина в список рассылки;
  • Синхронизация статусов подписчиков с вашей существующей CRM;
  • Создание специальных разделов для оказания услуг электронной рассылки для Интернет-порталов;
  • Загрузка статистики рассылок в системы анализа и data mining;

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

Вызов метода

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

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

где:

LANG * язык сообщений сервера API, в данный момент поддерживается ru, en, it
METHOD * название метода
KEY * ключ доступа к API
ARG_1 ... 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" в случае ошибки должно быть проигнорировано.

Стандартные коды ошибок:

unspecified Тип ошибки не указан. Подробности смотрите в сообщении.
invalid_api_key Указан неправильный ключ доступа к API. Проверьте, совпадает ли значение api_key со значением, указанным в личном кабинете.
access_denied Доступ запрещён. Проверьте, включён ли доступ к API в личном кабинете и не обращаетесь ли вы к методу, прав доступа к которому у вас нет.
unknown_method Указано неправильное имя метода
invalid_arg Указано неправильное значение одного из аргументов метода
not_enough_money Не хватает денег на счету для выполнения метода
retry_later Временный сбой. Попробуйте ещё раз позднее.
api_call_limit_exceeded_for_api_key Сработало ограничение по вызову методов API в единицу времени На данный момент это 1200 вызовов в минуту.
api_call_limit_exceeded_for_ip Сработало ограничение по вызову методов API в единицу времени На данный момент это 1200 вызовов в минуту.

 Кроме этих ошибок, могут быть и другие, указанные в описаниях методов. Коды ошибок уникальны для всего API вне зависимости от метода.

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

{"error":"AK100310-02","code":"invalid_api_key"}

Список методов

  1. Работа со списками контактов
  2. Работа с дополнительными полями и метками
  3. Создание и отправка сообщений
  4. Работа с шаблонами
  5. Получение статистики
  6. Методы для партнёрских сайтов

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

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

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

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

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

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

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

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

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

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

Методы для партнёрских сайтов

  • getCheckedEmail - получить список подтвержденных/неподтвержденных email
  • validateSender - подтвердить обратный адрес
  • register - зарегистрировать пользователя (для партнёрских сайтов)
  • checkUserExists - проверить существование пользователя по логину или email
  • getUserInfo - получить информацию о пользователе (для партнёрских сайтов)
  • getUsers - получить информацию о пользователях (для партнёрских сайтов)
  • transferMoney - перевести деньги на счёт пользователя (для партнёрских сайтов)
  • getPayments - получить список платежей пользователя (для партнёрских сайтов)
  • getTariffs - получить список тарифов (для партнёрских сайтов)
  • getAvailableTariffs - метод для получения списка тарифов (для партнёрских сайтов)
  • changeTariff - переключить тариф пользователю (для партнёрских сайтов)
  • setSenderDomain - получить и активировать DKIM-ключ для домена отправителя

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

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

Подробная статья по ссылке

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

api

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

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

Далее можно отправлять сообщения. Создаёте сообщение методом createEmailMessage (или createSmsMessage). При этом Вы указываете id списка с адресатами - и письмо будет предназначено для всех адресатов из этого списка активных на момент вызова createEmailMessage/createSmsMessage. Если это автоматически отправляемое сообщение, входящее в серию а-ля "Похудение шаг за шагом за 10 дней", то на этом действия заканчиваются, и сообщение будет отправлено, как только понадобится. Если же это не серийное сообщение, то вам надо вызывать метод createCampaign для отправки созданного сообщения.

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

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

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

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

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