/v2/Api/Subscribers POST
Используя метод HTTP-POST, можно добавить подписчика в лист. Если подписчик, которого Вы хотите добавить, уже существует (подписчики идентифицируются по емейлу), то он будет обновлен.
Можно добавить одного или нескольких подписчиков с помощью одного запроса.
Максимальное количество передаваемых подписчиков для одного API запроса 100.
Формат данных запроса
Элементы тега ApiRequest
Элемент/Атрибут | Тип | Описание |
---|---|---|
ApiKey | string | Ваш API-ключ. Обязательный. |
ReturnData | bool | Если установлен в «true» (только в нижнем регистре!), то будет возвращена дополнительная информация. Полезно для использования с MultiData. |
VerboseErrors | bool | Если установлен в «true» (только в нижнем регистре!), то будет возвращена расширенная информация об ошибках. См. примеры. |
Data | complex | Объект, содержащий информацию о подписчике. Необходим, но заменяется на MultiData в случае массового добавления подписчиков. |
MultiData | complex | Объект, содержащий информацию о нескольких подписчиках для их массового добавления. Необходим, но не применяется для добавления одного подписчика, когда используется Data. |
Элементы тега Data:
Элемент/Атрибут | Тип | Описание |
---|---|---|
xsi:type | - | Определяет, какое действие производится над данными. Должен быть «Subscriber» для этого запроса. |
Mode | string | Метод добавления. Смотрите список поддерживаемых методов. По умолчанию «AddAndUpdate». |
Force | boolean | Если установлено значение «true», то при повторном запросе на добавление подписчика отправится еще одно письмо подтверждения. Используется только для листов с подтверждением подписки и для неподтвержденных пользователей. Необязательный. По умолчанию «false». |
ListId | integer | Идентификатор листа, в который добавляем подписчика. Обязательный. |
AllowUnsubscribed | boolean | При значении «false» система не позволит добавить подписчика, который ранее отписался. По умолчанию «true». |
AllowRemoved | boolean | При значении «false» система не позволит добавить подписчика, который ранее был удален пользователем. По умолчанию «true». |
MatchingMode | string | Метод согласования подписчиков. Это поле будет использовано как основной идентификатор подписчика. Необязательный. Может принимать значения: Email, CustomSubscriberId, Id, Phone (Phone доступно только при доступе к SMS каналу). Значение по умолчанию:
|
Id | integer | Идентификатор подписчика.* Укажите его, если хотите изменить емейл подписчика. Необязательный. ID подписчика можно получить по GET-запросу. |
string | Емейл подписчика.* Обязательный. | |
EmailMd5 | string | MD5-хэш адреса подписчика.* Необязательный. |
Phone | string | Номер телефона подписчика (доступно только при подключенном SMS канале). Необязательный.** |
CustomSubscriberId | string | ID подписчика. Необязательный. |
Firstname | string | Имя подписчика. Необязательный. |
Lastname | string | Фамилия подписчика. Необязательный. |
TrackingCode | string | Идентификатор источника подписчиков (например, конкретная форма на веб-сайте). |
Name | string | Полное имя. Можно использовать, когда невозможно отделить имя и фамилию. Шаблон — «Имя Фамилия». Необязательный. |
Vendor | string | Идентификатор/имя типа трафика, из которого пришел подписчик. Необязательный. |
Ip | string | IP-адрес подписчика. Необязательный. |
Properties | complex | Дополнительные параметры. Необязательный. |
* Для добавления нового подписчика необходимо указать емейл подписчика. Если вы хотите обновить существующего подписчика, вы должны указать только одно из значений: Email или EmailMd5. Если вы хотите изменить емейл подписчика, вы должны указать Email и ID.
** Если у вас подключен SMS канал, вы можете указать Email или Phone для добавления нового подписчика. Если вы хотите обновить существующего подписчика, вы должны указать только одно из значений: Email, EmailMd5, Phone. Если вы хотите изменить Email или Phone, вы должны указать одно из значений: Email, EmailMd5, Phone, Id, CustomSubscriberId И Email или Phone, которые вы хотите изменить.)
Поддерживаемые методы добавления:
Метод | Описание |
---|---|
AddAndUpdate | Если подписчик (емейл) не содержится в листе, то он будет добавлен. Существующий пользователь будет обновлен. Поля, которые не передаются, не будут обновлены. |
AddAndReplace | Несуществующий подписчик будет добавлен. Существующий подписчик будет обновлен, но поля, которые не передаются, будут удалены. |
AddAndIgnore | Несуществующий подписчик будет добавлен. Существующий подписчик будет пропущен (без генерации ошибки). |
IgnoreAndUpdate | В этом режиме только существующий подписчик будет обновлен. Несуществующие подписчики игнорируются. |
IgnoreAndReplace | Похож на AddAndReplace, но несуществующий подписчик будет пропущен. |
Synchronize | Синхронизация импортируемого файла с листом подписчиков. При этом емейлы, отсутствующие в импортируемом файле, будут удалены из листа подписчиков в Expertsender. Работает только для импорта подписчиков в лиcт |
Элементы тега Property:
Элемент/атрибут | Тип | Описание |
---|---|---|
Id | integer | Идентификатор заранее созданного дополнительного поля. Обязательный. |
Value | mixed | Значение дополнительного поля. Обязательный. Тип значения описывается в обязательном атрибуте xsi:type. Тип должен совпадать с типом заранее созданного дополнительного поля. |
Например, если дополнительное поле с ID = 1 имеет тип «дата», «xsi:type» должен быть «xs:date» или «xs:dateTime» для типа "дата и время". Передача другого типа приведет к ошибке. Для типа «число» надо передавать «xs:int» и т. д.
- Текст - xs:string
- Число - xs:integer
- Валюта - xs:double
- Дата - xs:date
- Дата и время - xs:dateTime
- Единственный выбор - xs:string
- Логический - xs:boolean
- Ссылка - xs:string
Формат Дата: 2014-04-25
Формат Дата и время: 2014-04-25T12:42:00
Дату необходимо передавать в текущем часовом поясе субаккаунта.
xsi:nil = true позволяет обнулить поле, установив его в null (также работает для запроса к таблице данных)
пример:
<Value xsi:type="xs:dateTime" xsi:nil="true"/>
Элемент/атрибут | Тип | Описание |
---|---|---|
MultiData | complex | Список элементов Subscriber, которые имеют такую же структуру, как и элемент Data, при добавлении одного подписчика |
ВАЖНО: При использовании MultiData можно получать ошибки в режиме расширенного вывода (см. примеры ниже).
Формат ответа
Обычно возвращается пустой ответ. В случае удачного запроса возвращается код "201 Created". Вы можете изменять поведение, используя два флага: ReturnData и VerboseErrors. ReturnData позволяет получать информацию по каждому удачно добавленному подписчику. VerboseErrors меняет формат вывода ошибок (при их наличии).
OK ответ с ReturnData=true
Элементы тега ApiResponse
Элемент/атрибут | Тип | Описание |
---|---|---|
ErrorMessage | complex | Объект, содержащий данные об ошибках |
Элементы тега ErrorMessage
Элемент/атрибут | Тип | Описание |
---|---|---|
Code | integer | Код ошибки, например, "400" |
Messages | complex | Список ошибок |
Элементы тега Messages
Элемент/атрибут | Тип | Описание |
---|---|---|
Message | complex | Объект, содержащий информацию об ошибке |
Элементы тега Message
Элемент/атрибут | Тип | Описание |
---|---|---|
for | string | Атрибут XML, отображающий связанный с ошибкой емейл. |
(content) | string | Контент XML, отображающий описание ошибки. |
OK ответ с VerboseErrors=true:
Элементы тега ApiResponse
Элемент/атрибут | Тип | Описание |
---|---|---|
Data | complex | Массив элементов SubscriberData |
Элементы тега Data
Элемент/атрибут | Тип | Описание |
---|---|---|
SubscriberData | complex | Объект содержащий информацию о подписчике |
Элементы тега SubscriberData
Элемент/атрибут | Тип | Описание |
---|---|---|
string | Емейл подписчика. Всегда возвращается при выключенном SMS канале. Если SMS канал включен, возвращается если существует. | |
Id | int | ID подписчика. Возвращается, если только подписчик был добавлен или уже содержится в листе. |
Phone | string | Номер телефона подписчика. Возвращается, только если существует при подключенном SMS канале. |
CustomSubscriberId | string | ID подписчика. Возвращается, только если существует. |
WasAdded | boolean | Флаг сообщающий о том, что подписчик был добавлен в лист |
WasIgnored | boolean | Флаг сообщающий о том, что подписчик был пропущен (зависит от режима добавления, например, если используется режим AddAndIgnore, то будут пропущены подписчики уже содержащиеся в листе) |
Примеры
Запрос, добавляющий единственного подписчика:
POST https://api.esv2.com/v2/Api/Subscribers/ HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: text/xml User-Agent: Jakarta Commons-HttpClient/3.1 Host: api.esv2.com Content-Length: 715 <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <ApiKey>Ваш_API_ключ</ApiKey> <Data xsi:type="Subscriber"> <Mode>AddAndUpdate</Mode> <Force>true</Force> <ListId>1</ListId> <Email>ivan.petrov@domain.com</Email> <Firstname>Ivan</Firstname> <Lastname>Petrov</Lastname> <TrackingCode>123</TrackingCode> <Vendor>Основной сайт</Vendor> <Ip>11.22.33.44</Ip> <Properties> <Property> <Id>2</Id> <Value xsi:type="xs:string">student</Value> </Property> <Property> <Id>3</Id> <Value xsi:type="xs:date">1985-03-12</Value> </Property> </Properties> </Data> </ApiRequest>
Запрос (добавляющий нескольких подписчиков):
Поддерживаются запросы не более 1Мб
<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <ApiKey>Ваш_API_ключ</ApiKey> <MultiData> <Subscriber> <Mode>AddAndUpdate</Mode> <Force>true</Force> <ListId>1</ListId> <Email>ivan.petrov@domain.com</Email> <Firstname>Ivan</Firstname> <Lastname>Petrov</Lastname> <TrackingCode>123</TrackingCode> <Vendor>Основной сайт</Vendor> <Ip>11.22.33.44</Ip> </Subscriber> <Subscriber> <Mode>AddAndUpdate</Mode> <Force>true</Force> <ListId>1</ListId> <Email>jane.doe@domain.com</Email> <Firstname>Jane</Firstname> <Lastname>Doe</Lastname> <TrackingCode>456</TrackingCode> <Vendor>abc</Vendor> <Ip>22.33.44.55</Ip> </Subscriber> </MultiData> </ApiRequest>
OK ответ:
HTTP/1.1 201 Created Cache-Control: private Server: Microsoft-IIS/7.5 X-AspNetMvc-Version: 1.0 X-AspNet-Version: 2.0.50727 X-Powered-By: ASP.NET Date: Wed, 28 Oct 2009 15:35:17 GMT Content-Length: 0
Формат ответа с ошибкой:
HTTP/1.1 400 Bad Request Cache-Control: private Content-Type: text/xml; charset=utf-8 Server: Microsoft-IIS/7.5 X-AspNetMvc-Version: 1.0 X-AspNet-Version: 2.0.50727 X-Powered-By: ASP.NET Date: Wed, 28 Oct 2009 11:32:07 GMT Content-Length: 239 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <ErrorMessage> <Code>400</Code> <Message>Email is invalid;</Message> </ErrorMessage> </ApiResponse>
Массовое добавление подписчиков с расширенным выводом ошибок
Запрос
POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: text/xml Content-Length: 513 Host: api.esv2.com Connection: Keep-Alive User-Agent: Apache-HttpClient/4.1.1 (java 1.5) <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <ApiKey>Ваш_API_ключ</ApiKey> <VerboseErrors>true</VerboseErrors> <MultiData> <Subscriber> <Mode>AddAndUpdate</Mode> <ListId>1</ListId> <Email>ivanpetrov@domain.com</Email> </Subscriber> <Subscriber> <Mode>AddAndUpdate</Mode> <ListId>1</ListId> <Email>olga.stepanova@domain.com</Email> </Subscriber> </MultiData> </ApiRequest>
Ответ с ошибками (расширенный вывод ошибок)
HTTP/1.1 400 Bad Request Cache-Control: private Content-Type: text/xml; charset=utf-8 Server: Microsoft-IIS/7.5 X-AspNetMvc-Version: 5.2 X-AspNet-Version: 4.0.30319 Set-Cookie: TEMP_DATA=6df3c82d-189c-4984-b8b2-a5d78bde501d; path=/ X-Powered-By: ASP.NET Date: Wed, 29 Jul 2015 11:00:50 GMT Content-Length: 373 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <ErrorMessage> <Code>400</Code> <Messages> <Message for="john.smith@@domain.com">Email is invalid</Message> <Message for="jane.doe@domain.com">Address is present on your blacklist</Message> </Messages> </ErrorMessage> </ApiResponse>
Массовое добавление подписчиков с флагом ReturnData = true
Запрос
POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: text/xml Content-Length: 558 Host: api.esv2.com Connection: Keep-Alive User-Agent: Apache-HttpClient/4.1.1 (java 1.5) <ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <ApiKey>Ваш_API_ключ</ApiKey> <VerboseErrors>true</VerboseErrors> <ReturnData>true</ReturnData> <MultiData> <Subscriber> <Mode>AddAndUpdate</Mode> <ListId>1</ListId> <Email>ivan.petrov@domain2.com</Email> </Subscriber> <Subscriber> <Mode>AddAndUpdate</Mode> <ListId>1</ListId> <Email>olga.stepanova@domain2.com</Email> </Subscriber> </MultiData> </ApiRequest>
Ответ
HTTP/1.1 201 Created Cache-Control: private Content-Type: text/xml; charset=utf-8 Server: Microsoft-IIS/7.5 X-AspNetMvc-Version: 5.2 X-AspNet-Version: 4.0.30319 Set-Cookie: TEMP_DATA=09987c87-b886-4164-8fad-89d6ab3ef6bb; path=/ X-Powered-By: ASP.NET Date: Wed, 29 Jul 2015 11:50:48 GMT Content-Length: 517 <ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Data> <SubscriberData> <Email>john.smith@domain2.com</Email> <Id>4238647</Id> <WasAdded>true</WasAdded> <WasIgnored>false</WasIgnored> </SubscriberData> <SubscriberData> <Email>jane.doe@domain2.com</Email> <Id>4238648</Id> <WasAdded>true</WasAdded> <WasIgnored>false</WasIgnored> </SubscriberData> </Data> </ApiResponse>