Get subscriber information - ExpertSender Help Center

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

Short information	Short information w/suppression lists	Full information
Subscriber’s state on particular lists Is this subscriber on Global or Local Blacklist Geographic information	Subscriber’s state on particular lists Is this subscriber on Global or Local Blacklist Suppression lists subscriber belongs to Geographic information	Subscriber’s state on particular lists Is this subscriber on Global or Local Blacklist Suppression lists subscriber belongs to Subscriber’s data: First name Last name IP Subscriber ID Email Phone Custom Subscriber ID Custom Channel ID Vendor All Properties Geographic information

Events history	Subscriptions history
Information about all events associated with subscriber, such as sending a message, clicks, opens etc This is the same information as can be seen in the panel’s Subscriber details	Information about all subscription and unsubscription events associated with a subscriber This is the same information as can be seen in the panel’s Subscriber details

Request data format#

Parameter	Type	Notes
apiKey	staring	Your API key, used for authentication. Required.
id	integer	Subscriber’s ID.Optional*
email	string	Subscriber’s email. Optional.*
md5	string	Subscriber’s email in Md5 format. Optional.*
sha256	string	Subscriber’s email in Sha256 format. Optional.*
phone	string	Subscriber’s phone number.*
customSubscriberId	string	Subscriber’s custom ID. Optional.*
customChannelId	string	Subscriber’s Custom Channel ID. Optional. ***
option	string**	Required. There are 4 options of getting information: Short – Basic information Long – Basic information plus suppression list info Full – Full information with property values EventsHistory – History of events associated with subscriber SubscriptionsHistory – History of subscriptions/unsubscriptions of a subscriber
bounceDetails	bool	Parameter used only if the option=EventHistory is selected. In the case of true will be returned bounce diagnostic code.
geoDetails	bool	Subscriber’s geographic details.

* At least one of the following must be specified: Id, Md5, Sha256, Email, Phone or CustomSubscriberId. System will firstly look for Id, then Email, Md5, Sha256, 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.
*** only when custom channel is activated

Response

Response Data element:

Element/attribute	Type	Notes
BlackListEmail	boolean	If 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.
BlackListPhone	boolean	If 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.
StateOnLists	array[complex]	Array of StateOnList elements.
City	string	Subscriber’s city
Country	string	Subscriber’s country
State	string	Subscriber’s state

StateOnList element children:

Element/attribute	Type	Notes
Email	string	Subscriber’s email address.
Phone	integer	Subscriber’s phone number.
ListId	integer	ID of subscribed list.
Name	string	Name of subscribed list.
Status	string	Subscriber state on particular list.
SubscribedOn	datetime	Date of subscription.
UnsubscriptionDate	datetime	Date of unsubscription. Returned only for unsubscribed status.

Response for „Long” information

Response Data element:

Element/attribute	Type	Notes
BlackListEmail	boolean	If 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.
BlackListPhone	boolean	If 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.
StateOnLists	array[complex]	Array of StateOnList elements.
SuppressionLists	array[complex]	Array of SuppressionList elements.
City	string	Subscriber’s city
Country	string	Subscriber’s country
State	string	Subscriber’s state

StateOnList element children:

Element/attribute	Type	Notes
Email	string	Subscriber’s email address.
Phone	integer	Subscriber’s phone number.
ListId	integer	ID of subscribed list.
Name	string	Name of subscribed list.
Status	string	Subscriber state on particular list.
SubscribedOn	datetime	Date of subscription.

SuppressionList element children:

Element/attribute	Type	Notes
Id	integer	ID of current suppression list.
Name	string	Name of current suppression list.
Type	string	Type of current suppression list. Possible types are: Email Phone

Response for „Full” information

Response Data element:

Element/attribute	Type	Notes
BlackListEmail	boolean	If 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.
BlackListPhone	boolean	If 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.
StateOnLists	array[complex]	Array of StateOnList elements.
SuppressionLists	array[complex]	Array of SuppressionList elements.
Firstname	string	First name of current subscriber.
Lastname	string	Last name of current subscriber.
Ip	string	IP of current subscriber. Optional.
Id	integer	ID of current subscriber.
CustomChannelId	string	Subscriber’s custom channel ID.
Email	string	Subscriber’s email address.
Phone	string	Subscriber’s phone number.
CustomSubscriberId	string	Subscriber’s custom ID.
Vendor	string	Vendor code of current subscriber. Optional.
Properties	array[complex]	Array of subscriber’s properties. Optional.
City	string	Subscriber’s city
Country	string	Subscriber’s country
State	string	Subscriber’s state

StateOnList element children:

Element/attribute	Type	Notes
Email	string	Subscriber’s email address.
Phone	integer	Subscriber’s phone number.
ListId	integer	ID of subscribed list.
Name	string	Name of subscribed list.
Status	string	Subscriber state on particular list.
SubscribedOn	datetime	Date of subscription.

SuppressionList element children:

Element/attribute	Type	Notes
Id	integer	ID of current suppression list.
Name	string	Name of current suppression list.
Type	string	Type of current suppression list. Possible types are: Email Phone

Properties element children:

Element/attribute	Type	Notes
Id	integer	ID of current property.
Source	string	Information about the source of property value. See below for all possible property sources.
DateTimeValue	datetime	Value. Only for date and datetime property.
IntValue	integer	Value. Only for integer properties.
StringValue	string	Value. Only for string properties.
DecimalValue	decimal	Value. Only for money properties.
Type	string	Property type. See below for all possible property types.
FriendlyName	string	Friendly property name.
Description	string	Description of current property.
Name	string	Name of current property.
DefaultStringValue	string	Default property value. Only for string properties.
DefaultIntValue	integer	Default property value. Only for integer properties.
DefaultDateTimeValue	datetime	Default property value. Only for data and datetime properties.
DefaultDecimalValue	decimal	Default property value. Only for money properties.

Property sources:

Name	Description
Web	Property was added/modified using a subscription webform.
Panel	Property was added/modified manually by user in ExpertSender application.
Import	Property was added/modified during an import.
Api	Property was added/modified using ExpertSender REST API.
PrefCenter	Subscriber added/modified the property on Preference Center page.

Property types:

Name	Description
Text	Text (string) property.
Number	Whole number, e.g. '0′ or '123′.
Money	A number with two decimal places, e.g. '10.99′.
Url	Url.
Date	Date, e.g. '2011-01-01′.
Datetime	Date and time information, e.g. '2011-01-01 12:00:00′.
SingleSelect	An enumeration of predefined values with one selected value possible, e.g. 'option 1′.
Boolean	True/false.

Response for „EventsHistory” information

Response Data element:

Element/attribute	Type	Notes
Events	array[complex]	Array of Event elements.

Event element children:

Element/attribute	Type	Notes
StartDate	datetime	Event start date.
EndDate	datetime	Event end date.
Channel	string	Channel involved in an event. Possible values: EmailSmsMms
MessageType	string	Type of message involved in an event. Newsletter, Autoresponder, Trigger, Transactional etc.
EventType	string	Type of event. Send, Open, Click, Bounce, Complaint, Confirm, Unsubscribe.
EventCount	integer	Number of event occurrences between StartDate and EndDate.
MessageId	integer	ID of message involved in an event.
MessageSubject	string	Subject of message involved in an event.
BounceDiagnosticCode	string	Contents of the diagnostic code.

Response for „SubscriptionsHistory” information

Response Data element:

Element/attribute	Type	Notes
SubscriptionsHistory	array[complex]	Array of SubscriptionEvent elements.

SubscriptionEvent element children:

Element/attribute	Type	Notes
StartDate	datetime	Event start date.
EndDate	datetime	Event end date.
Channel	string	Channel involved in an event. Present only if unit uses any channels besides email. Possible values: Email SmsMms
EventType	string	Type of event. Possible values: Subscribed Unsubscribed
List	string	Details of a list that the event concerns, in form of „[list id] list name”
EventSource	string	Source 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>