×

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

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

меню
Generic selectors
Exact matches only
Search in title
Search in content
Search in posts
Search in pages

Метод subscribe

Этот метод добавляет контакты (email адрес и/или мобильный телефон) контакта в один или несколько списков, а также позволяет добавить/поменять значения дополнительных полей и меток.

По умолчанию, на email контакта отправляется письмо с просьбой подтвердить подписку, но если Вы уже проверили существование адреса самостоятельно, то можете отключить это с помощью установки параметра double_optin.

В зависимости от значения параметра double_optin контакт либо получит статус «новый», либо ему будет отправлено письмо с просьбой подтвердить подписку и он получит статус «запрошено подтверждение», либо будет возвращено сообщение об ошибке (подробнее о статусах).

Если нужно проверить, есть ли контакт в списке или аккаунте, — можете вызвать метод exportContacts, передав в параметре email адрес интересующего контакта.

Для того, чтобы контакт был просто добавлен без отправки письма необходимо использовать параметр double_optin=3

Принцип использования

Синтаксис и 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» или «phone», иначе метод возвратит ошибку. В случае наличия и e-mail, и телефона, контакт будет включён и в e-mail, и в SMS списки рассылки. Обратите внимание, что значение поля «phone» должно передаваться в международном формате (пример: +79261232323).

Примеры:

fields[email]=test@example.org fields[email]=test@example.org&fields[Name]=UserName
tagsПеречисленные через запятую метки, которые добавляются к контакту.
double_optinПринимает значение 0, 3 или 4.

  • Если 0, то мы считаем, что контакт только высказал желание подписаться, но ещё не подтвердил подписку. В этом случае контакту будет отправлено письмо-приглашение подписаться. Текст письма будет взят из свойств первого списка из list_ids. Кстати, текст можно поменять с помощью метода updateOptInEmail или через веб-интерфейс.
  • Если 3, то также считается, что у Вас согласие контакта уже есть, контакт добавляется со статусом «новый».
  • Если 4, то система выполняет проверку на наличие контакта в ваших списках. Если контакт уже есть в ваших списках со статусом «новый» или «активен», то адрес просто будет добавлен в указанный вами список. Если же контакт отсутствует в ваших списках или его статус отличен от «новый» или «активен», то ему будет отправлено письмо-приглашение подписаться. Текст этого письма можно настроить для каждого списка с помощью метода  updateOptInEmail или через веб-интерфейс.
overwriteРежим перезаписывания полей и меток, число от 0 до 2 (по умолчанию 0). Задаёт, что делать в случае существования контакта (контакт определяется по email-адресу и/или телефону).

Если 0 — происходит только добавление новых полей и меток, уже существующие поля сохраняют своё значение.
Если 1 — все старые поля удаляются и заменяются новыми, все старые метки также удаляются и заменяются новыми.
Если 2 — заменяются значения переданных полей, если у существующего контакта есть и другие поля, то они сохраняют своё значение. В случае передачи меток они перезаписываются, если же метки не передаются, то сохраняются старые значения меток.

Возвращаемое значение
Объект с единственным полем 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]=John+Doe

— добавить нового контакта с именем John Doe и адресом 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]=John+Doe&double_optin=0&tags=RedRoseCustomer

— добавить нового контакта с именем John Doe и адресом test@example.org в список с кодом 555777. Контакту будет присвоена меткаRedRoseCustomer для дальнейших целей сегментации рассылок. Запрос-подтверждение отправлен не будет, адрес будет подписан автоматически.

Повторная подписка

Если вы добавляете email и телефон контакта, который уже есть в вашем кабинете, то могут возникнуть такие случаи:

  • при отправке запроса email указан тот же, а телефонный номер другой. Тогда телефон заменится на новый при условии, что он не принадлежит другому контакту у вас в кабинете;
  • при отправке запроса телефонный номер указан тот же, а email другой. Тогда email заменится на новый при условии, что он не принадлежит другому контакту у вас в кабинете.

В противном случае вы получите ошибку такого вида:

{
  "error": "Contacts test@example.org and +77777777 already exist but owned 
by different subscribers",
  "code": "unspecified",
  "result": [   
  ]
}