Интеграция ePochta Mail Service
ePochta Email Service API (v. 3.0)
Базовые положения
Для активации email шлюза необходимо в панели управления сервисом ePochta Email в «Настройках» (https://myatompark.com/settings/) активировать использование апи 3.0. Для этого в закладке «ePochta Mail», в пункте «Активировать API 3.0» установите «Да».
Внимание! Tестовый режим включается передачей параметра test=1. Примите во внимание, что данный параметр, если он присутствует, также используется в формировании контрольной суммы.
Принцип работы с API
Методы API вызываются посредством запроса к URL:
https://atompark.com/api/email/3.0/METHOD
Параметры можно передавать методами GET, POST.
Пример GET-запроса:
https://atompark.com/api/email/3.0/METHOD?key=public_key&sum=CONTROL_SUM&arg1=ARG_1&argN=ARG_N
где:
METHOD |
название метода |
KEY |
публичный ключ доступа к API |
SUM |
контрольная сумма запроса |
ARG_1 ... ARG_N |
индивидуальные аргументы метода |
Все параметры должны иметь кодировку UTF-8. Рекомендуется передавать все параметры методом POST, чтобы он не сохранялся в логах прокси-серверов.
Для подсчета контрольной суммы необходимо:
- отсортировать все входящие ключи
- сделать конкатенацию значений по этим ключам
- сделать конкатенацию полученного значения с приватным ключом
- взять MD5 от полученного результата
Полученный от сервера ответ передается в формате JSON
Задать публичный и приватный ключи можно на странице настроек сервиса.
Пример подсчета суммы для метода addAddressbook на языке PHP.
$params ['version'] ='3.0'; $params ['action'] = 'addAddressBook'; $params ['key'] = $openKey; //you open key $params ['name'] = 'Test addressbook'; ksort ($params); $sum=''; foreach ($params as $k=>$v) $sum.=$v; $sum .= $privateKey; //your private key $control_sum = md5($sum);
Пример ответа при успешном вызове методаа
Если вызов метода выполнен успешно, то в ответе сервера будет присутствовать поле "result", включающее аргументы, характерные этому методу. Поля "error" в таком ответе не будет. Допускается наличие поля "warnings", содержимое которого состоит из массива объектов-предупреждений, указанных в одной строке поля "warning".
Пример результата успешного выполнения метода:
{ "result":{ "addressbook_id":123 } }
или
{ "result":1 }
Пример ответа с ошибкой
Если в ответе сервера присутствует только поле "error", в котором указан числовой код ошибки – это является показателем неуспешного вызова метода.
При этом в объекте ответа полностью отсутствует поле "result".
{ "error": 202, }
Для каждого метода есть свой код ошибки. Ознакомиться с перечнем всех кодов ошибки можно по ссылке.
Методы
Список методов
- Операции с адресной книгой
- addAddressbook — создать новую адресную книгу
- delAddressbook — удалить адресную книгу
- getAddressbook — получить информацию об адресной книге/списке адресных книг
- editAddressBook — редактировать имя адресной книги
- getAddresses — получить список адресов
- Управление адресами
- addAddresses — добавить адрес
- activateEmails — запросить активацию email адреса
- changeEmailStatus — блокировать/разблокировать адреса
- delEmail — удалить адреса
- delEmailFromAllBooks — удаление адреса из всех адресных книг
- getEmailInfoFromABook — получить информацию по email адресу в адресной книге
- getEmailInfo — получить информацию по email адресу в адресных книгах
- getEmailSentInfo — получить информацию по email адресу в рассылках
- editVariableValue — редактировать переменную email адреса
- Управление кампаниями
- createCampaign — создать новую кампанию
- getCampaignCost — расчет стоимости кампании
- getCampaign — получить список кампаний
- getCampaigns — информация по кампаниям
- getCampaignStats — узнать статус кампании
- getCampaignDeliveryStats — узнать статус по адресам
- getCampaignStatsByCountries — получить статистику по странам
- getCampaignStatsByReferrals — получить статистику переходов по ссылкам
- cancelCampaign — отменить кампанию
- Отправители
- getSender — получить список отправителей
- addSender — добавить отравителя
- getSenderActivateCode — получить код активации на почтовый адрес отправителя
- activateSender — активировать отправителя
- delSender — удалить отправителя
- Баланс
- getUserBalance — получить информацию о состоянии баланса
- Причина отписки (blacklist)
- getBlackList — получить список отписавшихся
- addBlackList — добавить в список отписавшихся
- delBlackList — удалить отписавшегося из списка
- getTemplates — получить список шаблонов пользователя
Операции с адресной книгой
Создание адресной книги
Используется метод addAddressbook().
Аргументы:
name — имя адресной книги
userapp - идентификатор приложения. Необязательный параметр, он не участвует в формировании контрольной суммы.
Пример запроса: https://atompark.com/api/email/3.0/addAddressbook?key=public_key&sum=control_sum&name=BOOK_NAME&userapp=somecms_v1.0
Ответ:
{ "result":{ "addressbook_id":"ADDRESSBOOK_ID" } }
В ответе будет возвращено:
addressbook_id — идентификатор адресной книги.
Удаление адресной книги
Используется метод delAddressbook().
Аргументы:
id — идентификатор адресной книги
Пример запроса: https://atompark.com/api/email/3.0/delAddressbook?key=public_key&sum=control_sum&id=ADDRESSBOOK_ID
Ответ:
Успешное выполнение
{ "result":1 }
В случае ошибки
При удалении книги, которая не существует сервер вернёт
{ "error": 213, }
Информация об адресной книге/список адресных книг
Используется метод getAddressbook().
Аргументы:
id — идентификатор адресной книги, не обязательный параметр*
* без указания идентификатора, будут возвращены все адресные книги
Пример запроса: https://atompark.com/api/email/3.0/getAddressbook?key=public_key&sum=control_sum&id=2161
Ответ:
Успешное выполнение
{ "result":{ "id":2161, "name":"super book", "all_email_qty":25, "active_email_qty":10, "inactive_email_qty":5, "activation_request_qty":10, "creationdate":"2012-04-01 18:44:36", } }
В ответе будет возвращено:
id — идентификатор адресной книги
name — имя адресной книги
all_email_qty — общее количество адресов в адресной книге
active_email_qty — количество активных адресов
inactive_email_qty — количество не активированных адресов
activation_request_qty — количество адресов для которых запрошена активация
creationdate — дата создания адресной книги
variables — переменные адресной книги(если они есть)
Редактировать имя адресной книги
Используется метод editAddressBook().
id - идентификатор адресной книги
new_name - новое название адресной книги
Пример запроса: https://atompark.com/api/email/3.0/editAddressBook?key=public_key&sum=control_sum&id=37&new_name=Some+name
Ответ:
Успешное выполнение
{ "result": 1 }
В случае возникновения ошибки при переименовании адресной книги сервер вернёт:
{ "error": 214 }
Получить список адресов
Используется метод getAddresses().
id - идентификатор адресной книги
start - позиция выборки (не обязательный параметр, по умолчанию 0)
offset - смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
Пример запроса https://atompark.com/api/email/3.0/getAddresses?key=public_key&sum=4ca6be5442e95e330e5d3780cfa9018b&id=37&start=0&offset=10
Ответ:
Успешное выполнение
{ "myTestEmail@gmail.com":{ "status":"1", "variables":{ "name":"Aleks", "age":"39" } }, ....... }
status - цифровой код статуса email адреса
variables - переменные email адреса(если они есть)
Управление адресами
Добавление адресов
Используется метод addAddresses().
Аргументы:
id_list — идентификатор(ы) адресных книг. (число или массив)
email — массив email адресов
v — двухмерный массив переменных. Не обязательное значение
userapp - идентификатор приложения. Необязательный параметр, он не участвует в формировании контрольной суммы.
Также, можно использовать метод addAddressesNew() (оптимизирован для загрузки больших списков).
Аргументы:
id_list — идентификатор(ы) адресных книг. (число или массив)
emails['address'] — email адреса разделенные символом |
emails['variables'] — переменные в формате json, разделенные символом | . Не обязательное значение
Ответ:
{ "result":1 }
Запрос активации
Используется метод activateEmails().
Аргументы:
id — идентификатор адресной книги
Пример запроса: https://atompark.com/api/email/3.0/activateEmails?key=public_key&sum=control_sum&id=2161
Ответ
{ "result":{ "activation_request_qty":100 } }
В ответе будет возвращено:
activation_request_qty — количество адресов, которые отправлены на активацию.
Блокирование/разблокирование адресов
Используется метод changeEmailStatus().
Аргументы:
id — идентификатор адресной книги
email — email адрес, который нужно удалить
Пример запроса: https://atompark.com/api/email/3.0/changeEmailStatus?key=public_key&sum=control_sum&id=2161&email=email@addr.com&status=1
Ответ
{ "result":1 }
Удаление адреса
Используется метод delEmail().
Аргументы:
id — идентификатор адресной книги
email — email адрес, который нужно удалить
Пример запроса: https://atompark.com/api/email/3.0/delEmail?key=public_key&sum=control_sum&id=2161&email=email@addr.com
Ответ
{ "result":1 }
Удаление адреса из всех адресных книг
Используется метод delEmailFromAllABooks().
Пример запросаhttp://atompark.com/api/email/3.0/delEmailFromAllABooks?key=public_key&sum=control_sum&id=2161&email=email@addr.com
email - email адрес, который нужно удалить
Ответ
{ "result":1 }
Получить информацию по email адресу в адресной книге
Используется метод getEmailInfoFromABook().
abook_id - id адресной книги
email - email адрес
Пример запросаhttps://atompark.com/api/email/3.0/getEmailInfoFromABook?key=public_key&sum=control_sum&email=myTest%40gmail.com&abook_id=3750
Ответ
Успешное выполнение
{ "email":"anton.kovalskiy@gmail.com", "status":3, "add_date":"2014-04-09", "variables":{"Company":"myCompany", "age": 39}, "variables_type":{"Company":"string","age":"number"} }
email - email адрес
status - цифровой код статуса email адреса
variables - переменные email-адреса(если они есть)
variables_type - типы переменных
Получить информацию по email адресу в адресных книгах
Используется метод getEmailInfo().
email - email адрес
Пример запросаhttps://atompark.com/api/email/3.0/getEmailInfo?key=public_key&sum=control_sum&email=myTest%40gmail.com
Ответ
Успешное выполнение
[ { "abook_id":38, "email":"myTest@gmail.com", "status":1, "variables":[ "name": "Alex", "age": 39 ] }, { "abook_id":37, "email":"myTest@gmail.com", "status":1, "variables":[] }, ................ ]
abook_id - id адресной книги в которой находится email адрес
email - email адрес
status - цифровой код статуса email адреса
variables - переменные email-адреса(если они есть)
Получить информацию по email адресу в рассылках
Используется метод getEmailSentInfo().
email - email адрес
Пример запросаhttps://atompark.com/api/email/3.0/getEmailSentInfo?key=public_key&sum=control_sum&email=myTest%40gmail.com
Ответ
Успешное выполнение
{ "statistics":{ "sent":28, "open":10, "link":8 }, "adressbooks":[ { "id":14695, "abook_name":"MyTestAddressBook", "variables":[], "unsubscribe":0 }, ......... ], "blacklist":0, "add_date":"2014-11-13" }
sent - отправлено
open - открыто
link - перешли по ссылке
adressbooks - информация об адресной книге(id, название, переменные(если они есть), отписан ли емайл)
blacklist - находится ли адрес в "Черном списке"
add_date - дата добавления email адреса
Редактировать переменную email адреса
Используется метод editVariableValue().
abook_id - id адресной книги
email - email адрес
var_name - имя переменной
var_value - новое значение переменной
Ответ
Успешное выполнение
{ "result":1 }
Управление кампаниями
Создание кампании
Используется метод createCampaign().
Аргументы:
name — имя кампании, не обязательный параметр (если не указать будет создано имя по-умолчанию)
sender_name — имя отправителя
sender_email — email отправителя
subject — тема письма
body — тело письма(base64)
list_id — идентификатор адресной книги по которой будет делаться рассылка
attachments — ассоциативный массив файлов-вложений. В качестве ключа указывается имя файла, в качестве значения - содержимое файла.
userapp — идентификатор приложения. Необязательный параметр, он не участвует в формировании контрольной суммы.
Ответ
{ "result":{ "id":3214, "status":1, "count":300, "tariff_email_qty":200, "paid_email_qty":100, "overdraft_price":15.21, "ovedraft_currency":"USD" } }
В ответе будет возвращено:
id — идентификаторы созданной рассылки
status — статус рассылки
count — количество адресов, на которые будет произведена рассылка
tariff_email_qty — количество сообщений, отправленных за счёт включенных в тариф
paid_email_qty — количество сообщений оплаченных сверх тарифа
overdraft_price — стоимость оплаченных сверх лимита
ovedraft_currency — валюта оплаты сверх лимита (USD, RUR, UAH, EUR)
Расчет стоимости кампании
Используется метод getCampaignCost().
Пример запроса: https://atompark.com/api/email/3.0/getCampaignCost?key=public_key&sum=control_sum&abook_id=3750
abook_id - идентификатор адресной книги по которой будет делаться рассылка
Ответ
{ "result":1, "cur":"UAH", "message":"You are going to send 26 emails.", "overdraftAllEmailsPrice":0, "addressesDeltaFromBalance":0, "addressesDeltaFromTariff":"26", "max_emails_per_task":2000 }
result 1 - хватило средств, 0 - нет
max_emails_per_task - максимальное кол-во имейлов по тарифу за одну рассылку
addressesDeltaFromTariff - кол-во имейлов которое будет снято в рамках тарифа
addressesDeltaFromBalance - кол-во имейлов которое выходит за границы тарифа, за них будут сняты дополнительные средства с баланса
overdraftAllEmailsPrice - кол-во средств которое будет снято(в случае если addressesDeltaFromBalance больше 0)
cur - валюта пользователя
Получить список кампаний
Используется метод getCampaign().
Аргументы:
start — позиция выборки (не обязательный параметр, по умолчанию 0)
offset — смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
Пример запроса: https://atompark.com/api/email/3.0/getCampaign?key=public_key&sum=control_sum
Ответ
{ "result":{:{ "name":"campaign name", "message":{ "sender_name":"sender name", "sender_email":"test@addr.com", "subject":"email subject", "body":"hello world!!!", "list_id":1234, "attachments":["file1.txt","file2.jpg"] } "status":1, "count":300, "tariff_email_qty":200, "paid_email_qty":100, "overdraft_price":15.21, "ovedraft_currency":"USD" }, } }
В ответе будет возвращено:
id — идентификаторы созданной рассылки
status — статус рассылки
count — количество адресов, на которые будет произведена рассылка
tariff_email_qty — количество сообщений, отправленных за счёт включенных в тариф
paid_email_qty — количество сообщений оплаченных сверх тарифа
overdraft_price — стоимость оплаченных сверх лимита
ovedraft_currency — валюта оплаты сверх лимита (USD, RUR, UAH, EUR)
message — блок, содержащий параметры отправленного сообщения
sender_name — имя отправителя
sender_email — email отправителя
subject — тема письма
body — тело письма(base64)
list_id — идентификатор адресной книги
attachments — список файлов, которые были прикреплены к письму
Информация по кампаниям
Используется метод getCampaigns().
Похож на метод getCampaign, отличие - в ответе информация по статистике(эта информация не всегда нужна)
Пример запроса: http://atompark.com/api/email/3.0/getCampaigns?key=public_key&sum=control_sum
name - имя(или часть имени) рассылки
start - позиция выборки (не обязательный параметр, по умолчанию 0)
offset - смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
order - направление сортировки, возможные варианты: 0, 1
Ответ
{ "result":[{ "id":35, "name":"testSend", "message":{ "sender_name":"Alex", "sender_email":"myTest@gmail.com", "subject":"mySubject", "body":"base64_text", "list_id":38, "list_name":"myTest", "attachments":"" }, "status":3, "count":200, "tariff_email_qty":200, "paid_email_qty":0, "overdraft_price":0, "ovedraft_currency":"USD", "send_date":{ "date":"2012-07-04 13:03:00", "timezone_type":3, "timezone":"UTC" }, "date_created":{ "date":"2012-07-04 10:04:14", "timezone_type":3, "timezone":"UTC" }, "statistics":{ "sent":0, "delivered":0, "open":0, "link":0, "unsubscribe":0, "error":0, "complaint":"0", "errors_list":[] } }, ......... ] }
id - id рассылки
name - имя рассылки
message - информация о отправленом сообщении
sender_name - имя отправителя
sender_email - email отправителя
subject - тема письма
body - тело письма(base64)
list_id - id адресной книги
list_name - имя адресной книги
attachments - список файлов, которые были прикреплены к письму
status - статус рассылки
count - количество адресов, на которые будет произведена рассылка
tariff_email_qty - количество сообщений, отправленных за счёт включенных в тариф
paid_email_qty - количество сообщений оплаченных сверх тарифа
overdraft_price - стоимость оплаченных сверх лимита
ovedraft_currency - валюта оплаты сверх лимита (USD, RUR, UAH, EUR)
send_date - дата отправки
date_created - дата создания
statistics - статистика по кампании
sent - отправлено
delivered - доставлено
open - открыто
link - перешли по ссылки
complaint - жалоб
error - ошибок
unsubscribe - отписалось
errors_list - первое значение - цифровой статус, второе - кол-во ошибок с данным статусом
Статус кампании
Используется метод getCampaignStats().
Аргументы:
id — идентификатор кампании
Пример запроса: https://atompark.com/api/email/3.0/getCampaignStats?key=public_key&sum=control_sum&id=1234
Ответ
{ "result":{ "id":1234, "status":1, "count":300, "tariff_email_qty":200, "paid_email_qty":100, "overdraft_price":15.21, "ovedraft_currency":"USD", "statistics":{ "sent":300, "delivered":290, "open":100, "link":50, "unsubscribe":1, "error":15, "complaint":0, "errors_list":[ "9":10, "6":5 } } }
В ответе будет возвращено:
id — идентификаторы созданной рассылки
status — статус рассылки
count — количество адресов, на которые будет произведена рассылка
tariff_email_qty — количество сообщений, отправленных за счёт включенных в тариф
paid_email_qty — количество сообщений оплаченных сверх тарифа
overdraft_price — стоимость оплаченных сверх лимита
ovedraft_currency — валюта оплаты сверх лимита (USD, RUR, UAH, EUR)
statistics — общая статистика рассылки
sent — отправлено
delivered — доставлено
open — открыто
visit_link — сделан переход по ссылке
Статус по адресам
Используется метод getCampaignDeliveryStats().
Аргументы:
id — идентификатор кампании
start — позиция выборки (не обязательный параметр, по умолчанию 0)
offset — смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
Пример запроса: https://atompark.com/api/email/3.0/getCampaignDeliveryStats?key=public_key&sum=control_sum&id=1234
Ответ
{ "result": [, , ], ['email@adddr.com',1,'2012-11-06 00:12:13'] } }
В ответе будет возвращено:
email — email адрес
last time status update
status — цифровой код статуса email адреса
Получить статистику открытий по странам
Используется метод getCampaignStatsByCountries().
id - идентификатор кампании
Пример запроса: https://atompark.com/api/email/3.0/getCampaignStatsByCountries?key=public_key&sum=control_sum&id=18988
Ответ
Успешное выполнение
{ "result":[ ["RU",50], ["US",42], ["IN",20], ......... ] }
первый параметр('US', 'RU', etc) - буквенные код страны
второй параметр - кол-во открытий по конкретной стране
Получить статистику переходов по ссылкам
Используется метод getCampaignStatsByReferrals().
id - идентификатор кампании
Пример запроса: https://atompark.com/api/email/3.0/getCampaignStatsByReferrals?key=public_key&sum=control_sum&id=18988
Ответ
Успешное выполнение
{ "result":[ ["http://www.epochta.ru/email/",18], ["http://www.epochta.ru/email/api/",8], ......... ] }
первый параметр- href ссылки
второй параметр - кол-во переходов по конкретной стране
Отменить кампанию
Используется метод cancelCampaign().
Отменить кампанию возможно, если кампания имеет статус "Запланирована" или "На модерации"
id - идентификатор кампании
Пример запроса: https://atompark.com/api/email/3.0/cancelCampaign?key=public_key&sum=control_sum&id=18988
Ответ
Успешное выполнение
{ "result":1 }
Отправители
Получить список отправителей
Используется метод getSender().
Аргументы:
start — позиция выборки (не обязательный параметр, по умолчанию 0)
offset — смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
Пример запроса: https://atompark.com/api/email/3.0/getSender?key=public_key&sum=control_sum
Ответ
{ "result":['email@addr.com','email2@addr.com'] }
Добавление отправителя
Используется метод addSender().
Аргументы:
sender_name — имя отправителя
sender_email — email адрес отправителя
Пример запроса: https://atompark.com/api/email/3.0/addSender?key=public_key&sum=control_sum&sender_name=Sender name&sender_email=email@addr.com
Ответ
{ "result":1 }
Получить код активации на почтовый адрес отправителя
Используется метод getSenderActivateCode().
Аргументы:
sender_email — email адрес отправителя
Пример запроса: https://atompark.com/api/email/3.0/getSenderActivateCode?key=public_key&sum=control_sum&sender_email=email@addr.com
Ответ
{ "result":1 }
Активация отправителя
Используется метод activateSender().
Аргументы:
sender_email — email адрес отправителя
code — активационный код
Пример запроса: https://atompark.com/api/email/3.0/activateSender?key=public_key&sum=control_sum&code=12312sender_email=email@addr.com
Ответ
{ "result":1 }
Удаление отправителя
Используется метод delSender().
Аргументы:
sender_email — email адрес отправителя
Пример запроса: https://atompark.com/api/email/3.0/delSender?key=public_key&sum=control_sum&code=12312sender_email=email@addr.com
Ответ
{ "result":1 }
Получение состояния баланса
Используется метод getUserBalance().
Аргументы:
currency — валюта возвращаемого баланса
Пример запроса: https://atompark.com/api/email/3.0/getUserBalance?key=public_key&sum=control_sum¤cy=USD
Ответ
{ "result":{ "balance_currency":123.45, "currency":"USD" } }
В ответе будет возвращено:
balance_currency — баланс в выбранной валюте
currency — валюта, в которой возвращается баланс
Причина отписки (blacklist)
Получить список отписавшихся
Используется метод getBlackList().
Аргументы:
start — позиция выборки (не обязательный параметр, по умолчанию 0)
offset — смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
Пример запроса: https://atompark.com/api/email/3.0/getBlackList?key=public_key&sum=control_sum
Ответ
{ "result":['email@addr.com','email2@addr.com'] }
В ответе будет возвращено:
result — содержит список отписавшихся
Добавить в список отписавшихся
Используется метод addBlackList().
Аргументы:
email — email который нужно добавить в список отписавшихся
Пример запроса: https://atompark.com/api/email/3.0/addBlackList?key=public_key&sum=control_sum&email=email@addr.com
Ответ
{ "result":1 }
Удалить отписавшегося из списка
Используется метод delBlackList().
Аргументы:
email — email который нужно удалить из списка отписавшихся
Пример запроса: https://atompark.com/api/email/3.0/delBlackList?key=public_key&sum=control_sum&email=email@addr.com
Ответ
{ "result":1 }
Получить список шаблонов пользователя
Используется метод getTemplates().
start - позиция выборки (не обязательный параметр, по умолчанию 0)
offset - смещение относительно позиции (не обязательный параметр, по умолчанию 10, максимально = 100)
name - имя шаблона (не обязательный параметр)
Ответ
Успешное выполнение
[ { "template_name":"my_test", "body":"dGVzdA==" }, ........ ]
template_name - имя шаблона
body - тело шаблона(base64)