Метод subscribe

Этот метод добавляет контакты (email адрес и/или мобильный телефон) подписчика в один или несколько списков, а также позволяет добавить/поменять значения дополнительных полей и меток.

По умолчанию, на email подписчика отправляется письмо с просьбой подтвердить подписку, но если Вы уже проверили существование адреса самостоятельно, то можете отключить это с помощью установки параметра double_optin.

В зависимости от значения параметра double_optin подписчик либо получит статус «новый», либо ему будет отправлено письмо с просьбой подтвердить подписку и он получит статус «запрошено подтверждение», либо будет возвращено сообщение об ошибке (подробнее о статусах).

Если нужно проверить, есть ли подписчик в списке или аккаунте, - можете вызвать метод exportContacts, передав в параметре email адрес интересующего подписчика.

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

Принцип использования

Синтаксис и URL для вызова метода

subscribe (string list_ids, string array fields [string tags, 

int double_optin, int overwrite])

https://api.unisender.com/ru/api/subscribe?format=json&api_key=KEY&

list_ids=134,135&fields[email]=test@example.org&tags=MyTag1,

MyTag2&double_optin=0&overwrite=0

Аргументы
api_key * Ключ доступа к API
list_ids * Перечисленные через запятую коды списков, в которые надо добавить подписчика. Коды можно узнать с помощью метода getLists. Они совпадают с кодами, используемыми в форме подписки.

Примеры:

list_ids=123456
list_ids=123456,345678,2344423
fields * Ассоциативный массив дополнительных полей. Массив в запросе передаётся строкой вида
fields[NAME1]=VALUE1&fields[NAME2]=VALUE2
Обязательно должно присутствовать хотя бы поле «email» или «phone», иначе метод возвратит ошибку. В случае наличия и e-mail, и телефона, подписчик будет включён и в e-mail, и в SMS списки рассылки.

Примеры:

fields[email]=test@example.org
fields[email]=test@example.org&fields[Name]=UserName
tags Перечисленные через запятую метки, которые добавляются к подписчику.
double_optin Принимает значение 0, 3 или 4.
  • Если 0, то мы считаем, что подписчик только высказал желание подписаться, но ещё не подтвердил подписку. В этом случае подписчику будет отправлено письмо-приглашение подписаться. Текст письма будет взят из свойств первого списка из list_ids. Кстати, текст можно поменять с помощью метода updateOptInEmail или через веб-интерфейс.
  • Если 3, то также считается, что у Вас согласие подписчика уже есть, подписчик добавляется со статусом «новый».
  • Если 4, то система выполняет проверку на наличие подписчика в ваших списках. Если подписчик уже есть в ваших списках со статусом «новый» или «активен», то адрес просто будет добавлен в указанный вами список. Если же подписчик отсутствует в ваших списках или его статус отличен от «новый» или «активен», то ему будет отправлено письмо-приглашение подписаться. Текст этого письма можно настроить для каждого списка с помощью метода  updateOptInEmail или через веб-интерфейс. 
overwrite Режим перезаписывания полей и меток, число от 0 до 2 (по умолчанию 0). Задаёт, что делать в случае существования подписчика (подписчик определяется по email-адресу и/или телефону).

Если 0 — происходит только добавление новых полей и меток, уже существующие поля сохраняют своё значение.

Если 1 — все старые поля удаляются и заменяются новыми, все старые метки также удаляются и заменяются новыми.

Если 2 — заменяются значения переданных полей, если у существующего подписчика есть и другие поля, то они сохраняют своё значение. В случае передачи меток они перезаписываются, если же метки не передаются, то сохраняются старые значения меток.

Возвращаемое значение
Объект с единственным полем person_id – целым положительным десятичным 64-битным уникальным кодом подписчика.

Пример возвращаемого значения:

{"result":{"person_id":2500767342}}

Примеры формирования URL-запроса

https://api.unisender.com/ru/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]=test@example.org&fields[Name]=John+Doe

— добавить нового подписчика с именем John Doe и адресом test@example.org в список с кодом 555777. Сразу после добавления ему будет отправлен запрос-подтверждение, что он действительно согласен получать рассылку.

 

https://api.unisender.com/ru/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]=
test@example.org&fields[Name]=John+Doe&double_optin=
0&tags=RedRoseCustomer

— добавить нового подписчика с именем John Doe и адресом test@example.org в список с кодом 555777. Подписчику будет присвоена меткаRedRoseCustomer для дальнейших целей сегментации рассылок. Запрос-подтверждение отправлен не будет, адрес будет подписан автоматически.

Повторная подписка

Если вы добавляете email и телефон контакта, который уже есть в вашем кабинете, то могут возникнуть такие случаи:

  • при отправке запроса email указан тот же, а телефонный номер другой. Тогда телефон заменится на новый при условии, что он не принадлежит другому контакту у вас в кабинете; 
  • при отправке запроса телефонный номер указан тот же, а email другой. Тогда email заменится на новый при условии, что он не принадлежит другому контакту у вас в кабинете.
В противном случае вы получите ошибку такого вида:
{
 "error": "Contacts test@example.org and +77777777 already exist but owned
by different subscribers",
 "code": "unspecified",
 "result": [   
 ]
}

Примеры на PHP

Мы настоятельно рекомендуем использовать POST-запросы, так как это более безопасный метод передачи данных, нежели GET. Используйте SSL-соединение с UniSender. Подробнее о методах соединения здесь.

Пример с использованием POST-запроса
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxx";

// Данные о новом подписчике
$user_email = "new@aol.de";
$user_name = iconv('cp1251', 'utf-8', "Василий Иванович Чапаев");
$user_lists = "354168";
$user_tag = urlencode("Added using API");

// Создаём POST-запрос
$POST = array (
  'api_key' => $api_key,
  'list_ids' => $user_lists,
  'fields[email]' => $user_email,
  'fields[Name]' => $user_name,
  'tags' => $user_tag
);

// Устанавливаем соединение
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_URL, 
            'https://api.unisender.com/ru/api/subscribe?format=json');
$result = curl_exec($ch);

if ($result) {
  // Раскодируем ответ API-сервера
  $jsonObj = json_decode($result);

  if(null===$jsonObj) {
    // Ошибка в полученном ответе
    echo "Invalid JSON";

  }
  elseif(!empty($jsonObj->error)) {
    // Ошибка добавления пользователя
    echo "An error occured: " . $jsonObj->error . "(code: " . $jsonObj->code . ")";

  } else {
    // Новый пользователь успешно добавлен
    echo "Added. ID is " . $jsonObj->result->person_id;

  }
} else {
  // Ошибка соединения с API-сервером
  echo "API access error";
}

Пример с использованием GET-запроса
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxx";

// Данные о новом подписчике
// Если скрипт в кодировке UTF-8, то удалите вызов iconv
$user_email = "new@aol.com";
$user_name = urlencode(iconv('cp1251', 'utf-8', "Василий Иванович"));
$user_lists = "354168";
$user_tag = urlencode("Added using API");

// Создаём GET-запрос
$api_url = "https://api.unisender.com/ru/api/subscribe?format=json".
           "&api_key=$api_key&list_ids=$user_lists".
           "&fields[email]=$user_email&fields[Name]=$user_name".
           "&tags=$user_tag";

// Делаем запрос на API-сервер
$result = file_get_contents($api_url);

if ($result) {
  // Раскодируем ответ API-сервера
  $jsonObj = json_decode($result);

  if(null===$jsonObj) {
    // Ошибка в полученном ответе
    echo "Invalid JSON";

  }
  elseif(!empty($jsonObj->error)) {
    // Ошибка добавления пользователя
    echo "An error occured: " . $jsonObj->error . "(code: " . $jsonObj->code . ")";

  } else {
    // Новый пользователь успешно добавлен
    echo "Added. ID is " . $jsonObj->result->person_id;

  }

} else {
  // Ошибка соединения с API-сервером
  echo "API access error";
}