Этот метод добавляет контакты (email адрес и/или мобильный телефон) контакта в один или несколько списков, а также позволяет добавить/поменять значения дополнительных полей и меток.
По умолчанию, на email контакта отправляется письмо с просьбой подтвердить подписку, но если вы уже проверили существование адреса самостоятельно, то можете отключить это с помощью установки параметра double_optin.
В зависимости от значения параметра double_optin контакт либо получит статус «новый», либо ему будет отправлено письмо с просьбой подтвердить подписку и он получит статус «запрошено подтверждение», либо будет возвращено сообщение об ошибке (подробнее о статусах).
Если нужно проверить, есть ли контакт в списке или аккаунте, - можете вызвать метод exportContacts, передав в параметре email адрес интересующего контакта.
Для того, чтобы контакт был просто добавлен без отправки письма необходимо использовать параметр double_optin=3
Для данного метода существует лимит на количество запросов от одного API-ключа или IP-адреса — 300 запросов/60 секунд.
Принцип использования
| Синтаксис и URL для вызова метода |
| subscribe (string list_ids, string array fields [string tags, int double_optin, int overwrite]) |
| https://api.unisender.com/ru/api/subscribe?format=json&api_key=KEY& list_ids=134,135&fields[email]=test@example.org&tags=MyTag1, MyTag2&double_optin=0&overwrite=0 |
| Аргументы | |
| api_key * | Ключ доступа к API |
| list_ids * | Перечисленные через запятую коды списков, в которые надо добавить контакта. Коды можно узнать с помощью метода getLists. Они совпадают с кодами, используемыми в форме подписки.
Примеры: list_ids=123456 list_ids=123456,345678,2344423 |
| fields * |
Ассоциативный массив дополнительных полей. Массив в запросе передаётся строкой вида fields[NAME1]=VALUE1&fields[NAME2]=VALUE2 Обязательно должно присутствовать поле «email», иначе метод возвратит ошибку. В случае наличия и email, и телефона, контакт будет включён и в email, и в SMS списки рассылки. Обратите внимание, что значение поля «phone» должно передаваться в международном формате (пример: +79261232323). Примеры: fields[email]=test@example.org fields[email]=test@example.org&fields[Name]=UserName |
| tags | Перечисленные через запятую метки, которые добавляются к контакту. Максимально допустимое количество - 10 меток. |
| double_optin | Принимает значение 0, 3 или 4.
|
| overwrite | Режим перезаписывания полей и меток, число от 0 до 2 (по умолчанию 0). Задаёт, что делать в случае существования контакта (контакт определяется по email-адресу).
Если 0 — происходит только добавление новых полей и меток, уже существующие поля сохраняют своё значение. |
| Возвращаемое значение |
| Объект с единственным полем person_id – целым положительным десятичным 64-битным уникальным кодом контакта.
Пример возвращаемого значения: {"result":{"person_id":2500767342}}
|
Примеры формирования URL-запроса
https://api.unisender.com/ru/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]=test@example.org&fields[Name]=Ivan+Ivanov
— добавить нового контакта с именем Ivan Ivanov и адресом test@example.org в список с кодом 555777. Сразу после добавления ему будет отправлен запрос-подтверждение, что он действительно согласен получать рассылку.
https://api.unisender.com/ru/api/subscribe?format=json&api_key=KEY&list_ids=555777&fields[email]= test@example.org&fields[Name]=Ivan+Ivanov&double_optin=3&tags=RusMag
— добавить нового контакта с именем Ivan Ivanov и адресом test@example.org в список с кодом 555777. Контакту будет присвоена метка RusMag для дальнейших целей сегментации рассылок. Запрос-подтверждение отправлен не будет, адрес будет подписан автоматически.
Повторная подписка
Если вы добавляете email и телефон контакта, который уже есть в вашем кабинете, то могут возникнуть такие случаи:
- при отправке запроса email указан тот же, а телефонный номер другой. Тогда телефон заменится на новый при условии, что он не принадлежит другому контакту у вас в кабинете;
- при отправке запроса телефонный номер указан тот же, а email другой. Тогда email заменится на новый при условии, что он не принадлежит другому контакту у вас в кабинете.
В противном случае вы получите ошибку такого вида:
{
"error": "Contacts test@example.org and +77777777 already exist but owned
by different subscribers",
"code": "unspecified",
"result": [
]
}
