Метод массового импорта контактов. Может использоваться также для периодической синхронизации с базой контактов, хранящейся на вашем собственном сервере (см. также описание метода 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», иначе метод вернет ошибку. Могут быть указаны названия существующих пользовательских полей и названия следующих системных полей:
|
||||||||||||||||||||||
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 | Массив ошибок и предупреждений импорта, каждый элемент — объект со следующими свойствами:
|
||||||||
Пример возвращаемого значения:
{ "result":{ "total":4, "inserted":2, "updated":1, "deleted":2, "new_emails":1, "invalid":2, "log":[ {"index":0,"code":"e_email_invalid", "message":"Неправильный формат e-mail"}, ] } } Если при импорте превышается лимит на количество контактов в рамках текущего тарифного плана, будет возвращаться ответ с предупреждением: {
"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-запросе допустимая длина запроса существенно меньше.