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

Главная Возможности Интеграция с UniSender Интеграция по API

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

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

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

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

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

Вызов метода

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

 http://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 Не хватает   денег на счету для выполнения метода
api_call_limit_exceeded_for_api_key Сработало ограничение по вызову методов API в единицу времени. На данный момент это 300 вызовов в минуту.
api_call_limit_exceeded_for_ip Сработало ограничение по вызову методов API в единицу времени. На данный момент это 300 вызовов в минуту.

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

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

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

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

  • Работа со списками контактов
    • getLists - получить списки рассылки с их кодами
    • createList - создать новый список рассылки
    • updateList - изменить свойства списка рассылки
    • deleteList - удалить список рассылки
    • subscribe - подписать адресата на один или несколько списков рассылки
    • exclude - исключить адресата из списков рассылки
    • unsubscribe - отписать адресата от рассылки
    • importContacts - массовый импорт и синхронизация контактов
    • exportContacts - экспорт всех данных контактов
  • Создание и отправка сообщений
    • createEmailMessage - создать e-mail для массовой рассылки
    • createSmsMessage - создать SMS для массовой рассылки
    • createCampaign - запланировать массовую отправку e-mail или SMS сообщения
    • getCampaigns - получить список рассылок
    • getCampaignStatus - получить статус рассылки
    • sendSms - отправить SMS-сообщение
    • checkSms - проверить статус доставки SMS
    • sendEmail - упрощённая отправка индивидуальных email-сообщений
    • checkEmail - проверить статус доставки email
    • updateOptInEmail - изменить текст письма со ссылкой подтверждения подписки
    • deleteMessage - удалить сообщение
  • Получение статистики
    • getCampaignDeliveryStats - получить отчёт о статусах доставки сообщений для заданной рассылки
    • getCampaignAggregateStats - получить отчёт о статусах доставки сообщений для заданной рассылки, сгруппированных по типам результата
    • getVisitedLinks - получить статистику переходов по ссылкам
  • Работа с дополнительными полями и метками
    • getFields - получить список пользовательских полей
    • createField - создать новое поле
    • updateField - изменить параметры поля
    • deleteField - удалить поле
    • getTags - получить список пользовательских меток
    • deleteTag - удалить метку
  • Методы для партнёрских сайтов
    • validateSender - подтвердить обратный адрес
    • register - зарегистрировать пользователя (для партнёрских сайтов)
    • checkUserExists - проверить существование пользователя по логину или email
    • getUserInfo - получить информацию о пользователе (для партнёрских сайтов)
    • getUsers - получить информацию о пользователях (для партнёрских сайтов)
    • transferMoney - перевести деньги на счёт пользователя (для партнёрских сайтов)
    • getPayments - получить список платежей пользователя (для партнёрских сайтов)
    • getTariffs - получить список тарифов (для партнёрских сайтов)
    • changeTariff - переключить тариф пользователю (для партнёрских сайтов)
    • callbacks - оповещение об отписке, подтверждении обратного адреса

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

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

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

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

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

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

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

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

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

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

Также мы сделали несколько примеров реализации наиболее популярных функций по управлению списками и рассылкой.