×

Получите 5 готовых email-стратегий для любого бизнеса БЕСПЛАТНО!

После регистрации

меню
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’. Также обратите внимание, что значение поля «phone» должно передаваться в международном формате (пример: +79261232323)
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-запросе допустимая длина запроса существенно меньше.