Sendios SDK

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

🚧

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

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

composer require sendios/php-sdk

Для авторизації використовуйте:

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

Sending 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]');

Providing user 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

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

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

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

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

  • settings_all_types - користувач відписався від розсилки в налаштуваннях продукту;
  • fbl – користувач поскаржився на розсилку в поштовику;
  • admin - користувача відписали через адмін панель;
  • client - користувач відписаний у вашій системі (або його обліковий запис було видалено з продукту);
  • header - користувач відписався від розсилки через поштовик з використанням заголовка листа;
  • invalid - не валідна електронна адреса,
  • settings_oneclick - повна відписка користувача з листа в один клік,
  • page - відписка користувача через сторінку Sendios,
  • mx_invalid - користувач відписаний через не валідний поштовий домен,
  • distance_bounce - користувач відписаний через неіснуючу електронну адресу.
$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"
}

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 user from types

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

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

Subscribe user back to 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 статусу користувача за його email адресою

$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

Error handling

За замовчуванням усі повідомлення про помилки (крім 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"
//  }
//}