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"
}
Реaлизация для остальных типов:
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
}
}
}