Embedded Files
API Documentation V2
Subscribers collection allows adding new subscribers using HTTP POST method. If subscriber you want to add is already present (subscribers have unique emails and unique phone numbers), they are updated.
It is possible to add a single subscriber or multiple subscribers with one request.
Please note that you should not add/update more then 100 subscribers using a single API call.
Request format
Request format
ApiRequest element children:
Request data format
Request data format
Data element children:
* Please note that for adding new subscribers providing Email is required. If you want to update a particular subscriber you should provide only one of Email, EmailMd5 or EmailSha256. If you want to change Email address for a subscriber you have to provide BOTH Email and Id fields.
** If you have SMS channel activated it is possible to provide either Email or Phone number for adding new subscribers. (If you want to update a particular subscriber you should provide only one of Email, EmailMd5, EmailSha256, Phone. If you want to change Email or Phone you should provide one of Email, EmailMd5, EmailSha256, Phone, Id, CustomSubscriberId AND Email or Phone that you want to change.).
WARNING! Please note that each phone number must include country prefix. Except digits it is allowed to enter a plus sign "+", left and right parenthesis "(" ")" or zeros. Regardless of the input the phone number will be saved as an integer that is less than or equal to 20 characters. Here's how sample, valid input numbers will be saved in the database:
+48501228855 = 48501228855
(+48)501228855 = 48501228855
+48 (501) 228855 = 48501228855
0048 501 22 88 55 = 48501228855
Supported adding modes:
Property element children:
* xsi:type should correspond with property type. Providing incorrect value type will result in an error. See the table below for details:
* Single select property will accept only one of predefined values for this particular property.
** Format: YYYY-MM-DD
To add multiple subscribers, use MultiData element instead of Data element:
NOTE: With MultiData, it is possible to return error messages in a verbose mode. See examples below.
Response format
Response format
Usually, this request returns no data. On success, it will return HTTP code "201 Created". We can modify this behavior using two available flags: ReturnData and VerboseErrors.
ReturnData can be used to return additional information about each successfully added subscriber. VerboseErrors will change the format the errors are returned (if any are ancountered).
Error response with VerboseErrors=true:
ApiResponse element children:
ErrorMessage element children:
Messages element children:
Message element children:
OK response with ReturnData=true:
ApiResponse element children:
Data element children:
SubscriberData element children:
Examples
Examples
Request (creating single subscriber):
POST https://api.esv2.com/v2/Api/Subscribers/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.com
Content-Length: 715
<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<ApiKey>test_api_key1</ApiKey>
<Data xsi:type="Subscriber">
<Mode>AddAndUpdate</Mode>
<Force>true</Force>
<ListId>1</ListId>
<Email>john.smith@domain.com</Email>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<TrackingCode>123</TrackingCode>
<Vendor>xyz</Vendor>
<Ip>11.22.33.44</Ip>
<Properties>
<Property>
<Id>2</Id>
<Value xsi:type="xs:string">student</Value>
</Property>
<Property>
<Id>3</Id>
<Value xsi:type="xs:dateTime">1985-03-12</Value>
</Property>
</Properties>
</Data>
</ApiRequest>
Request (creating multiple subscribers):
<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<ApiKey>test_api_key1</ApiKey>
<MultiData>
<Subscriber>
<Mode>AddAndUpdate</Mode>
<Force>true</Force>
<ListId>1</ListId>
<Email>john.smith@domain.com</Email>
<Firstname>John</Firstname>
<Lastname>Smith</Lastname>
<TrackingCode>123</TrackingCode>
<Vendor>xyz</Vendor>
<Ip>11.22.33.44</Ip>
</Subscriber>
<Subscriber>
<Mode>AddAndUpdate</Mode>
<Force>true</Force>
<ListId>1</ListId>
<Email>jane.doe@domain.com</Email>
<Firstname>Jane</Firstname>
<Lastname>Doe</Lastname>
<TrackingCode>456</TrackingCode>
<Vendor>abc</Vendor>
<Ip>22.33.44.55</Ip>
</Subscriber>
</MultiData>
</ApiRequest>
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>
OK response:
HTTP/1.1 201 Created
Cache-Control: private
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 15:35:17 GMT
Content-Length: 0
Error response:
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>Email is invalid;</Message>
</ErrorMessage>
</ApiResponse>
Request (creating multiple subscribers with verbose errors enabled):
POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Content-Length: 513
Host: localapi2-dev
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<ApiKey>test_api_key1</ApiKey>
<VerboseErrors>true</VerboseErrors>
<MultiData>
<Subscriber>
<Mode>AddAndUpdate</Mode>
<ListId>1</ListId>
<Email>john.smith@@domain.com</Email>
</Subscriber>
<Subscriber>
<Mode>AddAndUpdate</Mode>
<ListId>1</ListId>
<Email>jane.doe@domain.com</Email>
</Subscriber>
</MultiData>
</ApiRequest>
Error response (with verbose errors on):
HTTP/1.1 400 Bad Request
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=6df3c82d-189c-4984-b8b2-a5d78bde501d; path=/
X-Powered-By: ASP.NET
Date: Wed, 29 Jul 2015 11:00:50 GMT
Content-Length: 373
<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ErrorMessage>
<Code>400</Code>
<Messages>
<Message for="john.smith@@domain.com">Email is invalid</Message>
<Message for="jane.doe@domain.com">Address is present on your blacklist</Message>
</Messages>
</ErrorMessage>
</ApiResponse>
Request (creating multiple subscribers with ReturnData flag on):
POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Content-Length: 558
Host: localapi2-dev
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<ApiKey>test_api_key1</ApiKey>
<VerboseErrors>true</VerboseErrors>
<ReturnData>true</ReturnData>
<MultiData>
<Subscriber>
<Mode>AddAndUpdate</Mode>
<ListId>1</ListId>
<Email>john.smith@domain2.com</Email>
</Subscriber>
<Subscriber>
<Mode>AddAndUpdate</Mode>
<ListId>1</ListId>
<Email>jane.doe@domain2.com</Email>
</Subscriber>
</MultiData>
</ApiRequest>
OK Response (with ReturnData flag on):
HTTP/1.1 201 Created
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=09987c87-b886-4164-8fad-89d6ab3ef6bb; path=/
X-Powered-By: ASP.NET
Date: Wed, 29 Jul 2015 11:50:48 GMT
Content-Length: 517
<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Data>
<SubscriberData>
<Email>john.smith@domain2.com</Email>
<Id>4238647</Id>
<WasAdded>true</WasAdded>
<WasIgnored>false</WasIgnored>
</SubscriberData>
<SubscriberData>
<Email>jane.doe@domain2.com</Email>
<Id>4238648</Id>
<WasAdded>true</WasAdded>
<WasIgnored>false</WasIgnored>
</SubscriberData>
</Data>
</ApiResponse>
Report abuse