API для email та SMS-розсилок

API для звичайних розсилок

Для того, щоб використовувати API, необхідно завантажити бібліотеку SendExpert API здесь.

Усі дані передаються в кодуванні UTF8. Повернуте значення у вигляді асоціативного масиву закодованого у вигляді JSON: {"error":"","result":[...]}.

У разі помилки в параметрі «error» передається символьний код помилки. У разі успіху цей параметр буде порожній. Результат передається в параметрі «result» залежно від викликаної функції.

Приклад використання SendExpert API

                    
                        # підключаємо бібліотеку
                        require_once 'SendExpertAPI.php';

                        # ID користувача
                        $user_id = '1';

                        # Секретний ключ, який відображається в особистому кабінеті
                        $user_private_key = 'e10adc3xxxxxbe56e057f20f883e';

                        # створюємо об'єкт API вказавши в конструкторі ключі
                        $api = new cSendExpertAPI($user_id, $user_private_key);

                        echo "Отримати звіт SMS-розсилки";
                        $res = $api->getSMSReport($project_ID = 96, $ID = 83);
                        if ($res['error'] == ""){
                            print_r($res['result']);
                        } else {
                            echo "Помилка: ".$res['error'];
                        }

Отримати список проектів поточного користувача

Виклик

getProjects

Вхідні параметри

ні

Результат повернення

Список проєктів поточного користувача:

name	назва проекту
ID	ID проекту

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [name] => ProjectName1
            [ID] => 1
        )

    [1] => Array
        (
            [name] => ProjectName2
            [ID] => 52
        )
}

Отримати список полів бази для проекту

Виклик

getProjectsStructure

Вхідні параметри

project_id	ID проекту, для якого необхідно отримати список полів

Результат повернення

Список полів бази для проєкту:

name	назва поля
ID	ID поля
type	тип поля

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [name] => Електронна адреса
            [ID] => 1
            [type] => email
        )

    [1] => Array
        (
            [name] => Ім'я
            [ID] => 2
            [type] => text
        )
}

Отримати всіх підписників (експорт)

Виклик

getSubscribers

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список підписників

Результат повернення

Список підписників:

ID	ID підписника
1	значення поля з кодом "1"
...	...
х	значення поля з кодом "х"
GROUPS	список груп, до яких підключений цей користувач
DATE	дата додавання підписника
UNSUBSCRIBED	прапор відписки передплатника від розсилок
DISABLE	відключений чи ні підписник
ACTIVATED	підтвердження та активація підписника адміністрацією

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 23
            [1] => [email protected]
            [2] => Лілія
            [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412936959
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )

    [1] => Array
        (
            [ID] => 34
            [1] => [email protected]
            [2] => Анна
	    [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412937514
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )
)

Отримати список користувачів за телефоном або за його частиною

Виклик

getSubscribersByPhone

Вхідні параметри

project_id	ID проєкту, для якого необхідно отримати список підписників
phone	повний номер телефону підписника або його частину

Наприклад

				
                    $phone = '38(067)';

Результат повернення

Список користувачів:

ID	ID підписника
1	значення поля з кодом "1"
...	...
х	значення поля з кодом "х"
GROUPS	список груп, до яких підключений цей користувач
DATE	дата додавання підписника
UNSUBSCRIBED	прапор відписки підписника від розсилок
DISABLE	відключений чи ні підписник
ACTIVATED	підтвердження та активація підписника адміністрацією

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 1
            [1] => [email protected]
            [2] => Євген
            [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412937697
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )

    [1] => Array
        (
            [ID] => 12
            [1] => [email protected]
            [2] => Ольга
            [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412937023
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )
}

Отримати список користувачів за email або за його частиною

Виклик

getSubscribersByEmail

Вхідні параметри

project_id	ID проекту, для якого необхідно отримати список передплатників
email	адреса електронної пошти підписника або її частина

Наприклад

				
                    $email = '@gmail.com';

Результат повернення

Список користувачів:

ID	ID підписника
1	значення поля з кодом "1"
...	...
х	значення поля з кодом "х"
GROUPS	список груп, до яких підключений цей користувач
DATE	дата додавання підписника
UNSUBSCRIBED	прапор відписки підписника від розсилок
DISABLE	відключений чи ні підписник
ACTIVATED	підтвердження та активація підписника адміністрацією

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 23
            [1] => [email protected]
            [2] => Василь
            [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412936959
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )

    [1] => Array
        (
            [ID] => 34
            [1] => [email protected]
            [2] => Іван
	    [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412937514
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )
}

Додати підписника

Виклик

addSubscriber

Вхідні параметри

project_id	ID проєкту, до якого необхідно додати підписника
subscriber	масив із даними підписника зі структурою [ID поля] => [Значення]
subscriber ["GROUPS"]	список груп, до яких необхідно підключити підписника
responder	ID автовідповідача або масив з автовідповідачами для API або параметр "ALL". Якщо вказано ID автовідповідачів, тоді їх буде запущено в разі успішного додавання користувача. Якщо вказано параметр ALL - будуть запущені всі автовідповідачі для API для доданого користувача

Наприклад

				
$subscriber = array();
$subscriber[100] = '[email protected]';
$subscriber[500] = 'Тарас';
$subscriber["groups"] = array('31','54');
$responder = array(123,124);

Результат повернення

Масив:

id	ID підписника
1	значення поля з кодом "1"
...	...
х	значення поля з кодом "х"
groups	список груп, до яких підключений цей користувач
date	дата додавання підписника
unsubscribed	прапор відписки підписника від розсилок
disable	відключений чи ні підписник
activated	підтвердження та активація підписника адміністрацією

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 23
            [1] => [email protected]
            [2] => Василь
            [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412936959
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )

    [1] => Array
        (
            [ID] => 34
            [1] => [email protected]
            [2] => Іван
	    [GROUPS] => Array
                (
                    [0] => Array
                        (
                            [ID] => 31
                            [name] => ProjectName1
                        )

                )

            [DATE] => 1412937514
            [UNSUBSCRIBED] => 0
            [DISABLE] => 0
            [ACTIVATED] => 1
        )
}

Редагувати підписника

Виклик

editSubscriber

Вхідні параметри

project_id	ID проекту, в якому необхідно відредагувати підписника
ID	ID підписника
subscriber	масив із даними підписника зі структурою [ID поля] => [Значення]
subscriber ["groups"]	список груп, до яких необхідно підключити підписника

Наприклад

				
$subscriber = array();
$subscriber[2] = 'Тарас1';
$subscriber["GROUPS"] = array();

Результат

“OK” у разі успішної зміни даних

Видалити підписника

Виклик

deleteSubscriber

Вхідні параметри

project_id	ID проекту, з якого необхідно видалити підписника
ID	ID підписника

Результат

“OK” у разі успішної зміни даних

Отримати зворотні адреси електронної пошти

Виклик

getSenderEmails

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список зворотних адрес електронної пошти

Результат повернення

Масив елементів:

email	email адреса зворотньої електронної пошти
ID	ID адреса зворотньої електронної пошти
checked	прапор активності перевірки адреси зворотньої електронної пошти

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [email] => [email protected]
            [ID] => 6
            [checked] => 1
        )

    [1] => Array
        (
            [email] => [email protected]
            [ID] => 23
            [checked] => 1
        )
)

Отримати список груп

Виклик

getGroupsList

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список альфа-імен
filter необов'язковий	повна або часткова маска для пошуку в назві групи

Результат повернення

Список груп:

name	назва групи
ID	ID групи

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [name] => Група 1
            [ID] => 100
        )
    [1] => Array
        (
            [name] => Група 2
            [ID] => 500
        )

)

Додати групу

Виклик

addGroup

Вхідні параметри

project_id	ID проєкту, в якому необхідно створити групу
name	назва групи

Результат повернення

У разі успішного результату:

ID	ID групи

Список можливих помилок:

ERROR_NAME	назва містить заборонені символи
ERROR_ALREADY_EXIST	група з даним ім'ям уже існує в системі

Приклад відповіді

				  
Array
(
    [ID] => 100
)

Отримати список Альфа-імен для SMS

Виклик

getAlphaNames

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список альфа-імен

Результат повернення

Список Альфа-імен:

name	альфа-ім'я
ID	ID альфа-імені
checked	прапор активності альфа-імені

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [name] => SENDEXPERT
            [ID] => 29
            [checked] => 1
        )

)

Надіслати SMS-повідомлення підписникам

Виклик

sendSMS

Вхідні параметри

project_id	ID проекту, в якому необхідно надіслати SMS-повідомлення
alphaname_id	ID альфа-імені, яке буде використовуватися як відправник
subscribers	список ID користувачів, яким необхідно надіслати SMS
message	повідомлення, яке необхідно надіслати (підтримується персоналізація)
date	дата відправлення SMS-повідомлення у форматі UNIXTIME

Наприклад

				
$subscribers = array();
$subscribers[] = 337361;
$subscribers[] = 43235;
$message = "Привіт {{Ім'я}}! Це тест API!";
$date = mktime();
$res = $api->sendSMS($project_ID = 96, $alphaname_id = 29, $subscribers, $message, $date);

Результат повернення

Масив:

ID	ID створеної розсилки

Приклад відповіді

				  
Array
(
    [ID] => 84
)

Отримати список SMS-розсилок

Виклик

getSMSList

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список SMS-розсилок
time_start	дата і час початку звіту у форматі UNIXTIME
time_end	дата і час закінчення звіту у форматі UNIXTIME

Наприклад

				
$time_start = strtotime("-2 days");
$time_end = time();
$res = $api->getSMSList($project_ID = 96, $time_start, $time_end);

Результат повернення

Список SMS-розсилок у форматі:

id	ID розсилки
alphanameID	ID Альфа-імені від якого надіслано розсилку
body	зміст розсилки
time_start	дата і час старту розсилки у форматі UNIXTIME
type	статус розсилки
date_create	дата створення розсилки у форматі UNIXTIME
price	вартість розсилки в у.е.

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 84
            [alphanameID] => 29
            [body] => SMS працює!
            [time_start] => 1437135207
            [type] => in_proccess
            [date_create] => 2015-07-17 12:13:28
            [price] => 0.023399
        )

    [1] => Array
        (
            [ID] => 83
            [alphanameID] => 29
            [body] => Привіт {{Ім'я}}! Це тест API!
            [time_start] => 1436799595
            [type] => sended
            [date_create] => 2015-07-13 15:00:23
            [price] => 0.023399
        )
)

Отримати звіт SMS-розсилки

Виклик

getSMSReport

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список SMS-розсилок
ID	ID SMS-розсилки

Результат повернення

Список SMS-розсилок у форматі:

total	кількість підписників, яким буде надіслано повідомлення
sended	кількість підписників, яким уже було надіслано повідомлення
delivered	кількість підписників, які отримали повідомлення
not_delivered	кількість підписників, які не отримали повідомлення
not_exist	кількість підписників, у яких неіснуючий номер телефону
alphanameID	ID Альфа-імені від якого надіслано розсилку
body	зміст розсилки
time_start	дата і час старту розсилки у форматі UNIXTIME
type	статус розсилки
date_create	дата створення розсилки
price	вартість розсилки в у.е.

Приклад відповіді

				  
Array
(
    [total] => 1
    [sended] => 1
    [delivered] => 0
    [not_delivered] => 0
    [not_exist] => 0
    [alphanameID] => 29
    [body] => Привіт {{Ім'я}}! Це тест API!
    [time_start] => 1436799595
    [type] => sended
    [date_create] => 2015-07-13 15:00:23
    [price] => 0.023399
)

Отримати список email-розсилок

Виклик

getMailList

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список email-розсилок
time_start	дата і час початку звіту у форматі UNIXTIME
time_end	дата і час закінчення звіту у форматі UNIXTIME

Наприклад

				
$time_start = strtotime("-2 days");
$time_end = time();
$res = $api->getMailList($project_ID = 96, $time_start, $time_end);

Результат повернення

Список email-розсилок у форматі:

ID	ID email-розсилки
fromID	ID зворотної адреси електронної пошти
sender_name	ім'я відправника
subject	тема листа (підтримує персоналізацію)
body	вміст листа (підтримує персоналізацію)
alternate_body	альтернативний текст листа без тегів, для text-plain відображення
images_place	місце зберігання малюнків
time_start	дата і час старту розсилки у форматі UNIXTIME
type	статус розсилки
date_create	дата створення розсилки

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 827
            [fromID] => 160
            [sender_name] => Ім'яВідправника
            [subject] => Тема листа для {{Ім'я}}!
            [body] => Привіт {{Ім'я}}! Це тест API!
            [alternate_body] => Привіт {{Ім'я}}! Це тест API!
            [images_place] => server
            [time_start] => 1436883244
            [type] => sended
            [date_create] => 2015-07-14 14:14:29
        )

    [1] => Array
        (
            [ID] => 826
            [fromID] => 160
            [sender_name] => Апі
            [subject] => Тема листа!
            [body] => Тест працює. Ура!
            [alternate_body] => Тест працює. Ура!
            [images_place] => server
            [time_start] => 1436883216
            [type] => sended
            [date_create] => 2015-07-14 14:14:28
        )
)

Отримати звіт email-розсилки

Виклик

getMailReport

Вхідні параметри

project_id	ID проекту, в якому необхідно отримати список email-розсилок
ID	ID email-розсилки

Результат повернення

Список email-розсилок у форматі:

total	загальна кількість листів
sended	кількість надісланих email-листів
delivered	кількість доставлених
opened	кількість відкритих листів
with_moving	кількість листів з переходами
moved	кількість переходів за посиланнями з листів
not_delivered	кількість недоставлених листів
unsubscribed	кількість підписників, які відписалися
unsubscribed_as_spam	кількість тих, хто поскаржився на СПАМ
fromID	ID зворотної адреси електронної пошти
sender_name	ім'я відправника
subject	тема листа (підтримує персоналізацію)
body	вміст листа (підтримує персоналізацію)
alternate_body	альтернативний текст листа без тегів, для text-plain відображення
images_place	місце зберігання малюнків
time_start	дата і час старту розсилки у форматі UNIXTIME
type	статус розсилки
date_create	дата створення розсилки

Приклад відповіді

				  
Array
(
    [total] => 2
    [sended] => 2
    [delivered] => 2
    [opened] => 1
    [with_moving] => 0
    [moved] => 0
    [not_delivered] => 0
    [unsubscribed] => 0
    [unsubscribed_as_spam] => 0
    [fromID] => 160
    [sender_name] => Тест
    [subject] => Привіт {{Ім'я}} - {{Номер телефона}} - {{Електронна адреса}}
    [body] => Тіло листа
    [alternate_body] =>
    [images_place] => server
    [time_start] => 1432044523
    [type] => sended
    [date_create] => 2015-05-19 14:13:17
}

Отримати список автовідповідачів для API

Виклик

getResponderList

Вхідні параметри

project_id	ID проєкту, в якому необхідно отримати список автовідповідачів, призначених для API

Результат повернення

Список email-розсилок у форматі:

ID	ID автовідповідача
mailID	ID листа для автовідповідача
time_type	тип часового інтервалу для спрацьовування автовідповідача
time_send	`Array ( [days] — кількість днів до старту автовідповідача; [time_hour] — кількість годин; [time_minutes] — кількість хвилин. )`

Приклад відповіді

				  
Array
(
    [0] => Array
        (
            [ID] => 19
            [mailID] => 819
            [time_type] => timeleft
            [time_send] => Array
                (
                    [days] => 0
                    [time_hour] => 0
                    [time_minutes] => 5
                )

        )

)

Надіслати Email-повідомлення підписникам

Виклик

sendMail

Вхідні параметри

project_id	ID проєкту, в якому необхідно отримати надіслати розсилку
subscribers	масив ID підписників, яким необхідно надіслати розсилку. Не більше 1000 підписників у списку. Якщо необхідно надіслати більшій кількості - необхідно використовувати фільтри або групи. Для того, щоб надіслати всім по базі - переданий параметр `$subscribers = "ALL"`;
subject	тема email-розсилки (підтримує персоналізацію)
message	зміст розсилки (підтримує персоналізацію)
sender_id	ID адреси зворотної електронної адреси відправника
sender_name	ім'я відправника
date	час старту розсилки у форматі UNIXTIME
filter_id	якщо вказано: відправлення за ID фільтром у системі
group_id	якщо вказано: відправлення за ID групи в системі

Наприклад

				
$subscribers = array();
$subscribers[] = 337361;
$subscribers[] = 438106;
$subject = "Тема листа для {{Ім'я}}!";
$message = "Привіт {{Ім'я}}! Це тест API!";
$sender_id = 160;
$sender_name = "Ім'я відправника";
$date = mktime();
$filter_id = 0;
$group_id = 0;
$res = $api->sendMail($project_ID = 96, $subscribers, $subject, $message, $sender_id, $sender_name, $date, $filter_id, $group_id);

Результат повернення

Масив:

ID	ID створеної email-розсилки

Приклад відповіді

				  
Array
(
    [ID] => 828
)