/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 Идентификатор листа, в который добавляем подписчика. Обязательный.
AllowUnsubscribedbooleanПри значении «false» система не позволит добавить подписчика, который ранее отписался. По умолчанию «true».
AllowRemovedbooleanПри значении «false» система не позволит добавить подписчика, который ранее был удален пользователем. По умолчанию «true».
MatchingModestringМетод согласования подписчиков. Это поле будет использовано как основной идентификатор подписчика. Необязательный. Может принимать значения: Email, CustomSubscriberId, Id, Phone (Phone доступно только при доступе к SMS каналу).

Значение по умолчанию:

  • Email если для подписчика указан только емейл или телефон и емейл.
  • Phone если для подписчика указан только телефон.
  • Id если для подписчика указан Id.
Id integer Идентификатор подписчика.* Укажите его, если хотите изменить емейл подписчика. Необязательный. ID подписчика можно получить по GET-запросу.
Email string Емейл подписчика.* Обязательный.
EmailMd5stringMD5-хэш адреса подписчика.* Необязательный.
PhonestringНомер телефона подписчика (доступно только при подключенном SMS канале). Необязательный.**
CustomSubscriberIdstringID подписчика. Необязательный.
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

Элемент/атрибут Тип Описание
Email string Емейл подписчика. Всегда возвращается при выключенном SMS канале. Если SMS канал включен, возвращается если существует.
Id int ID подписчика. Возвращается, если только подписчик был добавлен или уже содержится в листе.
PhonestringНомер телефона подписчика. Возвращается, только если существует при подключенном SMS канале.
CustomSubscriberIdstringID подписчика. Возвращается, только если существует.
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>