Get removed subscribers - ExpertSender Help Center

Removed collection allows retrieving a list of subscribers removed from lists for any reason. Any combination of remove type, data range and list can be specified to help with searching for data of interest.

Request format

Request URL parameters:

Parameter	Type	Notes
apiKey	string	Your API key, required for authentication. Required.
listIds	int (CSV)	List identifiers. Optional. If specified, only removed subscribers from given lists will be returned. If not specified, removed subscribers from all lists will be returned. To specify multiple list IDs, use comma separated format, e.g.: 12,34,56,789
removeTypes	string (CSV)	Remove types (reasons). Optional. If specified, only subscribers removed for listed reasons will be returned. If omitted, all reasons will be included. To specify multiple remove types, use comma separated format, e.g.: OptOutLink,Ui. See below for list of all known remove types.
startDate	date	Start date. Optional. If specified, subscribers removed prior to this date will not be returned. May be used together with endDate to specify a period of time. YYYY-MM-DD format.
endDate	date	See startDate.
option	string	Optional. If specified, additional subscriber information will be returned. Valid values: Customs – Return all subscriber properties and some general information
channel	string	Limits returned data to selected channel. Optional. Defaults to Email. Valid values: All Email SmsMms

Note: Make notice that only apiKey parameter is required. If you omit other parameters, you will get a list of all subscribers removed for any reason, from any list, since the creation of your business unit.

Remove types:

Value	Description
OptOutLink	Subscriber clicked unsubscribe link in email.
Ui	Removed manually using user interface (ExpertSender panel).
BounceLimit	Removed because limit of bounced messages was reached.
Complaint	Subscriber issued a spam complaint
UserUnknown	Removed because email server returned User Unknown bounce (email address does not exist).
Api	Removed using API.
SyncImport	Removed during synchronization with file.

Example URLs:

https://api.esv2.com/v2/Api/RemovedSubscribers?apiKey=YOUR_API_KEY_HERE

https://api.esv2.com/v2/Api/RemovedSubscribers?apiKey=YOUR_API_KEY_HERE&listIds=1,3,16

https://api.esv2.com/v2/Api/RemovedSubscribers?apiKey=YOUR_API_KEY_HERE&startDate=2017-05-01&endDate=2017-09-01

https://api.esv2.com/v2/Api/RemovedSubscribers?apiKey=YOUR_API_KEY_HERE&removeTypes=OptOutLink,Complaint,Ui

https://api.esv2.com/v2/Api/RemovedSubscribers?apiKey=YOUR_API_KEY_HERE&channel=Email

Response

Response Data element:

Element/attribute	Type	Notes
RemovedSubscribers	array[complex]	Array of RemovedSubscriber elements.

RemovedSubscriber element children:

Element/attribute	Type	Notes
Id	int	Subscriber’s ID
Email	string	Email of unsubscribed subscriber.
Phone	string	Phone number of unsubscribed subscriber.
ListId	int	Identifier of list that subscriber unsubscribed from.
UnsubscribedOn	dateTime	Date and time of unsubscription.

Additional elements returned with “Customs” option specified:

Element/attribute	Type	Notes
CustomSubscriberId	string	Subscriber’s custom ID.
Firstname	string	Subscriber’s firstname.
Lastname	string	Subscriber’s lastname.
Ip	string	Subscriber’s IP address.
Vendor	string	Vendor code of current subscriber.
Properties	array[complex]	Array of subscriber’s properties.

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.

Examples

Simple request

Request:

GET http://api.esv2.com/v2/Api/RemovedSubscribers?startDate=2011-02-01&apiKey=test_api_key1&listIds=1&endDate=2011-09-16 HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

Response:

HTTP/1.1 200 OK 
Cache-Control: private 
Content-Type: text/xml; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 3.0 
X-AspNet-Version: 4.0.30319 
X-Powered-By: ASP.NET 
Date: Thu, 17 May 2012 13:15:26 GMT 
Content-Length: 535 

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Data>
     <RemovedSubscribers>
       <RemovedSubscriber>
         <Id>123</Id>
         <Email>test123@yahoo.com</Email>
         <ListId>1</ListId>
         <UnsubscribedOn>2011-07-21T00:00:00Z</UnsubscribedOn>
       </RemovedSubscriber>
       <RemovedSubscriber>
         <Id>456</Id>
         <Email>test456@yahoo.com</Email>
         <ListId>1</ListId>
         <UnsubscribedOn>2011-09-14T11:37:20Z</UnsubscribedOn>
       </RemovedSubscriber>
   </Data>
</ApiResponse>

Simple request with all channels

We have three subscribers: Sub1 with email test123@yahoo.com and phone number 123456789, Sub2 with only email test456@gmail.com and Sub3 with only phone 111222333. All of them were removed from list 1 on all channels.

Request:

GET http://api.esv2.com/v2/Api/RemovedSubscribers?startDate=2017-02-01&apiKey=test_api_key1&listIds=1&endDate=2017-09-16&channel=All 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 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 3.0 
X-AspNet-Version: 4.0.30319 
X-Powered-By: ASP.NET 
Date: Thu, 17 May 2012 13:15:26 GMT 
Content-Length: 535  

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Data>
     <RemovedSubscribers>
       <RemovedSubscriber>
         <Id>123</Id>
         <Email>test123@yahoo.com</Email>
         <ListId>1</ListId>
         <UnsubscribedOn>2017-07-21T00:00:00Z</UnsubscribedOn>
       </RemovedSubscriber>
       <RemovedSubscriber>
         <Id>123</Id>
         <Phone>123456789</Phone>
         <ListId>1</ListId>
         <UnsubscribedOn>2017-07-21T00:00:00Z</UnsubscribedOn>
       </RemovedSubscriber>
       <RemovedSubscriber>
         <Id>456</Id>
         <Email>test456@yahoo.com</Email>
         <ListId>1</ListId>
         <UnsubscribedOn>2017-08-02T11:37:20Z</UnsubscribedOn>
       </RemovedSubscriber>
       <RemovedSubscriber>
         <Id>456</Id>
         <Phone>111222333</Phone>
         <ListId>1</ListId>
         <UnsubscribedOn>2017-09-15T04:10:00Z</UnsubscribedOn>
       </RemovedSubscriber>
   </Data>
</ApiResponse>

Request with “Customs” option

Request:

GET http://api.esv2.com/v2/Api/RemovedSubscribers?apiKey=test_api_key1&startDate=2016-05-01&option=Customs HTTP/1.1
Accept-Encoding: gzip,deflate
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Date: Fri, 15 Jul 2016 10:36:47 GMT
Content-Length: 2866

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Data>
    <RemovedSubscribers>
      <RemovedSubscriber xsi:type="FullRemovedSubscriber">
        <Id>123</Id>
        <Email>test123@yahoo.com</Email>
        <ListId>1194</ListId>
        <UnsubscribedOn>2016-06-21T08:33:34Z</UnsubscribedOn>
        <Properties>
          <Property>
            <Id>1</Id>
            <Source>NotSet</Source>
            <StringValue xsi:type="xsd:string">abc</StringValue>
            <Type>Text</Type>
            <FriendlyName>tekst</FriendlyName>
            <Description>tekstowa cecha xxx</Description>
            <Name>tekst</Name>
            <DefaultStringValue xsi:type="xsd:string">abc</DefaultStringValue>
          </Property>
          <Property>
            <Id>9</Id>
            <Source>NotSet</Source>
            <IntValue xsi:type="xsd:int">1</IntValue>
            <Type>Boolean</Type>
            <FriendlyName>testowy boolean "fifi"</FriendlyName>
            <Description>to jest test</Description>
            <Name>test_bool</Name>
            <DefaultIntValue xsi:type="xsd:int">1</DefaultIntValue>
          </Property>
          <Property>
            <Id>23</Id>
            <Source>NotSet</Source>
            <DecimalValue xsi:type="xsd:decimal">3.14</DecimalValue>
            <Type>Money</Type>
            <FriendlyName>kwota</FriendlyName>
            <Description />
            <Name>kwota</Name>
            <DefaultDecimalValue xsi:type="xsd:decimal">3.14</DefaultDecimalValue>
          </Property>
        </Properties>
        <Firstname />
        <Lastname />
        <Ip />
        <Vendor />
      </RemovedSubscriber>
    </RemovedSubscribers>
  </Data>
</ApiResponse>