Метод subscribe

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

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

Подробнее про Double Opt-In

В зависимости от значения параметра 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.

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

Если 0 — происходит только добавление новых полей и меток, уже существующие поля сохраняют своё значение.
Если 1 — все старые поля удаляются и заменяются новыми, все старые метки также удаляются и заменяются новыми. Контакт будет удален со всех списков, кроме переданных в параметре list_ids.
Если 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]=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": [   
  ]
}

Вы нашли ответ?

43
68