API для транзакційних розсилок
Для того, щоб використовувати API, необхідно завантажити бібліотеку SendExpert API тут.
Усі дані передаються в кодуванні UTF8. Повернуте значення у вигляді асоціативного масиву закодованого у вигляді JSON: { "error": "", "result":[...]}.
У разі помилки в параметрі «error» передається символьний код помилки. У разі успіху цей параметр буде порожній. Результат передається в параметрі «result» залежно від викликаної функції.
Приклад використання SendExpert API
# підключаємо бібліотеку
require_once 'SendExpertTransAPI.php';
# ID користувача
$user_id = '1';
# Секретний ключ, який відображається в особистому кабінеті
$user_private_key = 'e10adc3xxxxxbe56e057f20f883e';
# створюємо об'єкт API вказавши в конструкторі ключі
$api = new cSendExpertTransAPI($user_id, $user_private_key);
# Отримуємо звіт
$time_start=1506459600;
$time_end=1506608207;
$res = $api->getStatByDate($time_start, $time_end);
if($res['error'] == ""){
print_r($res['result']);
} else {
echo "Помилка: ".$res['error'];
}
URL POST запиту:
Параметри запиту:
{
"user_id": "1",
"action": "getStatByDate",
"data": {
"time_start": 1506459600,
"time_end": 1506546000
},
"sign": "bac2ff1d772299ab352178b9a09b37e8"
}
Відповідь:
{"error": "", "result": {"2017-09-27": {"TOTAL": 151, "SENDING": 0, "SENDED": 112, "SPAM": 1, "UNSUBSCRIBE": 2, "ERROR_EMAIL_IS_FULL": 0, "ERROR_EMAIL_NOT_EXIST": 2, "ERROR_UNAVAILABLE": 0, "ERROR_IS_SPAM": 0, "ERROR_DOMAIN_NOT_EMAIL": 1, "ERROR_MAIL_REFUSE": 0, "ERROR_DELIVERY": 0 }, "2017-09-28": { "TOTAL": 341, "SENDING":41, "SENDED":300, "SPAM": 0, "UNSUBSCRIBE": 0, "ERROR_EMAIL_IS_FULL": 0, "ERROR_EMAIL_NOT_EXIST": 0, "ERROR_UNAVAILABLE": 0, "ERROR_IS_SPAM": 0, "ERROR_DOMAIN_NOT_EMAIL": 0, "ERROR_MAIL_REFUSE": 0, "ERROR_DELIVERY": 0 }}}
Formatted JSON Data
{
"error": "",
"result": {
"2017-09-27": {
"TOTAL": 151,
"SENDING": 0,
"SENDED": 112,
"SPAM": 1,
"UNSUBSCRIBE": 2,
"ERROR_EMAIL_IS_FULL": 0,
"ERROR_EMAIL_NOT_EXIST": 2,
"ERROR_UNAVAILABLE": 0,
"ERROR_IS_SPAM": 0,
"ERROR_DOMAIN_NOT_EMAIL": 1,
"ERROR_MAIL_REFUSE": 0,
"ERROR_DELIVERY": 0
},
"2017-09-28": {
"TOTAL": 341,
"SENDING": 41,
"SENDED": 300,
"SPAM": 0,
"UNSUBSCRIBE": 0,
"ERROR_EMAIL_IS_FULL": 0,
"ERROR_EMAIL_NOT_EXIST": 0,
"ERROR_UNAVAILABLE": 0,
"ERROR_IS_SPAM": 0,
"ERROR_DOMAIN_NOT_EMAIL": 0,
"ERROR_MAIL_REFUSE": 0,
"ERROR_DELIVERY": 0
}
}
}
Перевірка працездатності API
Виклик
checkAPI
Вхідні параметри
Результат у разі успішного з'єднання
PASSED
Приклад використання
$res = $api->checkAPI();
Приклад відповіді
Array
(
[error] =>
[result] => PASSED
)
URL POST запиту:
https://app.sendexpert.com/api/transapi.php
Параметри запиту:
{
"user_id":"1",
"action":"checkAPI",
"data":[],
"sign":"e72635381efc5ba8ce993a0b8e26538e"
}
Відповідь:
{ "error": "", "result":"PASSED"}
Formatted JSON Data
{
"error": "",
"result":"PASSED"
}
Отримати інформацію по акаунту
Виклик
getAccountInfo
Результат повернення
Масив:
balance | поточний баланс |
---|---|
valute | валюта акаунта |
packet | поточний пакет |
name | |
mails_total | назва пакета |
mails_left | загальна кількість передплачених листів пакета |
period | залишок передплачених листів в акаунті |
date_end | період пакета, днів |
price | дата закінчення пакета у форматі UNIXTIME |
price_additional | вартість додаткового листа |
Приклад використання
$res = $api->getAccountInfo();
Приклад відповіді
Array
(
[balance] => 0.25353
[valute] => KZT
[packet] => Array
(
[name] => Лист
[mails_total] => 10000
[mails_left] => 0
[period] => 30
[date_end] => 1507982575
[price] => 2934.000000
[price_additional] => 0.366000
)
)
URL POST запиту:
https://app.sendexpert.com/api/transapi.php
Параметри запиту:
{
"user_id":"1",
"action":"getAccountInfo",
"data":[],
"sign":"e72635381efc5ba8ce933a0b8e26538e"
}
Відповідь:
{ "error": "", "result": { "balance": 104.46062, "valute":"KZT", "packet": { "name":"\u041f\u0438\u0441\u044c\u043c\u043e", "mails_total":"10000", "mails_left":"0", "period":"30", "date_end": 1507982575, "price":"2934.000000", "price_additional":"0.366000"}}}
Formatted JSON Data
{
"error": "",
"result": {
"balance": 104.46062,
"valute":"KZT",
"packet": {
"name":"\u041f\u0438\u0441\u044c\u043c\u043e",
"mails_total":"10000",
"mails_left":"0",
"period":"30",
"date_end": 1507982575,
"price":"2934.000000",
"price_additional":"0.366000"
}
}
}
Відправка листа на email
Виклик
sendMail
Вхідні параметри
params |
|
---|
Структура масиву $files
files[0]['name' => Ім'я файлу 1, 'body' => вміст файлу 1 у BASE64],
files[1]['name' => Ім'я файлу 2, 'body' => вміст файлу 2 в BASE64]
Результат повернення
У разі успішного результату:
ID | ID розсилки |
---|
Список можливих помилок:
NOT_REQUIRED_FIELDS | не всі обов'язкові поля заповнені |
---|---|
FILES_SIZE_TOO_LARGE | прикріплені файли перевищують допустимий розмір |
NOT_ENOUGH_MONEY | недостатньо коштів для надсилання повідомлення |
ERROR_SEND_MAIL | помилка формування черги надсилання |
UNSUBSCRIBE_FORM_NOT_EXIST | форма відписки з переданим ID не існує |
EMAIL_UNSUBSCRIBED | одержувач з даним email відписаний від розсилки |
ERROR_FROM_EMAIL | адреса відправника не підтверджена |
PROJECT_NOT_EXIST | ID проєкту не існує в акаунті |
Приклад використання
$files = array();
$files[] = array("name"=>"test.txt", "body"=>"aXQncyBhIHRlc3Q=");
$files[] = array("name"=>"test2.txt", "body"=>"aXQncyBhIHRlc3QyMjI=");
$params = array(
'to_email'=> '[email protected]',
'from_email' => '[email protected]',
'from_name' => 'Тест',
'subject' => 'Тестовая розсилка',
'body_html' => 'I\'m HTML! <a href="{unsubscribe_link}">Unsubscribe</a> see <a href="http://google.com">Google</a>
',
'body_text' => 'I\'m text!',
'timestamp_send' => time(),
'language' => 'ua',
'unsubscribe_form' => 5,
'attach_files' => $files
);
$res = $api->sendMail($params);
Приклад відповіді
Array
(
[error] =>
[result] => Array
(
[ID] => 43
)
)
URL POST запиту:
https://app.sendexpert.com/api/transapi.php
Параметри запиту:
{
"user_id":"1",
"action":"sendMail",
"data": {
"to_email":"[email protected]",
"from_email":"[email protected]",
"from_name":"\u0422\u0435\u0441\u0442",
"subject":"\u0422\u0435\u0441\u0442\u043e\u0432\u0430\u044f \u0440\u0430\u0441\u0441\u044b\u043b\u043a\u0430 \u0441 \u0440\u0438\u0441\u0443\u043d\u043a\u043e\u043c 3",
"body_html":"<strong>I'm HTML!</strong> <a href=\"{unsubscribe_link}\">Unsubscribe<\/a> see <a href=\"http:\/\/google.com\">Google<\/a> ",
"body_text":"I'm text!",
"timestamp_send":"1507622644",
"language":"ua",
"attach_files":[
{
"name":"test1.txt",
"body":"SGVsbG8gd29ybGQh"
},
{
"name":"test2.txt",
"body":"U29tZSB0ZXh0"
}
]
},
"sign":"6b0f04f1b776a0e34b5c043d7a94f9be"
}
Відповідь:
{ "error": "", "result": { "ID":63}}
Formatted JSON Data
{
"error": "",
"result": {
"ID":63
}
}
Отримати статус листа
Виклик
getStatusMail
Вхідні параметри
mail_id | ID листа |
---|
Результат повернення
У разі успішного результату:
STATUS |
статус листа: WAIT - очікує відправки SENDING – відправляється SENT – відправлено UNSUBSCRIBE – користувач відписався SPAM – користувач позначив лист СПАМОМ і відписався Статуси Видів помилок ERROR_EMAIL_NOT_EXIST – Електронна адреса не існує ERROR_EMAIL_IS_FULL – Електронна скринька переповнена ERROR_UNAVAILABLE Електронна скринька тимчасово недоступна ERROR_IS_SPAM Сервер одержувача вважає лист СПАМ-ом ERROR_DOMAIN_NOT_EMAIL Домен не приймає електронну пошту ERROR_MAIL_REFUSED Лист відхилено сервером одержувача ERROR_DELIVERY Інші причини щодо доставки |
---|---|
TIMESTAMP_SENT | дата надсилання листа |
TIMESTAMP_VIEW | дата останнього перегляду листа |
TIMESTAMP_MOVE | дата останнього переходу за посиланням із листа |
IP | IP адреса користувача, який здійснив перегляд або перехід з листа |
OS | операційна система користувача, який здійснив перегляд або перехід з листа |
DEVICE | тип пристрою користувача |
REASON | причина в разі відписки |
RESPONSE | відповідь сервера одержувача в момент отримання листа |
Список можливих помилок:
ERROR_MAIL_NOT_EXIST | лист із зазначеним ID не існує |
---|
Приклад використання
$mail_id = 20;
$res = $api->getStatusMail($mail_id);
Приклад відповіді
Array
(
[error] =>
[result] => Array
(
[STATUS] => SENT
[TIMESTAMP_SENT] => 1506511522
[TIMESTAMP_VIEW] => 1506511742
[TIMESTAMP_MOVE] => 1506511842
[IP] => 192.160.102.170
[OS] => Windows 7
[DEVICE] => Desktop
[REASON] =>
[RESPONSE] => 250 2.0.0 OK d16-v6si1089652wrp.194
)
)
URL POST запиту:
https://app.sendexpert.com/api/transapi.php
Параметри запиту:
{
"user_id":"1",
"action":"sendMail",
"data": {
"to_email":"[email protected]",
"from_email":"[email protected]",
"from_name":"\u0422\u0435\u0441\u0442",
"subject":"\u0422\u0435\u0441\u0442\u043e\u0432\u0430\u044f \u0440\u0430\u0441\u0441\u044b\u043b\u043a\u0430 \u0441 \u0440\u0438\u0441\u0443\u043d\u043a\u043e\u043c 3",
"body_html":"<strong>I'm HTML!</strong> <a href=\"{unsubscribe_link}\">Unsubscribe<\/a> see <a href=\"http:\/\/google.com\">Google<\/a> ",
"body_text":"I'm text!",
"timestamp_send":"1507622644",
"language":"ua",
"attach_files":[
{
"name":"test1.txt",
"body":"SGVsbG8gd29ybGQh"
},
{
"name":"test2.txt",
"body":"U29tZSB0ZXh0"
}
]
},
"sign":"6b0f04f1b776a0e34b5c043d7a94f9be"
}
Відповідь:
{ "error": "", "result": { "ID":63}}
Formatted JSON Data
{
"error": "",
"result": {
"ID":63
}
}
Отримати звіти за період часу
Виклик
getStatByDate
Вхідні параметри
time_start | час початку у форматі UNIXTIME |
---|---|
time_end | час закінчення у форматі UNIXTIME |
Результат повернення
Масив за днями, з такою структурою
[Дні звіту] => Array
(
[TOTAL] => усього листів
[SENDING] => надсилається листів
[SENT] => надіслано листів
[VIEW] => відкрито листів
[MOVE] => листів з переходами
[SPAM] => поскаржилися на спам
[UNSUBSCRIBE] => тих, хто відписався
[ERROR_EMAIL_IS_FULL] => Електронна скринька переповнена
[ERROR_EMAIL_NOT_EXIST] => - Електронна адреса не існує
[ERROR_UNAVAILABLE] => Електронна скринька тимчасово недоступна
[ERROR_IS_SPAM] => Сервер одержувача вважає лист СПАМ-ом
[ERROR_DOMAIN_NOT_EMAIL] => Домен не приймає електронну пошту
[ERROR_MAIL_REFUSE] => Лист відхилено сервером одержувача
[ERROR_DELIVERY] => Інші причини щодо доставки
)
Приклад використання
$time_start = mktime(0,0,0,9,27,2017);
$time_end = mktime(0,0,0,9,28,2017);
$res = $api->getStatByDate($time_start,$time_end);
Приклад відповіді
Array
(
[error] =>
[result] => Array
(
[2017-09-27] => Array
(
[TOTAL] => 110
[SENDING] => 0
[SENT] => 110
[VIEW] => 2
[MOVE] => 1
[SPAM] => 0
[UNSUBSCRIBE] => 0
[ERROR_EMAIL_IS_FULL] => 0
[ERROR_EMAIL_NOT_EXIST] => 0
[ERROR_UNAVAILABLE] => 0
[ERROR_IS_SPAM] => 0
[ERROR_DOMAIN_NOT_EMAIL] => 0
[ERROR_MAIL_REFUSE] => 0
[ERROR_DELIVERY] => 0
)
[2017-09-28] => Array
(
[TOTAL] => 0
[SENDING] => 0
[SENT] => 0
[VIEW] => 0
[MOVE] => 0
[SPAM] => 0
[UNSUBSCRIBE] => 0
[ERROR_EMAIL_IS_FULL] => 0
[ERROR_EMAIL_NOT_EXIST] => 0
[ERROR_UNAVAILABLE] => 0
[ERROR_IS_SPAM] => 0
[ERROR_DOMAIN_NOT_EMAIL] => 0
[ERROR_MAIL_REFUSE] => 0
[ERROR_DELIVERY] => 0
)
)
)
URL POST запиту:
https://app.sendexpert.com/api/transapi.php
Параметри запиту:
{
"user_id":"1",
"action":"getStatByDate",
"data": {
"time_start": 1506459600,
"time_end": 1506546000
},
"sign":"bac2ff1d732299ab252178b9a09b37e8"
}
Відповідь:
{ "error": "", "result": { "2017-09-27": { "TOTAL": 110, "SENDING": 0, "SENT": 110, "VIEW": 2, "MOVE": 1, "SPAM": 0, "UNSUBSCRIBE": 0, "ERROR_EMAIL_IS_FULL": 0, "ERROR_EMAIL_NOT_EXIST": 0, "ERROR_UNAVAILABLE": 0, "ERROR_IS_SPAM": 0, "ERROR_DOMAIN_NOT_EMAIL": 0, "ERROR_MAIL_REFUSE": 0, "ERROR_DELIVERY": 0}, "2017-09-28": { "TOTAL": 0, "SENDING": 0, "SENT": 0, "VIEW": 0, "MOVE": 0, "SPAM": 0, "UNSUBSCRIBE": 0, "ERROR_EMAIL_IS_FULL": 0, "ERROR_EMAIL_NOT_EXIST": 0, "ERROR_UNAVAILABLE": 0, "ERROR_IS_SPAM": 0, "ERROR_DOMAIN_NOT_EMAIL": 0, "ERROR_MAIL_REFUSE": 0, "ERROR_DELIVERY": 0}}}
Formatted JSON Data
{
"error": "",
"result": {
"2017-09-27": {
"TOTAL": 110,
"SENDING": 0,
"SENT": 110,
"VIEW": 2,
"MOVE": 1,
"SPAM": 0,
"UNSUBSCRIBE": 0,
"ERROR_EMAIL_IS_FULL": 0,
"ERROR_EMAIL_NOT_EXIST": 0,
"ERROR_UNAVAILABLE": 0,
"ERROR_IS_SPAM": 0,
"ERROR_DOMAIN_NOT_EMAIL": 0,
"ERROR_MAIL_REFUSE": 0,
"ERROR_DELIVERY": 0
},
"2017-09-28": {
"TOTAL": 0,
"SENDING": 0,
"SENT": 0,
"VIEW": 0,
"MOVE": 0,
"SPAM": 0,
"UNSUBSCRIBE": 0,
"ERROR_EMAIL_IS_FULL": 0,
"ERROR_EMAIL_NOT_EXIST": 0,
"ERROR_UNAVAILABLE": 0,
"ERROR_IS_SPAM": 0,
"ERROR_DOMAIN_NOT_EMAIL": 0,
"ERROR_MAIL_REFUSE": 0,
"ERROR_DELIVERY": 0
}
}
}
CallBack функції
Для відстеження реакцій на розсилку в системі є 8 CallBack функцій на такі типи подій:
- Відправка листа
- Лист доставлено
- Відкриття листа
- Перехід за посиланням
- Помилка доставки
- Відписка від розсилки
- Позначка як СПАМ
- Повідомлення про помилки надсилання листів SMTP-сервером
Для кожної функції вказується адреса сервера обробника цієї події.
Дані передаються за допомогою POST запиту на зазначені URL у вигляді json рядка з таким content-type у заголовку запиту:
Content-Type: application/json; charset=utf-8
Параметри відповіді
mail_id – ID листа
timestamp – час події
status = статус події:
sent
delivered
open
move
unsubscribe
spam
error
smtp-warning
checksum = MD5($account_key . json_encode($data) . $account_key);
Для типу події "Повідомлення про помилки надсилання листів SMTP-сервером" (smtp-warning) додатково вказується в особистому кабінеті максимальний поріг помилок, за якого надсилатиметься повідомлення.
$account_key — Ключ для API вашого акаунта,
$data — передані $_POST дані (без значення checksum)
Приклад даних, що передаються:
{
"data": [
{
"mail_id": "265",
"timestamp": "1508765221",
"status": "sent"
},
{
"mail_id": "266",
"timestamp": "1508765221",
"status": "sent"
},
{
"mail_id": "267",
"timestamp": "1508765221",
"status": "sent"
},
{
"mail_id": "268",
"timestamp": "1508765221",
"status": "sent"
}
],
"checksum": "b3c1eae0ced2bc39baae1cfa0828"
}
Реалізація для Rest API
Для прямого з'єднання API використовується наступний url:
https://
app.sendexpert.com
/api/transapi.php
Параметри, що передаються
Реалізація для Content-Type: application/json.
SIGN = MD5(КЛЮЧ_ДЛЯ_API + json_encode(REQUEST))
Значення, що передаються
{
"user_id"=> ID_КОРИСТУВАЧА,
"action" => ACTION,
"data" => REQUEST,
"sign" => SIGN
}
Приклад
КЛЮЧ_ДЛЯ_API = b2c1950e8b1baa4295f7ad8d4e;
ACTION = getStatByDate;
json_encode(REQUEST)= {
"time_start": 1506459600,
"time_end": 1506546000
}
SIGN = md5( b2c1950e8b1baa4295f7ad8d4e { "time_start": 1506459600, "time_end": 1506546000} )
Результат даних для відправки
{
"user_id":"1",
"action":"getStatByDate",
"data": {
"time_start": 1506459600,
"time_end": 1506546000
},
"sign": "bac2ff1d772299ab252178b9a0"
}
Реалізація для інших типів:
POST = [
'user_id' => ID_КОРИСТУВАЧА,
'sign' => MD5(КЛЮЧ_ДЛЯ_API + REQUEST),
'request' => REQUEST,
'action' => ACTION
]
де
ACTION — назва методу API, що викликається ( [checkAPI, getAccountInfo, sendMail, getStatusMail, getStatByDate])
REQUEST — JSON-рядок масиву переданих параметрів у метод. Назви параметрів згідно з документацією вище;
Приклад
КЛЮЧ_ДЛЯ_API = b2c1950e8b1baa4295f7ad8d4e;
ACTION = getStatByDate;
REQUEST = Array
(
[time_start] => 1506459600
[time_end] => 1506546000
)
SIGN = md5( b2c1950e8b1baa4295f7ad8d4e { "time_start": 1506459600, "time_end": 1506546000} )
Результат даних для відправки
Array
(
[user_id] => 1
[sign] => bac2ff1d772299ab252178b9a
[request] => { "time_start": 1506459600, "time_end": 1506546000 }
[action] => getStatByDate
)
Результат відповіді
JSON рядок із такою структурою:
JSON = [
'error' = КОД ПОМИЛКИ (порожньо якщо запит виконався успішно)
'result' = РЕЗУЛЬТАТ (відповідь згідно з функцією, що викликається)
]
Приклад
POST запит на url =
https://
app.sendexpert.com
/api/transapi.php
зі значеннями:
POST params (
[user_id] => 1
[sign] => 65bc26de3deb281d0550f660ee
[request] => { "time_start": 1506459600, "time_end": 1506608207}
[action] => getStatByDate
)
Відповідь
{"error": "", "result": {"2017-09-27": {"TOTAL": 151, "SENDING": 0, "SENDED": 112, "SPAM": 1, "UNSUBSCRIBE": 2, "ERROR_EMAIL_IS_FULL": 0, "ERROR_EMAIL_NOT_EXIST": 2, "ERROR_UNAVAILABLE": 0, "ERROR_IS_SPAM": 0, "ERROR_DOMAIN_NOT_EMAIL": 1, "ERROR_MAIL_REFUSE": 0, "ERROR_DELIVERY": 0 }, "2017-09-28": {"TOTAL": 341, "SENDING": 41, "SENDED": 300, "SPAM": 0, "UNSUBSCRIBE": 0, "ERROR_EMAIL_IS_FULL": 0, "ERROR_EMAIL_NOT_EXIST": 0, "ERROR_UNAVAILABLE": 0, "ERROR_IS_SPAM": 0, "ERROR_DOMAIN_NOT_EMAIL": 0, "ERROR_MAIL_REFUSE": 0, "ERROR_DELIVERY": 0 }}}
Formatted JSON Data
{
"error": "",
"result": {
"2017-09-27": {
"TOTAL": 151,
"SENDING": 0,
"SENDED": 112,
"SPAM": 1,
"UNSUBSCRIBE": 2,
"ERROR_EMAIL_IS_FULL": 0,
"ERROR_EMAIL_NOT_EXIST": 2,
"ERROR_UNAVAILABLE": 0,
"ERROR_IS_SPAM": 0,
"ERROR_DOMAIN_NOT_EMAIL": 1,
"ERROR_MAIL_REFUSE": 0,
"ERROR_DELIVERY": 0
},
"2017-09-28": {
"TOTAL": 341,
"SENDING":41,
"SENDED":300,
"SPAM": 0,
"UNSUBSCRIBE": 0,
"ERROR_EMAIL_IS_FULL": 0,
"ERROR_EMAIL_NOT_EXIST": 0,
"ERROR_UNAVAILABLE": 0,
"ERROR_IS_SPAM": 0,
"ERROR_DOMAIN_NOT_EMAIL": 0,
"ERROR_MAIL_REFUSE": 0,
"ERROR_DELIVERY": 0
}
}
}