/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>false</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>false</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>false</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>