Метод importContacts

Метод массового импорта подписчиков. Может использоваться также для периодической синхронизации с базой подписчиков, хранящейся на вашем собственном сервере (см. также описание метода exportContacts). Импортировать можно данные не более 500 подписчиков за вызов. Списки большего размера надо импортировать за несколько вызовов (данное ограничение связано с ограничениями POST-запроса).

Если среди подписываемых e-mail адресов есть новые, то по умолчанию они получают статус "новый".

Технические ограничения: максимальное количество пользовательских полей равно 50. Таймаут на один вызов составляет 30 секунд с момента полной передачи запроса на сервер. Если по истечении таймаута ответ не получен, то рекомендуется сделать до двух повторных попыток, и если ответа снова нет, тогда обращаться в техническую поддержку.

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

Синтаксис и URL для вызова метода
importContacts (string array field_names, string array data [bool overwrite_tags, bool overwrite_lists])
https://api.unisender.com/ru/api/importContacts?format=json&api_key=KEY&field_names[0]=email ... field_names[N]=MyFieldN&data[0][0]=test@example.org.... &data[N][0]=test2@example.org&overwrite_tags=X&overwrite_lists=X

Аргументы
api_key * Ключ доступа к API
field_names * Массив названий столбцов данных. Обязательно должно присутствовать хотя бы поле "email" или "phone", иначе метод вернет ошибку. Могут быть указаны названия существующих пользовательских полей и названия следующих системных полей:

Особые значения параметра field_names
delete Если поле с этим названием содержит 1, то указанные подписчики списка удаляются.
tags Через запятую можно указать метки, присваемые подписчику.
email Адрес электронной почты подписчика
email_status Статус email, один из: 'new' (новый), 'active' (активный), 'inactive'(временно отключённый), 'unsubscribed' (отписался от всех настоящих и будущих рассылок). Если статус не указан, то для новых адресов подразумевается 'new'. Для уже существующих адресов с текущим статусом, не совпадающим с 'active' или 'inactive', значение статуса поменять нельзя.
email_availability Доступность адреса. Смотри описание поля email_availability в методе exportContacts.
email_add_time Дата и время добавления адреса/запроса подписки в формате "ГГГГ-ММ-ДД" или "ГГГГ-ММ-ДД чч:мм:сс" по Гринвичу (UTC).
email_request_ip Можно указать IP-адрес в формате "NNN.NNN.NNN.NNN", с которого поступил запрос о подписке. Необязателен, но без указания действуют более строгие ограничения на количество подписчиков в сутки. IP-адреса из "внутренних" подсетей не засчитываются.
email_confirm_time Дата и время подтверждения подписки в формате "ГГГГ-ММ-ДД" или "ГГГГ-ММ-ДД чч:мм:сс" по Гринвичу (UTC).
email_list_ids Перечисленные через запятую коды списков, на которые будет подписан email-адрес.
email_subscribe_times Перечисленные через запятую дата и время подписки, количество и порядок дат должен соответствовать количеству и порядку кодов списков в email_list_ids. Даты указаны в UTC, в формате "ГГГГ-ММ-ДД чч:мм:сс" или "ГГГГ-ММ-ДД".
email_unsubscribed_list_ids Перечисленные через запятую коды списков, в которые email входит, но от которых подписчик отписался. Может показаться, что это поле избыточно, ведь можно просто в поле email_status указать unsubscribed. Но если у вас несколько списков, подписчик может быть отписанным, например, только от одного, и тогда только этот список указывается в email_unsubscribed_list_ids, а остальные - в email_list_ids. Поле же email_status относится к адресу в целом и может быть при этом равно 'active'.
email_excluded_list_ids Перечисленные через запятую коды списков, в которые email входит, но из которых подписчик будет исключен.
phone, phone_status, phone_availability, phone_add_time, phone_request_ip, phone_list_ids, phone_subscribe_times, phone_unsubscribed_list_ids, phone_excluded_list_ids Смысл полей совпадает с аналогичными полями для email. Обратите внимание, что для телефонов отсутствуют поля phone_confirm_ip и phone_confirm_time. Ещё одно отличие — по умолчанию для новых телефонов phone_status устанавливается в 'active'.
data *

Массив данных подписчиков, каждый элемент которого — массив полей в том порядке, в котором следуют field_names.

Пример для двух подписчиков (у первого email входит в список 123, второй оказывается вне списков):

field_names[0]=email&field_names[1]=email_list_ids&
data[0][0]=a@example.com&data[0][1]=123&data[1][0]=b@example.org
overwrite_tags

Необязательное логическое поле (0 или 1, по умолчанию 0). Перезаписываются ли метки (если 1), или только добавляются новые, не удаляя старых (если 0).

overwrite_lists

Необязательное логическое поле (0 или 1, по умолчанию 0).

Единица означает — заменить на новые все данные о том, когда и в какие списки включены и от каких отписаны подписчики. Т.е. если подписчик сейчас включён в три списка, а в email_list_ids будет указан только один, то после вызова подписчик будет включён только в один указанный, и время подписки будет то, которое указано в email_subscribe_times (либо текущее, если поле email_subscribe_times пропущено).

Возвращаемое значение
JSON-объект со следующими полями:
total Целое десятичное неотрицательное число — общее количество подписчиков во входном массиве data. Сумма inserted+updated+deleted может оказаться меньше, чем total, если были ошибки или дубликаты.
inserted Целое десятичное неотрицательное число — количество успешно добавленных подписчиков, ни один из контактов которых ранее не встречался.
updated Целое десятичное неотрицательное число — количество обновлённых данных подписчиков (e-mail или телефон уже был в базе).
deleted Целое десятичное неотрицательное число — количество успешно удалённых подписчиков как новых, так и уже существующих, а также успешно удалённых.
new_emails Целое десятичное неотрицательное число, меньшее или равное total. Сколько среди импортированных e-mail адресов получили статус 'new'. Причём в это число входят и существовавшие ранее адреса, статус которых был 'new'.
invalid Целое десятичное неотрицательное число, больше или равное нулю. Сколько среди e-mail адресов не было импортировано.
log Массив ошибок и предупреждений импорта, каждый элемент — объект со следующими свойствами: 

Поля параметра log
index Целое десятичное неотрицательное число — номер подписчика в массиве data.
code Код ошибки или предупреждения
message Сообщение об ошибке/предупреждении.
Пример возвращаемого значения:

{
  "result":{
    "total":4, "inserted":2, "updated":1, "deleted":2, "new_emails":1, "invalid":2,
    "log":[
      {"index":0,"code":"e_email_invalid", 
       "message":"Неправильный формат e-mail"},
      {"index":2,"code":"e_phone_not_unique", 
       "message":"Повторно встретившийся телефон"}
    ]
  }
}

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

{
  "result":{
    "total":1, "inserted":1, "updated":0, "deleted":0, "new_emails":1, "invalid":0,
    "log":[
      {"index":0,"code":"w_common_overlimit", 
       "message":"Превышен лимит количества контактов для текущего тарифного плана (но строка добавлена)"
}
]
},
"warnings":[
{
"warning":"Addresses overlimit for current period"
}
]
}

 

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

https://api.unisender.com/ru/api/importContacts?format=json&api_key=KEY&
field_names[0]=email&field_names[1]=Name&field_names[2]=email_list_ids&
data[0][0]=1@example.com&data[0][1]=Anna&data[0][2]=778899&
data[1][0]=2@example.com&data[1][1]=Kate&data[1][2]=778899&
data[2][0]=3@example.com&data[2][1]=John&data[2][2]=778899&
data[3][0]=4@example.com&data[3][1]=Mike&data[3][2]=778899&
data[4][0]=5@example.com&data[4][1]=Bill&data[4][2]=778899


— добавить 5 новых подписчиков с адресами 1 .. 5@example.org и именами AnnaKateJohnMike и Bill в список с кодом 778899. Стоит заметить, что запросы правильнее делать через POST, так как в GET-запросе допустимая длина запроса существенно меньше.

Пример на PHP

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

Более того, так как в данном методе возможная передача больших массивов данных, то метод GET будет категорически неприемлем из-за своего небольшого лимита на длину запроса.

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

// Новые подписчики
$new_emails = array ('1@example.org', '2@example.org', '3@example.org',
                     '4@example.org', '5@example.org');
$new_names = array ('Аня', 'Женя', 'Лев', 'Иван', 'Ира');

// Список, куда их добавить
$list = "234234";

// Создаём POST-запрос
$POST = array (
  'api_key' => $api_key,
  'field_names[0]' => 'email',
  'field_names[1]' => 'Name',
  'field_names[21]' => 'email_list_ids'
);
for ($i=0;$i<5;$i++){
  $POST['data[' . $i .'][0]'] = $new_emails[$i];
  $POST['data[' . $i .'][1]'] = iconv('cp1251', 'utf-8', $new_names[$i]);
  $POST['data[' . $i .'][2]'] = $list;
}

// Устанавливаем соединение
$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/importContacts?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 "Success! Added " . $jsonObj->result->new_emails . " new e-mail addresses";

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