Email Украина (‎044) 360 40 04
 
 
 
 

API

ВСТУПЛЕНИЕ


ПОДПИСЧИКИ


getSubscriberList – просмотр списков подписчиков.


editSubscriberList – редактирование и создание нового списка подписчиков.


getSubscriber – просмотр данных по одному подписчику.


editSubscriber – редактирование и добавление подписчика.


addSubscribers –массовое добавление подписчиков.


setSubscriberStatus – установка статуса подписчика.


deleteSubscriber – удаление подписчика.


РАССЫЛКИ


getSenderNames – список адресов, от имени которых возможная отправка писем.


getTemplates – список доступных шаблонов для рассылки.


sendEmail – одиночная отправка писем.


getEmail – просмотр данных по одиночной отправке.


sendMasEmail – массовая отправка писем.


getMasEmail – просмотр данных по массовой рассылке.




Вступление

HTTP API предоставляет возможность отправки рассылок и писем, и получения статуса доставки и статистики просмотров и переходов по ссылкам. Взаимодействие с API осуществляется по протоколу HTTP, параметры передаются методом POST. Чтобы обратиться к API-­функции, нужно вызвать ее по определенному адресу, который формируется из:

  • ­ основного адреса шлюза http://email-ua.com/apimail/
  • названия функции.

Данные переданные в POST передаются в виде ассоциативного JSON массива.

Для авторизации, в каждом запросе должен присутствовать ключ пользователя, в переменной «api_key».

После отправки возвращается ответ в виде JSON массива с массивом data, в котором находится результат выполнения функции, и массивом error, в котором находится список ошибок который произошли в результате выполнения функции. Если функция выполнилась корректно, то массив error пуст.

Подписчики

Для работы с подписчиками необходимо использовать следующие функции:


getSubscriberList – просмотр списков подписчиков.


Передаваемые параметры:

  • id – номер списка,
  • show_emails – показывать подписчиков списка.

Если вызывается без параметра id, то возвращает все списки, если параметр show_emails имеет значение 1, то возвращает список подписчиков в выбранном списке.

Результатом выполнения функции будет набор массивов с данными о списках, если параметр id не указан, или массив с данными о списке:

  • id – номер списка
  • name – название списка
  • user_name – название списка для подписчиков
  • subscribers – количество активных подписчиков
  • unsubscribers – количество отписавшихся подписчиков

Если указан параметр show_emails при просмотре одного списка, то дополнительно выведется список подписчиков в переменной users, с полями:

  • id – номер подписчика
  • status_id – номер статуса
  • status_name – название статуса
  • email – почтовый адрес
  • ctime – время создания
  • utime – время изменения
  • name – имя
  • middle_name – отчество
  • second_name – фамилия
  • company – компания
  • sex/ – пол (1-М, 2-Ж)
  • birthday – день рождения

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_LIST -­ неправильно указан номер списка

editSubscriberList – редактирование и создание нового списка подписчиков.


Передаваемые параметры:

  • id – номер списка, если данные параметр равен 0, то создается новый список;
  • name – название списка, обязательное поле при создании нового списка;
  • user_name – название списка для подписчиков.

Результатом выполнения функции будет массив с данными о списке:

  • id – номер списка
  • name – название списка
  • user_name – название списка для подписчиков
  • subscribers – количество активных подписчиков
  • unsubscribers – количество отписавшихся подписчиков

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_LIST – неправильно указан номер списка;
  • API_ERROR_NO_LIST_NAME – не указано название при создании списка.

getSubscriber – просмотр данных по одному подписчику.


Передаваемые параметры:

  • list_id – номер списка,
  • subscriber_id – номер подписчика.

Результатом выполнения функции будет массив с данными о подписчике:

  • id – номер подписчика
  • status_id – номер статуса
  • status_name – название статуса
  • email – почтовый адрес
  • ctime – время создания
  • utime – время изменения
  • name – имя
  • middle_name – отчество
  • second_name – фамилия
  • company – компания
  • sex – пол (1-М, 2-Ж)
  • birthday – день рождения

Ошибки, которые могут возникать: API_ERROR_NO_FIND_LIST – неправильно указан номер списка;

  • API_ERROR_NO_FIND_SUBSCRIBER – неправильно указан номер подписчика.

editSubscriber – редактирование и добавление подписчика.


Передаваемые параметры:

  • list_id – номер списка, обязательное поле;
  • id – номер подписчика, если данные параметр равен 0, то создается новый подписчик;
  • name -­ имя подписчика;
  • email – почта подписчика, обязательное поле при создании нового подписчика;
  • middle_name -­ отчество подписчика;
  • second_name – фамилия подписчика;
  • company – компания;
  • sex – пол (1-М, 2-Ж);
  • birthday – дата дня рождения.

Результатом выполнения функции будет массив с данными о подписчике:

  • id – номер подписчика
  • status_id – номер статуса
  • status_name – название статуса
  • email – почтовый адрес
  • ctime – время создания
  • utime – время изменения
  • name – имя
  • middle_name – отчество
  • second_name – фамилия
  • company – компания
  • sex – пол (1-М, 2-Ж)
  • birthday – день рождения

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_LIST – неправильно указан номер списка;
  • API_ERROR_NO_FIND_SUBSCRIBER – неправильно указан номер подписчика;
  • API_ERROR_NO_SUBSCRIBER_EMAIL – нет или некорректный email.

addSubscribers –массовое добавление подписчиков.


Передаваемые параметры:

  • list_id – номер списка;
  • subscribers – массив со списком ассоциативных массивов с данными про подписчика. Ключами для ассоциативных массивов являются названия переменных в данных о подписчике (name, email, middle_name, second_name, company, sex, birthday), обязательным параметром является email. Возвращает количество добавленных, существующих и ошибочных подписчиков:
    • add – добавлено
    • isset – существует
    • error – не добавлено в связи с ошибками

Пример использования функции addSubscribers:

$subscribers = array();
$subscribers[0]['email'] = 'test@test.net';
$subscribers[1]['email'] = 'test2@test.ua';
$subscribers[1]['name'] = 'Test_name';
$subscribers[1]['company'] = 'Test_company';

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_LIST – неправильно указан номер списка;
  • API_ERROR_NO_SUBSCRIBER_EMAIL – нет или некорректный email.

setSubscriberStatus – установка статуса подписчика.


Передаваемые параметры:

  • list_id – номер списка подписчиков, обязательный параметр;
  • id – номер подписчика, обязательный параметр;
  • status – номер статуса (1 – подписан, 2 -­ отписан), обязательный параметр.

Результатом выполнения функции будет массив с данными о подписчике:

  • id – номер подписчика
  • status_id – номер статуса
  • status_name – название статуса
  • email – почтовый адрес
  • ctime – время создания
  • utime – время изменения
  • name – имя
  • middle_name – отчество
  • second_name – фамилия
  • company – компания
  • sex – пол (1-М, 2-Ж)
  • birthday – день рождения

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_LIST – неправильно указан номер списка;
  • API_ERROR_NO_FIND_SUBSCRIBER – неправильно указан номер подписчика; API_ERROR_NO_STATUS – нет или неправильный статус.

deleteSubscriber – удаление подписчика.


Передаваемые параметры:

  • list_id – номер списка подписчиков, обязательный параметр;
  • id – номер подписчика, обязательный параметр.

Результатом выполнения функции будет массив с данными о подписчике как и в функции setSubscriberStatus , статус должен быть «Удален».

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_LIST – неправильно указан номер списка;
  • API_ERROR_NO_FIND_SUBSCRIBER – неправильно указан номер подписчика.

Рассылки

getSenderNames – список адресов, от имени которых возможная отправка писем.


Данная функция не принимает никаких специальных переменных.

Результатом функции будет список массивов с данными про адреса и имена. От имени которых можно отправлять письма:

  • id – номер имени
  • name – имя
  • email – адрес

getTemplates – список доступных шаблонов для рассылки.


Данная функция не принимает никаких специальных переменных.

Результатом выполнение функции будет список всех шаблонов которые доступны для отправки:

  • id – номер шаблона
  • name – название
  • time – время создания
  • description – описание

sendEmail – одиночная отправка писем.


Передаваемые параметры:

  • subject – тема письма, обязательный параметр;
  • template_id – номер шаблона для рассылки (можно получить с функции getTemplates), обязательный параметр;
  • sender – почтовый адрес от имени которого будет происходит рассылка, адрес должен быть подтвержденный (список подтвержденных адресов можно получить используя функцию getSenderNames), обязательный параметр;
  • email – почтовый адрес получателя, обязательный параметр;
  • email_name – имя получателя;
  • start_date – дата и время отправки;
  • name – специальное поле для указание определенной группы одиночных отправок.
  • status – статус отправки, если отправить письмо, статус должен равняется 2, если необходимо просто сохранить письмо в черновик то 10. Если статус не указан, письмо сохраняется в черновик. Обязательный параметр.
  • replace – поля для замены в шаблоне.

Поля для замены:

Передаваемыми данными является ассоциативный массив, ключами которого является название переменных для замены в тексте без специальных символов {%%}, а значениями массива, то на что необходимо заменить. Ключ для массива должен состоять из латинских букв верхнего регистра и знака «_» и с применением слова «API_», для предотвращения конфликтов со служебными переменными.

Пример использования замены:

В шаблоне:

$replaces = array();
$replaces['API_TITLE'] = 'Название письма';
$replaces['API_PRODUCT'] = 'Название продукта';

Результат:

<h1>Тема: {%API_TITLE%}</h1>
<p>Продукт {%API_PRODUCT%}</p>

Происходит замена специальных переменных ({%API_TITLE%}, {%API_PRODUCT%}) в шаблоне на данные с передаваемого массива.

Результатом выполнения функции будет данные о новой отправке:

  • id – номер одиночной отправки
  • status_id – номер статуса
  • status – название статуса
  • name – специальный тег, указанный при создании
  • subject – тема письма
  • from – от имени кого отправлено
  • to – кому доставлено

Ошибки, которые могут возникать:

  • API_ERROR_NO_CUSTOMER – пользователь не найден;
  • API_ERROR_NO_SUBJECT– нет темы письма;
  • API_ERROR_NO_EMAIL – нет или не валидный адрес получателя;
  • API_ERROR_NO_SENDER_NAME – отправитель не определен;
  • API_ERROR_NO_SENDER_EMAIL – отправитель не определен;
  • API_ERROR_TEXT – не найден шаблон или пустой шаблон;
  • API_ERROR_BAD_WORDS – недопустимые слова в тексте;
  • API_ERROR_NO_PAY – нет денег на балансе для отправки письма.

getEmail – просмотр данных по одиночной отправке.


Передаваемые данные:

  • id – номер одиночной рассылки, обязательный параметр.

Результатом выполнения функции будет данные отправки с дополнительными параметрами просмотров и переходов по ссылкам в письме:

  • id – номер одиночной отправки
  • status_id – номер статуса
  • status – название статуса
  • name – специальный тег, указанный при создании
  • subject – тема письма
  • from – от имени кого отправлено
  • to – кому доставлено
  • views – просмотры:
    • email – адрес получателя
    • time – дата и время просмотра
  • clicks – переходы по ссылкам
    • email -­ адрес получателя
    • time -­ дата и время перехода
    • link -­ ссылка

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_EMAIL – письмо не найдено;

senndMasEmail – массовая отправка писем.


Передаваемые параметры:

  • name – название рассылки, обязательный параметр;
  • subject – тема письма, обязательный параметр;
  • template_id – номер шаблона для рассылки (можно получить с функции getTemplates), обязательный параметр;
  • from – почтовый адрес от имени которого будет происходит рассылка, адрес должен быть подтвержденный (список подтвержденных адресов можно получить используя функцию getSenderNames), обязательный параметр;
  • list_id – номер списка получателей, обязательный параметр;
  • status -­‐ статус отправки, если отправить письмо, статус должен равняется 2, если необходимо просто сохранить письмо в черновик то 10. Если статус не указан, письмо сохраняется в черновик. Обязательный параметр.
  • replace – поля для замены в шаблоне (описание использования в функции sendEmail).
  • start_date – дата и время отправки;
  • end_date -- время завершения рассылки;
  • report_email – почтовый адрес, на который отправить отчет с результатами рассылки;
  • report_sms – телефон, на который отправить SMS о результате рассылки.

Результатом выполнения функции будет данные о новой массовой рассылке:

  • id – номер рассылки
  • status_id – номер статуса
  • status – название статуса
  • name – название рассылки
  • subject – тема письма
  • from – от имени кого отправлено
  • count – количество получателей
  • price – цена рассылки

Ошибки, которые могут возникать:

  • API_ERROR_NO_CUSTOMER – пользователь не найден;
  • API_ERROR_NO_SUBJECT – нет темы рассылки;
  • API_ERROR_NO_NAME – нет названия рассылки;
  • API_ERROR_NO_FIND_ LIST – список получателей не найден;
  • API_ERROR_NO_SUBSCRIBERS – нету активных получателей в списке;
  • API_ERROR_NO_SENDER_NAME – отправитель не определен;
  • API_ERROR_NO_SENDER_EMAIL – отправитель не определен;
  • API_ERROR_TEXT – не найден шаблон или пустой шаблон;
  • API_ERROR_BAD_WORDS – недопустимые слова в тексте;
  • API_ERROR_NO_PAY – нет денег на балансе для отправки рассылки.

getMasEmail – просмотр данных по массовой рассылке.


Передаваемые данные:

  • id – номер одиночной рассылки, обязательный параметр.

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

  • id – номер рассылки
  • status_id – номер статуса
  • status – название статуса
  • name – название рассылки
  • subject – тема письма
  • from – от имени кого отправлено
  • count – количество получателей
  • price – цена рассылки
  • views – количество просмторов
  • clicks – количество переходов

Ошибки, которые могут возникать:

  • API_ERROR_NO_FIND_EMAIL – рассылка не найдена.

Все значения ошибок

  • ERROR_INPUT_DATE – Ошибка во входных данных, невозможно передать запрос
  • ERROR_OUTPUT_DATE – Ошибка в выходных данных, запрос прислал некорректный ответ
  • API_ERROR_NO_API_KEY – Нет ключа пользователя
  • API_ERROR_NO_CUSTOMER – Пользователь не найден
  • API_ERROR_NO_FIND_LIST – Список подписчиков не найден
  • API_ERROR_NO_FIND_SUBSCRIBER – Подписчик не найден
  • API_ERROR_NO_LIST_NAME – Не задано имя списка подписчиков
  • API_ERROR_NO_SUBSCRIBER_EMAIL – Нет адреса подписчика
  • API_ERROR_NO_STATUS – Нет статуса подписчика
  • API_ERROR_NO_SUBJECT – Нет темы письма
  • API_ERROR_NO_EMAIL – Нет адреса получателя
  • API_ERROR_NO_SENDER_NAME – Нет имени отправителя
  • API_ERROR_NO_SENDER_EMAIL – Нет адреса отправителя
  • API_ERROR_TEXT – Ошибка текста
  • API_ERROR_NO_NAME – Нет названия рассылки
  • API_ERROR_NO_FIND_EMAIL – Нет подписчиков для отправки
  • API_ERROR_BAD_WORDS – В тексте некорректные слова
  • API_ERROR_NO_PAY – Оплата не удалась, закончились деньги на балансе