Работа с Unisender через API

2017-07-08

Unisender - это инструмент для массовых рассылок и отправки одиночных писем.

В этой статье я опишу как работать с ним через API и некоторые "подводные камни", с которыми пришлось столкнуться.

Начало

Для начала необходимо получить ключ доступа к API. Для этого переходим в личный кабинет, находим вкладку "Интеграция API".

screenshot 2017 06 08 11 47 54

Поставить “тестовый” или “включен”. В тестовом режиме не будут отправляться письма.

Дальше необходимо скачать SDK для PHP отсюда: https://github.com/unisender-dev/php-api-wrapper

Скачиваем, подключаем в проект:

include_once ("UnisenderApi.php");

Пример:

use Unisender\ApiWrapper\UnisenderApi;
$UnisenderApi = new UnisenderApi('api key here', 'UTF-8', 4, null, false, $platform);
Или так:
$UnisenderApi = new \Unisender\ApiWrapper\UnisenderApi('api key here', 'UTF-8', 4, null, false, $platform);

Так как основная задача состоит в том, чтобы отправлять почту, первый метод будет sendEmail.

Простая отправка письма:

https://www.unisender.com/ru/support/integration/api/sendemail

Взять пример кода, подставить свои данные и попытаться отправить.

Для начала нужно создать список рассылки:

$result=$uni->createList(Array("title"=>"OurNewList"));
$list = json_decode($result);
var_dump($list);

В админке появляется новый список.

screenshot 2017 06 08 13 35 48

Далее, подготавливаем параметры и собираем в массив все данные письма.

// Параметры сообщения
$email_from_name = 'Unisender';
$email_from_email = 'sender[sobaka]example.com';
$email_to = 'user[sobaka]example.com';
$email_body = '<html><body>Test, привет.</body></html>';
$email_subject = 'test email';
$list_id = $lists_arr[0];
// Создаём POST-запрос
$request = [
'api_key' => $api_key,
 'email' => $email_to,
 'sender_name' => $email_from_name,
 'sender_email' => $email_from_email,
 'subject' => $email_subject,
 'body' => $email_body,
 'list_id' => $list_id,
];

Отправка письма может производиться только от подтвержденного ящика, иначе будет ошибка:

{"error":"unchecked sender email: test[sobaka]unisender.com";,"code":"invalid_arg","result":""}

Подтвердить почтовый ящик в интерфейсе Unisender:

screenshot 2017 06 08 14 05 07

На почту придет письмо со ссылкой на подтверждение. После этого подтвержденный ящик будет указываться как адрес отправителя.

screenshot 2017 06 08 14 43 17

Создание списка рассылки

Без id списка рассылки невозможно отправить письмо. Для любой отправки письма нужен список рассылки.

Можно список создать вручную но это не наш метод.

$unisender->createList(Новый список);
Теперь нужно получить id какого-то списка рассылки, например только что созданного.

Получение списков рассылки

Можно посмотреть в интерфейсе, а можно получить через API.

$unisender->getLists();
array (size=2)
 0 => 
 object(stdClass)[3]
 public 'id' => int 10217533
 public 'title' => string 'название списка рассылки'
 1 => 
 object(stdClass)[4]
 public 'id' => int 10218569
 public 'title' => string 'название списка рассылки 1'

Полученный массив разбираем, получаем ID.

Создание письма

Сначала нужно создать письмо методом createEmailMessage.

Методом createEmailMessage письма помещаются в очередь отправки.

screenshot 2017 06 09 10 56 28

Можно запустить рассылку вручную.

screenshot 2017 06 09 11 01 02

Но нужно это сделать программно. Для этого есть метод createCampaign.

Рассылка

Для начала рассылки нужно получить email_id от функции createEmailMessage.

Запланировать массовую рассылку нужно методом createCampaign.

Методу отдается id письма и письмо ставится в очередь отправки.

{"result":{"campaign_id":122081893,"status":"scheduled","count":0}}

В интерфейсе это выглядит так:

screenshot 2017 06 09 11 51 47

После отправки можно посмотреть статистику прочтения.

screenshot 2017 06 09 11 53 35

Отправка на несколько адресов будет заключаться в том, что в список рассылки нужно добавить список email адресов методом subscribe.

Добавление адресатов в рассылку

Отдаем методу id списка рассылки и массив с адресами.

Код можно взять со страницы описания метода, хотя я сделал так:

 public function subscribe($list,$addr)
{
$subscribe = [];
foreach ($addr as $address){
$POST = array (
'api_key' => $this->apiKey,
'list_ids' => $list,
'fields[email]' => $address['address'],
'fields[Name]' => $address['name'],
// 'request_ip' => $user_ip,
'tags' => urlencode("Added using API"),
'double_optin' => 3
);
$subscribe[] = json_decode($this->request($POST,__FUNCTION__));
unset($POST);
}
return $subscribe;
}

По умолчанию, на e-mail подписчика отправляется письмо с просьбой подтвердить подписку, но если Вы уже проверили существование адреса самостоятельно, то можете отключить это с помощью установки параметра double_optin=1 или 3, в зависимости от потребности.

Для того что бы контакт был просто добавлен без отправки письма (подтвердить рассылку) необходимо использовать параметр double_optin=3

$list - это id списка рассылки (строка), а массив с адресами выглядит так:

['name' => 'Helga Kreutz','address' => 'Этот адрес электронной почты защищен от спам-ботов. У вас должен быть включен JavaScript для просмотра. ';],

В процессе я столкнулся с такой ошибкой:

object(stdClass)[2]

public 'error' => string 'SZ141008-01 [Subscription error: reply address for invitation messages not set in list '10217533']' (length=98)
public 'code' => string 'unspecified' (length=11)
public 'result' => string '' (length=0)

Здесь написано, что нужно зайти в настройки аккаунта и включить API если еще не включено (хотя странная рекомендация, без API вся предыдущая трахомудия не работала бы), зайти в необходимый список, кликнуть по ссылке “инструменты подписки и отписки” ...

screenshot 2017 06 09 14 29 30

… и указать необходимые данные.

screenshot 2017 06 09 14 31 26

Пришел такой ответ:

object(stdClass)[2]
public 'result' =>
object(stdClass)[5]
public 'person_id' => float 16392094873

Значит все в порядке.

Отправка одиночных писем

Для этого есть метод sendEmail.

$sendEmail = $uni->sendEmail($name,$email,$to,$subject,$body,$list_id);

В ответе метода должен присутствовать id письма и/или ошибка.

{"result":{"email_id":"11315194697"}}

Если отправка неуспешная:

{"result":{"email_id":"11315194697","errors":[{"code":"has_been_sent","message":"Email РґР°РЅРЅРѕРјСѓ Р°РґСЂРµСЃР°С‚Сѓ СѓР¶Рµ Р±С‹Р» РѕС‚РїСЂР°РІР»РµРЅ","accept_date":"2017-06-08 13:59:17"}]
}}

В данном случае письмо не отправилось, т.к. было отправлено ранее.

Проверка отправки

Можно проверить статус письма при помощи метода checkEmail()

Когда я использовал этот метод из класса, у меня выдавало ошибку.

Если все хорошо, возвращает:

:string 'ok_delivered' (length=12)

Сервисы

Непосильная помощь

Чтобы Ктулху не воскрес, подпишись на RSS