Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

Метод 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";
}