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

Метод 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 и именами Anna, Kate, John, Mike и 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";
}