Метод массового импорта контактов. Может использоваться также для периодической синхронизации с базой контактов, хранящейся на вашем собственном сервере (см. также описание метода exportContacts). Импортировать можно данные не более 500 контактов за вызов. Списки большего размера надо импортировать за несколько вызовов (данное ограничение связано с ограничениями POST-запроса).
Если среди подписываемых e-mail адресов есть новые, то по умолчанию они получают статус "новый".
Технические ограничения: максимальное количество пользовательских полей равно 50. Таймаут на один вызов составляет 30 секунд с момента полной передачи запроса на сервер. Если по истечении таймаута ответ не получен, то рекомендуется сделать до двух повторных попыток, и если ответа снова нет, тогда обращаться в техническую поддержку.
При импорте контактов через importContacts система проводит проверку на наличие спам-ловушек, технических и ролевых адресов при импорте.
Например, потенциально опасным будут считаться адреса типа info@, sales@, no-reply@ или all@. Они негативно влияют на доставляемость писем и репутацию отправителя, потому что не принадлежат конкретным подписчикам, что увеличивает вероятность отказов в доставке и жалоб на спам.
Потенциально опасные адреса будут исключены из импорта. Взаимодействовать с такими контактами необходимо через Double Opt-In.
Принцип использования
| Синтаксис и 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"
}
]
}
Если при импорте будут обнаружены технические или ролевые адреса, будет возвращаться следующий ответ: {
"result":{
"total":1, "inserted":0, "updated":0, "deleted":0, "new_emails":0, "invalid":1,"role_based": 1,
"log":[
{"index":0,"code":"w_common_overlimit",
"message":"Error (email was ignored). Role-based or technical email address: \"info@example.ru\""
}
]
}
}
|
|||||||||
Примеры формирования 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-запросе допустимая длина запроса существенно меньше.
