Skip to content

Get subscriber information

Get varied description of single Subscriber. There are 5 options of getting information:

Short informationShort information w/suppression listsFull information
Subscriber’s state on particular listsIs this subscriber on Global or Local BlacklistSubscriber’s state on particular listsIs this subscriber on Global or Local Blacklist Suppression lists subscriber belongs toSubscriber’s state on particular listsIs this subscriber on Global or Local BlacklistSuppression lists subscriber belongs toSubscriber’s data:First nameLast nameIPSubscriber IDEmailPhoneCustom Subscriber IDVendorAll Properties
Events historySubscriptions history
 Information about all events associated with subscriber, such as sending a message, clicks, opens etcThis is the same information as can be seen in the panel’s Subscriber details Information about all subscription and unsubscription events associated with a subscriberThis is the same information as can be seen in the panel’s Subscriber details

Request data format

ParameterTypeNotes
apiKeystaringYour API key, used for authentication. Required.
idintegerSubscriber’s ID.Optional*
emailstringSubscriber’s email. Optional.*
phonestringSubscriber’s phone number.*
customSubscriberIdstringSubscriber’s custom ID.*
optionstring**Required. There are 4 options of getting information:
Short – Basic information Long – Basic information plus suppression list info Full – Full information with property valuesEventsHistory – History of events associated with subscriberSubscriptionsHistory – History of subscriptions/unsubscriptions of a subscriber

* At least one of the following must be specified: Id, Email, Phone or CustomSubscriberId. System will firstly look for Id, then Emal, Phone and CustomSubscriberId. If more than one is specified system will use the first element with any value and ignore the others.
** For compatibility reasons, you may use integers (1, 2, 3, 4) instead of string. But this method of selecting type of returned information should be considered deprecated.

Response

Response Data element:

Element/attributeTypeNotes
BlackListEmailbooleanIf set to “true” (note the lowercase!), this parameter means that current email is on some blacklist (local or global). “false” means that current email isn’t on any blacklist. Omitted if subscriber doesn’t have an email address.
BlackListPhonebooleanIf set to “true” (note the lowercase!), this parameter means that current phone is on some blacklist (local or global). “false” means that current phone isn’t on any blacklist. Omitted if subscriber doesn’t have a phone number.
StateOnListsarray[complex]Array of StateOnList elements.

StateOnList element children:

Element/attributeTypeNotes
EmailstringSubscriber’s email address.
PhoneintegerSubscriber’s phone number.
ListIdinteger ID of subscribed list.
NamestringName of subscribed list.
StatusstringSubscriber state on particular list.
SubscribedOndatetimeDate of subscription.

Response for “Long” information

Response Data element:

Element/attributeTypeNotes
BlackListEmailbooleanIf set to “true” (note the lowercase!), this parameter means that current email is on some blacklist (local or global). “false” means that current email isn’t on any blacklist. Omitted if subscriber doesn’t have an email address.
BlackListPhonebooleanIf set to “true” (note the lowercase!), this parameter means that current phone is on some blacklist (local or global). “false” means that current phone isn’t on any blacklist. Omitted if subscriber doesn’t have a phone number.
StateOnListsarray[complex]Array of StateOnList elements.
SuppressionListsarray[complex]Array of SuppressionList elements.

StateOnList element children:

Element/attributeTypeNotes
EmailstringSubscriber’s email address.
PhoneintegerSubscriber’s phone number.
ListIdintegerID of subscribed list.
NamestringName of subscribed list.
StatusstringSubscriber state on particular list.
SubscribedOndatetimeDate of subscription.

SuppressionList element children:

Element/attributeTypeNotes
IdintegerID of current suppression list.
NamestringName of current suppression list.
TypestringType of current suppression list. Possible types are:
EmailPhone

Response for “Full” information

Response Data element:

Element/attributeTypeNotes
BlackListEmailbooleanIf set to “true” (note the lowercase!), this parameter means that current email is on some blacklist (local or global). “false” means that current email isn’t on any blacklist. Omitted if subscriber doesn’t have an email address.
BlackListPhonebooleanIf set to “true” (note the lowercase!), this parameter means that current phone is on some blacklist (local or global). “false” means that current phone isn’t on any blacklist. Omitted if subscriber doesn’t have a phone number.
StateOnListsarray[complex]Array of StateOnList elements.
SuppressionListsarray[complex]Array of SuppressionList elements.
FirstnamestringFirst name of current subscriber.
LastnamestringLast name of current subscriber.
IpstringIP of current subscriber. Optional.
IdintegerID of current subscriber.
EmailstringSubscriber’s email address.
PhonestringSubscriber’s phone number.
CustomSubscriberIdstringSubscriber’s custom ID.
VendorstringVendor code of current subscriber. Optional.
Propertiesarray[complex]Array of subscriber’s properties. Optional.

StateOnList element children:

Element/attributeTypeNotes
EmailstringSubscriber’s email address.
PhoneintegerSubscriber’s phone number.
ListIdintegerID of subscribed list.
NamestringName of subscribed list.
StatusstringSubscriber state on particular list.
SubscribedOndatetimeDate of subscription.

SuppressionList element children:

Element/attributeTypeNotes
IdintegerID of current suppression list.
NamestringName of current suppression list.
TypestringType of current suppression list. Possible types are:
EmailPhone

Properties element children:

Element/attributeTypeNotes
IdintegerID of current property.
SourcestringInformation about the source of property value. See below for all possible property sources.
DateTimeValuedatetimeValue. Only for date and datetime property.
IntValueintegerValue. Only for integer properties.
StringValuestringValue. Only for string properties.
DecimalValue decimal Value. Only for money properties. 
TypestringProperty type. See below for all possible property types.
FriendlyNamestringFriendly property name.
Description string Description of current property.  
NamestringName of current property.
DefaultStringValuestringDefault property value. Only for string properties.
DefaultIntValueintegerDefault property value. Only for integer properties.
DefaultDateTimeValuedatetimeDefault property value. Only for data and datetime properties.
DefaultDecimalValue decimal Default property value. Only for money properties. 

Property sources:

NameDescription
WebProperty was added/modified using a subscription webform.
PanelProperty was added/modified manually by user in ExpertSender application.
ImportProperty was added/modified during an import.
ApiProperty was added/modified using ExpertSender REST API.
PrefCenterSubscriber added/modified the property on Preference Center page.

Property types:

NameDescription
TextText (string) property.
NumberWhole number, e.g. ‘0’ or ‘123’.
MoneyA number with two decimal places, e.g. ‘10.99’.
UrlUrl.
DateDate, e.g. ‘2011-01-01’.
DatetimeDate and time information, e.g. ‘2011-01-01 12:00:00’.
SingleSelectAn enumeration of predefined values with one selected value possible, e.g. ‘option 1’.
BooleanTrue/false.

Response for “EventsHistory” information

Response Data element:

Element/attributeTypeNotes
Eventsarray[complex]Array of Event elements.

Event element children:

Element/attributeTypeNotes
StartDatedatetime Event start date.
EndDatedatetimeEvent end date.
Channelstring Channel involved in an event. Possible values:
EmailSmsMms
MessageTypestringType of message involved in an event. Newsletter, Autoresponder, Trigger, Transactional etc.
EventTypestringType of event. Send, Open, Click, Bounce, Complaint, Confirm, Unsubscribe.
EventCountintegerNumber of event occurrences between StartDate and EndDate.
MessageIdintegerID of message involved in an event.
MessageSubjectstringSubject of message involved in an event.

Response for “SubscriptionsHistory” information

Response Data element:

Element/attributeTypeNotes
SubscriptionsHistoryarray[complex]Array of SubscriptionEvent elements.

SubscriptionEvent element children:

Element/attributeTypeNotes
StartDatedatetimeEvent start date.
EndDatedatetimeEvent end date.
ChannelstringChannel involved in an event. Present only if unit uses any channels besides email. Possible values:
EmailSmsMms
EventTypestringType of event. Possible values:
SubscribedUnsubscribed
ListstringDetails of a list that the event concerns, in form of “[list id] list name”
EventSourcestringSource that caused the event

Examples

Getting subscriber’s information:

Request:

GET https://api.esv2.com/v2/Api/Subscribers?apiKey=test_api_key1&email=john%40yahoo.com&option=Full HTTP/1.1 
Accept-Encoding: gzip,deflate
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.com

OK response:

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: Mon, 25 Apr 2016 16:07:21 GMT 
Content-Length: 421 

<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Data>
   <BlackListEmail>false</BlackListEmail>
   <BlackListPhone>false</BlackListPhone>
   <StateOnLists>
    <StateOnList>
     <Email>john@yahoo.com</Email>
     <ListId>123</ListId>
     <Name>Testowa Lista</Name>
     <Status>Unsubscribed</Status>
     <SubscribedOn>2014-12-29T15:30:09</SubscribedOn>
    </StateOnList>
    <StateOnList>
     <Email>john@yahoo.com</Email>
     <ListId>456</ListId>
     <Name>Testowa Seed Lista 1 (3)</Name>
     <Status>Active</Status>
     <SubscribedOn>2014-11-12T12:30:41</SubscribedOn>
    </StateOnList>
    <StateOnList>
     <Phone>48789456123</Phone>
     <ListId>789</ListId>
     <Name>Testowa Lista 2</Name>
     <Status>Active</Status>
     <SubscribedOn>2015-01-11T11:00:02</SubscribedOn>
    </StateOnList>
   </StateOnLists>
   <SuppressionLists>
    <SuppressionList>
     <Id>1</Id>
     <Name>testowa lista suppression nr 1</Name>
     <Type>Phone</Type>
    </SuppressionList>
    <SuppressionList>
     <Id>2</Id>
     <Name>testowa lista suppression nr 2</Name>
    </SuppressionList>
   </SuppressionLists>
   <Id>3045574</Id>
   <Email>john@yahoo.com</Email>
   <Phone>48789456123</Phone>
   <CustomSubscriberId>522145698</CustomSubscriberId>
   <Firstname>John</Firstname>
   <Lastname>Doe</Lastname>
   <Vendor>RIVER2</Vendor>
   <Ip>90.2.214.146</Ip>
   <Properties>
    <Property>
     <Id>1</Id>
     <Source>NotSet</Source>
     <DateTimeValue xsi:type="xsd:dateTime">2016-07-19T00:00:00</DateTimeValue>
     <Type>Datetime</Type>
     <FriendlyName>Date added</FriendlyName>
     <Description/>
     <Name>dateadded</Name>
    </Property>
    <Property>
     <Id>5</Id>
     <Source>NotSet</Source>
     <StringValue xsi:type="xsd:string">Mr</StringValue>
     <Type>Text</Type>
     <FriendlyName>Title</FriendlyName>
     <Description/>
     <Name>title</Name>
    </Property>
   </Properties>
  </Data>
</ApiResponse>

Getting subscriber’s events history:

Request:

GET https://api.esv2.com/v2/Api/Subscribers?apiKey=test_api_key1&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)

OK response:

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 2017 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>
        <Channel>Email</Email>
        <MessageType>Newsletter</MessageType>
        <EventType>Click</EventType>
        <EventCount>1</EventCount>
        <MessageId>120540</MessageId>
        <MessageSubject>test of links</MessageSubject>
      </Event>
      <Event>
        <StartDate>2015-01-25T10:00:00</StartDate>
        <EndDate>2015-01-25T11:00:00</EndDate>
        <Channel>SmsMms</Email>
        <MessageType>Newsletter</MessageType>
        <EventType>Send</EventType>
        <EventCount>1</EventCount>
        <MessageId>473821</MessageId>
        <MessageSubject>test competition announcement</MessageSubject>
      </Event>
      <Event>
        <StartDate>2015-01-25T08:00:00</StartDate>
        <EndDate>2015-01-25T09:00:00</EndDate>
        <Channel>Email</Email>
        <MessageType>Newsletter</MessageType>
        <EventType>Send</EventType>
        <EventCount>1</EventCount>
        <MessageId>120540</MessageId>
        <MessageSubject>test of links</MessageSubject>
      </Event>
    </Events>
  </Data>
</ApiResponse>

Getting subscriber’s subscriptions history:

Request:

GET https://api.esv2.com/v2/Api/Subscribers?apiKey=test_api_key1&email=john%40yahoo.com&option=SubscriptionsHistory HTTP/1.1 Accept-Encoding: gzip,deflate
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

OK response:

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 2017 13:37:40 GMT
Content-Length: 734

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <SubscriptionsHistory>
      <SubscriptionEvent>
        <StartDate>2018-06-27T20:00:00</StartDate>
        <EndDate>2018-06-27T21:00:00</EndDate>
        <Channel>Email</Channel>
        <EventType>Unsubscribed</EventType>
        <List>[1] Some default list</List>
        <EventSource>Opt-out link</EventSource>
      </SubscriptionEvent>
      <SubscriptionEvent>
        <StartDate>2015-01-03T12:00:00</StartDate>
        <EndDate>2015-01-25T13:00:00</EndDate>
        <Channel>Email</Channel>
        <EventType>Subscribed</EventType>
        <List>[5] Special campaign list</List>
        <EventSource>Import</EventSource>
      </SubscriptionEvent>
    </SubscriptionsHistory>
  </Data>
</ApiResponse>
On this page
To top