Skip to content

Get removed subscribers

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:

ParameterTypeNotes
apiKeystringYour API key, required for authentication. Required.
listIdsint (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
removeTypesstring (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.
startDatedateStart 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.
endDatedateSee startDate.
optionstringOptional. If specified, additional subscriber information will be returned. Valid values:
Customs – Return all subscriber properties and some general information
channelstringLimits returned data to selected channel. Optional. Defaults to Email. Valid values:
AllEmailSmsMms

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:

ValueDescription
OptOutLinkSubscriber clicked unsubscribe link in email.
UiRemoved manually using user interface (ExpertSender panel).
BounceLimitRemoved because limit of bounced messages was reached.
ComplaintSubscriber issued a spam complaint
UserUnknownRemoved because email server returned User Unknown bounce (email address does not exist).
ApiRemoved using API.
SyncImportRemoved 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/attributeTypeNotes
RemovedSubscribersarray[complex]Array of RemovedSubscriber elements.

RemovedSubscriber element children:

Element/attributeTypeNotes
IdintSubscriber’s ID
EmailstringEmail of unsubscribed subscriber.
PhonestringPhone number of unsubscribed subscriber.
ListIdintIdentifier of list that subscriber unsubscribed from.
UnsubscribedOndateTimeDate and time of unsubscription.

Additional elements returned with “Customs” option specified:

Element/attributeTypeNotes
CustomSubscriberIdstringSubscriber’s custom ID.
FirstnamestringSubscriber’s firstname.
LastnamestringSubscriber’s lastname.
IpstringSubscriber’s IP address. 
VendorstringVendor code of current subscriber.
Propertiesarray[complex]Array of subscriber’s properties. 

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.

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>
On this page
To top