• Главная
• Ресурсы
• Документация
• API
• Интеграция

Общая информация про UniSender API

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

Работа с 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.

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

Если вызов успешен, то объект будет содержать поле "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 вне зависимости от метода.

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

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

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

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

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

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

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

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

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

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

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