/v2/Api/Subscribers GET

Возвращает информацию о подписчике. Существует 4 варианта получения информации.

Короткая информация Короткая информация, содержащая стоп-листы Полная информация История событий
  • находится ли подписчик в списке рассылки;
  • находится ли емейл в глобальном или в локальном черном списке.
  • находится ли подписчик в списке рассылки;
  • находится ли подписчик в глобальном черном списке;
  • стоп-лист (только тот, в котором содержится этот емейл).
  • находится ли подписчик в списке рассылки;
  • находится ли подписчик в глобальном черном списке;
  • стоп-лист (только тот, в котором содержится этот емейл);
  • информация о подписчике:
    • имя,
    • фамилия,
    • IP,
    • ID подписчика,
    • источник трафика,
    • все дополнительные поля подписчика
  • Информация о событиях связанных с подписчиком, такие как отправка сообщения, клики, открытия и т.д.
  • Информация аналогичная той, что можно увидеть в Деталях подписчика в веб-интерфейсе.

Формат запроса

ПараметрТипОписание
apiKeystringВаш API-ключ, необходимый для авторизации. Обязательный.
emailstring*Емейл подписчика.
customSubscriberIdstring*Идентификатор подписчика.
phonestring*Номер телефона.
optionstring**Short - короткая информация.
Long - короткая информация, содержащая стоп-листы.
Full - полная информация со значениями дополнительных полей.
EventsHistory - Информация о действиях подписчика (История событий).

*Необходимо указать хотя бы одно из следующего: Email, Phone или CustomSubscriberId. Сначала система будет искать Emal, затем Phone и CustomSubscriberId. Если указано более одного, система будет использовать первый элемент с любым значением и игнорировать остальные.

**В целях совместимости можно использовать integer значения (1,2,3,4) вместо string. Но использование такого способа является устаревшим, и будет отключено в скором времени.

Ответ

Short - Короткая информация

Элементы тега Data в ответе:

Элемент/атрибутТипОписание
BlacklistbooleanЕсли значение «true», то емейл находится в черном списке (локальном или глобальном). Если «false», то этот емейл не находится в черных списках.
StateOnListsarray[complex]Массив элементов StateOnList.

Элементы тега StateOnList:

Элемент/атрибутТипОписание
ListIdintID листа.
NamestringИмя листа.
StatusstringСтатус емейла в этом листе. Возможные значения: «Unsubscribed», «Active», «Snoozed», «NotConfirmed».
SubscribedOndatetimeДата подписки.

Long - Короткая информация, содержащая информацию о стоп-листах.

Элементы тега Data в ответе:

Элемент/атрибутТипОписание
BlacklistbooleanЕсли значение «true», то емейл находится в черном списке (локальном или глобальном). Если
«false», то этот емейл не находится в черных списках.
StateOnListsarray[complex]Массив элементов StateOnList.
SuppressionListsarray[complex]Массив элементов SuppressionLists.

Элементы тега StateOnList:

Элемент/атрибутТипОписание
ListIdintID листа.
NamestringИмя листа.
StatusstringСтатус емейла в этом листе. Возможные значения: «Unsubscribed», «Active», «Snoozed», «NotConfirmed».
SubscribedOndatetimeДата подписки

Элементы тега SuppressionList:

Элемент/атрибутТипОписание
IdintegerID стоп-листа.
NamestringИмя стоп-листа.

Full - Полная информация

Элементы тега Data в ответе:

Элемент/атрибутТипОписание
BlackListbooleanЕсли значение «true», то емейл находится в черном списке (локальном или глобальном). Если «false», то этот емейл не находится в черных списках.
StateOnListsarray[complex]Массив элементов StateOnList.
SuppressionListsarray[complex]Массив элементов SuppressionLists.
FirstnamestringИмя подписчика.
LastnamestringФамилия подписчика.
IpstringIP-адрес подписчика. Необязательное.
IdIntegerID подписчика. Обязательное.
VendorstringИсточник трафика. Необязательное.
Propertiesarray[complex]Массив дополнительных полей подписчика. Необязательное.

Элементы тега StateOnList:

Элемент/атрибутТипОписание
ListIdintID листа.
NamestringИмя листа.
StatusstringСтатус емейла в этом листе. Возможные значения: «Unsubscribed», «Active», «Snoozed», «NotConfirmed».
SubscribedOndatetimeДата подписки.

Элементы тега SuppressionLists:

Элемент/атрибутТипОписание
IdintegerID стоп-листа.
NamestringИмя стоп-листа.

Элементы тега Properties:

Элемент/атрибутТипОписание
IdintegerID текущего дополнительного поля подписчика.
SourcestringИнформация об источнике дополнительного поля подписчика. Ниже смотрите все возможные источники.
DateTimeValuedatetimeЗначение. Только для дополнительных полей с типом date и datetime.
IntValueintegerЗначение. Только для дополнительных полей с числовым типом.
StringValuestringЗначение. Только для дополнительных полей со строковым типом.
DecimalValuedecimalЗначение. Только для дополнительных полей с типом валюта.
TypestringТип дополнительного поля подписчика. Смотрите ниже все возможные типы.
FriendlyNamestringИмя дополнительного поля подписчика.
NamestringСлужебное имя дополнительного поля подписчика.
DefaultStringValuestringЗначение дополнительного поля подписчика по умолчанию. Только для текстовых типов.
DefaultIntValueintegerЗначение дополнительного поля подписчика по умолчанию. Только для текстовых типов.
DefaultDateTimeValuedatetimeЗначение дополнительного поля подписчика по умолчанию. Только для дополнительных полей с типом Дата и Дата и время.
DefaultDecimalValuedecimalЗначение дополнительного поля подписчика по умолчанию. Только для дополнительных полей с типом валюта.

Источники дополнительных полей:

NameОписание
WebЗначение дополнительного поля подписчика было добавлено/изменено через веб-форму подписки.
Panel Значение дополнительного поля подписчика было добавлено/изменено вручную через ExpertSender.
ImportЗначение дополнительного поля подписчика было добавлено/изменено через импорт.
ApiЗначение дополнительного поля подписчика было добавлено/изменено через REST APIExpertSender.
PrefCenterЗначение дополнительного поля подписчика было добавлено/изменено через страницу «Менеджер подписки».

Типы дополнительных полей:

NameОписание
TextТекстовое дополнительное поле подписчика.
NumberЦелое число, например, 0 или 123.
MoneyЧисло с десятичным разделителем, например, 10,99.
UrlUrl.
DateДата, например, 2011-01-01.
DatetimeДата и время, например, 2011-01-01 12:00:00.
SingleSelectСписок с возможностью выбрать из него только одно значение.
Booleantrue/false.

При создании дополнительного поля подписчика в платформе ExpertSender необходимо сразу удостовериться, что тип дополнительного поля подписчика задан верно. Впоследствии тип дополнительного поля подписчика менять нельзя.

EventsHistory - История событий подписчика.

Элементы тега Data:

Элемент/атрибутТипОписание
Eventsarray[complex]Массив элементов Event

Элементы тега Event:

Элемент/атрибутТипОписание
StartDatedatetimeДата начала события.
EndDatedatetimeДата окончания события.
MessageTypestringТип сообщения
EventTypestringТип события. Возможны следующие значения:
  • Send
  • Open
  • Click
  • Bounce
  • Complaint
  • Confirm
  • Unsubscribe
EventCountintegerНомер события со StartDate до EndDate
MessageIdintegerID сообщения в статистике.
MessageSubjectstringТема сообщения в событии.

Примеры

Получить информацию о подписчике:

Запрос:

GET https://api.esv2.com/v2/Api/Subscribers?apiKey=Ваш_API_ключ&email=john%40yahoo.com&option=2 HTTP/1.1 
Accept-Encoding: gzip,deflate
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.com

Ответ:

HTTP/1.1 200 OK
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/7.5 
Set-Cookie: ASP.NET_SessionId=soo4fqb5y5cjbr3wimnyelb3; path=/; HttpOnly 
X-AspNetMvc-Version: 1.0 
X-AspNet-Version: 2.0.50727 
X-Powered-By: ASP.NET 
Date: Thu, 22 Jul 2010 11:35:21 GMT 
Content-Length: 293 
 
 <ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Data>
   <BlackList>false</BlackList>
   <StateOnLists>
    <StateOnList>
     <Name>Тестовый лист</Name>
     <Status>Unsubscribed</Status>
     <SubscribedOn>2014-11-12T12:30:41</SubscribedOn>
    </StateOnList>
    <StateOnList>
     <Name>Тестовый лист 1 (3)</Name>
     <Status>Active</Status>
     <SubscribedOn>2014-11-12T12:30:41</SubscribedOn>
    </StateOnList>
    <StateOnList>
     <Name>Тестовый лист 2</Name>
     <Status>Unsubscribed</Status>
     <SubscribedOn>2014-11-12T12:30:41</SubscribedOn>
    </StateOnList>
   </StateOnLists>
   <EmailInSuppressionLists>
    <SuppressionList>
     <Id>1</Id>
     <Name>Тестовый стоп-лист 1</Name>
    </SuppressionList>
    <SuppressionList>
     <Id>2</Id>
     <Name>Тестовый стоп-лист 2</Name>
    </SuppressionList>
   </EmailInSuppressionLists>
  </Data>
 </ApiResponse>

Формат ответа с ошибкой:

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>Receivers data was not supplied;</Message>
   </ErrorMessage>
 </ApiResponse>

Получить историю событий подписчика:

Запрос:

GET https://api.esv2.com/v2/Api/Subscribers?apiKey=Ваш_API_ключ&email=john%40yahoo.com&option=EventsHistory HTTP/1.1
Accept-Encoding: gzip,deflate
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

ОК ответ:

HTTP/1.1 200 OK
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=2baf0f58-63a5-44bc-9673-988be8061978; path=/
X-Powered-By: ASP.NET
Date: Tue, 27 Jan 2015 13:37:40 GMT
Content-Length: 1259

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <Events>
      <Event>
        <StartDate>2015-01-25T10:00:00</StartDate>
        <EndDate>2015-01-25T11:00:00</EndDate>
        <MessageType>Newsletter</MessageType>
        <EventType>Click</EventType>
        <EventCount>1</EventCount>
        <MessageId>120540</MessageId>
        <MessageSubject>Тема тестового сообщения</MessageSubject>
      </Event>
      <Event>
        <StartDate>2015-01-25T10:00:00</StartDate>
        <EndDate>2015-01-25T11:00:00</EndDate>
        <MessageType>Newsletter</MessageType>
        <EventType>Open</EventType>
        <EventCount>1</EventCount>
        <MessageId>120540</MessageId>
        <MessageSubject>Тема тестового сообщения</MessageSubject>
      </Event>
      <Event>
        <StartDate>2015-01-25T10:00:00</StartDate>
        <EndDate>2015-01-25T11:00:00</EndDate>
        <MessageType>Newsletter</MessageType>
        <EventType>Send</EventType>
        <EventCount>1</EventCount>
        <MessageId>120540</MessageId>
        <MessageSubject>Тема тестового сообщения</MessageSubject>
      </Event>
    </Events>
  </Data>
</ApiResponse>