Метод createList

Метод для создания нового списка контактов.

Предполагается, что каждый список задаёт отдельную тематику рассылок. Подписчик может подписаться или отписатьcя от рассылки определённой тематики, поставив или убрав галочку напротив списка на странице управления подпиской, доступной по ссылке в письме. Поэтому неправильной практикой будет создание нового списка для каждой новой рассылки.

У каждого списка контактов в одном аккаунте UniSender должно быть уникальное имя. При попытке создания списка с повторяющимся именем будет возвращена ошибка. 

В случае необходимости изменения списка адресатов перед рассылкой рассмотрите возможность использования методов importContacts/exportContacts, либо указания конкретных адресов/телефонов в методе createCampaign.

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

Синтаксис и URL для вызова метода
createList (string title, [string before_subscribe_url, string after_subscribe_url])
https://api.unisender.com/ru/api/createList?format=json&api_key=KEY&title=NewListName

Аргументы
api_key * Ключ доступа к API
title * Название списка. Должно быть уникальным в вашем аккаунте.

Примеры:

      title=NewListTitle
title=%D0%9D%D0%BE%D0%B2%D1%8B%D0%B9
(«Новый» в кодировке UTF-8)
before_subscribe_url URL для редиректа на страницу "перед подпиской". Обычно на этой странице показывается сообщение, что подписчику надо перейти по ссылке подтверждения для активации подписки. В этот URL можно добавлять поля подстановки - например, вы можете идентифицировать подписчика по email-адресу, подставив сюда email - либо по коду подписчика в своей базе данных, сохраняя код в дополнительное поле и подставляя его в этот URL.

after_subscribe_url URL для редиректа на страницу "после подписки". Обычно на этой странице показывается сообщение, что подписка успешно активирована. В этот URL можно добавлять поля подстановки - например, вы можете идентифицировать подписчика по email-адресу, подставив сюда email - либо по коду подписчика в своей базе данных, сохраняя код в дополнительное поле и подставляя его в этот URL.

Возвращаемое значение

Объект с полем id (кодом списка). Этот id далее можно использовать в прочих методах, где требуется id списка контактов.

Пример успешного создания нового списка контактов:

{"result":{"id":353358}}

Пример ошибки:

{
  "error": "VM161103-01 [List \"Test List\" already exists]",
  "code": "invalid_arg"
}


Примеры на PHP

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

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

// Имя нового списка
$new_list_name = "Новый список контактов";

// Создаём POST-запрос
// Если файл скрипта в кодировке UTF-8, то удалите вызов iconv
$POST = array (
  'api_key' => $api_key,
  'title' => iconv('cp1251', 'utf-8', $new_list_name)
);

// Устанавливаем соединение
$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/createList?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 "New list successfully created. List id is " . $jsonObj->result->id;
  }
} else {
  // Ошибка соединения с API-сервером
  echo "API access error";
}
Пример с использованием GET-запроса
// Ваш ключ доступа к API (из Личного Кабинета)
$api_key = "xxxxxxxxxxxxxxxxxx";

// Имя нового списка
$new_list_name = urlencode(iconv('cp1251', 'utf-8', "Это новый список"));

// Если файл скрипта в кодировке UTF-8, то используйте такую строчку
// $new_list_name = rawurlencode("Это новый список");

// Создаём GET-запрос
$api_url = "https://api.unisender.com/ru/api/createList?format=json".
           "&api_key=$api_key&title=$new_list_name";

// Устанавливаем соединение
$handle = fopen($api_url, "r");

if ($handle) {
  $result = fgets($handle, 4096);
  fclose($handle);

  // Раскодируем ответ 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 "New list successfully created. List id is " . $jsonObj->result->id;
  }

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