Sendios SDK

Sendios SDK

Якщо ви використовуєте PHP, ви можете підключити нашу бібліотеку.

🚧

Наразі доступна лише PHP SDK, iншi мови програмування не підтримуються.

Для встановлення скористайтеся:

composer require sendios/php-sdk

Для авторизації:

$clientId = 123;
$clientToken = 'a1s2d3f4g5h6j7k8l';
$sendios = new \Sendios\SendiosSdk($clientId, $clientToken);

Send email

Для відправки системних та тригерних листів:

$email = '[email protected]'; // for matching or creating user

$projectId = 1; // sendios 
$typeId = 1; // mail type id
$categoryId = $sendios->push->getCategorySystem(); // system or trigger

$letterData = [
    'some' => 'hi',
    'letter' => 'John',
    'variables' => '!',
];

$sendios->push->send($typeId, $categoryId, $projectId, $email, [], $letterData, []);


# response: {"queued":true}

Також є можливість додати метадані для трекінгу:

// Your data, that will be sent with our webhooks
$meta = [
    'tracking_id' => 72348234,
];

Check email

Щоб валідувати пошту користувача:

$result = $sendios->email->check('[email protected]');

Provide the user with an ID on your product

Щоб надати користувачеві ідентифікатор, який використовується на вашому продукті, або, як ми його називаємо, client_user_id, використовуйте:

$email = '[email protected]';
$projectId = 1;
$clientUserId = 1234;

$sendios->clientUser->create($email, $projectId, $clientUserId);

Add and update user data (custom user fields)

За допомогою цього запиту ви можете передати інформацію, унікальну для вашого продукту, додати або оновити дані користувача:

$fields = [
    'name' => 'John Dou',
    'gender' => 'm', // m or f
    'age' => 21, // int
    'photo' => 'http://moheban-ahlebeit.com/images/Face-Wallpaper/Face-Wallpaper-26.jpg',//image url
    'ak' => 'FFZxYfCfGgNDvmZRqnELYqU7',//Auth key
    'vip' => 1, //int
    'language' => 'es', //ISO 639-1
    'country' => 'esp', //ISO 3166-1 alpha-3 or ISO 3166-1 alpha-2
    'platform_id' => $sendios->user->getPlatformDesktop(),
    'list_id' => 1,
    'status' => 0, //int
    'partner_id' => 1, //int

    // Your own custom fields may be here
    // allowed only int values
    'custom_field' => 542, //int
    'sessions_count' => 22, //int
    'session_last' => 1498137772, //unix timestamp
];

За ідентифікатором користувача (user_id):

$user = $sendios->user->getById(892396028);
$result = $sendios->user->setUserFieldsByUser($user, $fields);
// $result is a boolean status

За електронною поштою користувача та ідентифікатором Проєкту (email, project_id):

$result = $sendios->user->setUserFieldsByEmailAndProjectId('[email protected]', 2, $fields);
// $result is a boolean status

Get user custom fields

Щоб отримати загальну або додаткову інформацію про вашого користувача:

// by user_id
$result = $sendios->user->getUserFieldsByEmailAndProjectId('[email protected]', 1);

// or

// by email and project_id
$result = $sendios->user->getUserFieldsByUser($user);

/*
Returns [
    'user' => [
        'id' => 892396028,
        'project_id' => 1,
         ...
    ],
    'custom_fields' => [
        'sessions_count' => 22,
         ...
    ],
]
*

Erase user

Щоб додати користувача до черги на видалення:

$email = '[email protected]';
$projectId = 1;
$result = $sendios->user->erase($email, $projectId);

Користувача буде видалено через 24 години.

Unsubscribe

Для відписки на сторінці налаштувань у вашому продукті використовуйте метод addBySettings:

$projectId = 1;
$user = $sendios->user->getByEmail('[email protected]', $projectId);
$unsub = $sendios->unsub->addBySettings($user);

Щоб здійснити відписку у вашій адмін-панелі, використовуйте метод addByClient:

$projectId = 1;
$user = $sendios->user->getByEmail('[email protected]', $projectId);
$unsub = $sendios->unsub->addByClient($user);

Unsubscribe by admin

$projectId = 123;
$result = $sendios->unsub->unsubByAdmin('[email protected]',$projectId);

/*
success result
array(1) {
  'unsub' => bool(true)
}
error result (already unsubscribed)
array(1) {
  'unsub' => bool(false)
}
*/

Subscribe back

Щоб поновити повну підписку:

$projectId = 1;
$user = $sendios->user->getByEmail('[email protected]', $projectId);
// Make DELETE to /unsub/USER_ID
$unsub = $sendios->unsub->subscribe($user);

Check is unsubscribed

Щоб перевірити наявність відписки у користувача.

За ідентифікатором користувача (user_id):

$projectId = 1;
$user = $sendios->user->getByEmail('[email protected]', $projectId);
if($user) {
$unsub = $sendios->unsub->isUnsubByUser($user); // Returns false(if not unsubscribed) or unsub data
}

За електронною поштою користувача та ідентифікатором проєкту (email, project_id):

$projectId = 1;
$unsub = $sendios->unsub->isUnsubByEmailAndProjectId('[email protected]', $projectId); // Returns false(if not unsubscribed) or unsub data

У разі позитивної відповіді, ви отримаєте інформацію про відписки.

Get unsubscribe reason

Щоб дізнатись причину відписки:

$projectId = 123;
$result = $sendios->unsub->getUnsubscribeReason('[email protected]',$projectId);

//user does not unsubscribed
array(1) {
  'result' => bool(false)
}

//reason for the unsubscription is unknown
array(1) {
  'result' => string(7) "Unknown"
}

//success result
array(1) {
  'result' => string(5) "admin"
}

Загалом, бувають такі причини відписки:

  • Settings_all_types – користувач відписався від розсилки у налаштуваннях продукту;
  • fbl – користувач поскаржився на розсилку в поштовику;
  • admin – користувача відписали через адмін-панель;
  • client – користувача було відписано у вашій системі або його обліковий запис було видалено з продукту;
  • header – користувач відписався від розсилки через поштовик із використанням заголовка листа;
  • invalid – користувача відписано через невалідність його електронної адреси;
  • Settings_oneclick – користувач здійснив повну відписку в одне натискання через лист;
  • page – користувача відписано через сторінку Sendios;
  • mx_invalid – користувача було відписано через невалідний поштовий домен;
  • distance_bounce – користувача було відписаний через те, що його електронної адреси не існує.

Get unsubscribed list

Повертає список відписаних користувачів станом на вказану дату:

$result = $sendios->unsub->getByDate('2018-06-10');

//Response example
return [
    0 => [
        'email' => "[email protected]",
        'project_id' => 9,
        'client_user_id' => NULL,
        'source_id' => 9,
        'created_at' => "2018-02-27 20:31:45"
    ],
    // ...
];

Для отримання списку користувачів посторінково:

$date = '2018-06-10'; // required
$page = 1; // required
$pageSize = 100; // optional
$result = $sendios->unsub->getListByDate($date, $page, $pageSize);

//Response example
return [
    [
        'pages' => 6,
        'current_page' => 1,
        'size' => 100,
        'data' => [
            'email' => "[email protected]",
            'project_id' => 9,
            'client_user_id' => NULL,
            'source_id' => 9,
            'created_at' => "2018-02-27 20:31:45"
        ],
        //...
    ]
];

Unsubscribe users from email types

Для того, щоб відписати користувача від конкретного типу листа:

$sendios->unsubTypes->addTypes($user, [4, 5]);

Subscribe users back to email types

Щоб поновити підписку на конкретний тип листа:

$sendios->unsubTypes->removeTypes($user, [4, 5]);

Для поновлення підписки на всі типи листів:

$sendios->unsubTypes->removeAll($user);

Get current unsubscribes

Щоб отримати список типів листів, від яких відписано користувача:

$projectId = 1;
$user = $sendios->user->getByEmail('[email protected]', $projectId);
$list = $sendios->unsubTypes->getList($user);

//returns array {
//  [0] =>
//  array(3) {
//    'type_id' =>
//   int(3)
//    'unsubscribed' =>
//    bool(false)
//    'name' =>
//    string(11) "Popular now"
//  },
//  ...
//}

Online status

Щоб оновити online-статус користувача за його ідентифікатором:

$sendios->user->setOnlineByUser($user, new \DateTime());

Щоб оновити online-статус користувача за його електронною адресою:

$sendios->user->setOnlineByEmailAndProjectId('[email protected]', 1, new \DateTime());

Payments

Для передачі інформації щодо платежів користувача:

$startDate = 1509617696; //Payment date or subscription start date 
$expireDate = 1609617696; //Subscription end date (optional, default false)
$paymentCount = 14; //Pay count (optional, default false)
$paymentType = 1; //Pay type (optional, default false)
$amount = 20; //Pay amount (optional, default false)
$mailId = 12244; //Mail id (optional, default false)

За ідентифікатором користувача (user_id):

$user = $sendios->user->getById(892396028);
$result = $sendios->user->createPaymentByUser($user, $startDate, $expireDate, $paymentType, $amount, $mailId);
// $result is a boolean status

За електронною поштою користувача та ідентифікатором проєкту (email, project_id):

$result = $sendios->user->cratePaymentByEmailAndProjectId('[email protected]', 2, $startDate, $expireDate, $paymentType, $amount, $mailId);
// $result is a boolean status

Handle an error

За замовчуванням усі повідомлення про помилки (крім InvalidArgumentException у конструкторі Sendios) збираються в error_log. Якщо ви бажаєте, щоб компонент видавав винятки, просто змініть режим обробника:

$sendios = new Sendios($clientId, $clientHash);
$sendios->errorHandler->setErrorMode(SendiosErrorHandler::MODE_EXCEPTION);

Set curl options for а single request

$sendios = new Sendios($clientId, $clientHash);
$sendios->request->setOption(CURLOPT_TIMEOUT, 2);

Reset permanent curl options

$sendios->request->resetPermanentOptions();

Set curl options for multiple requests (permanent)

$sendios->request->setOption(CURLOPT_TIMEOUT_MS, 2000, true);

Get а response

(if $result === false)

$response = $sendios->request->getLastResponse()->getData();

//array(3) {
//  'errorCode' =>
//  int(409)
//  'message' =>
//  string(16) "Validation error"
//  'errors' =>
//  array(1) {
//    'field_name' =>
//    string(29) "Can't find user field: field2"
//  }
//}