Add subscriber - ExpertSender Help Center

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.

For this method, all request data should be provided in XML or JSON format. Responses, depending on the format provided, are also generated as XML or JSON data.

The content type for such a request should be set to text/xml or application/json.

Request format

ApiRequest element children:

Parameter	Type	Notes
ApiKey	string	Your API key. Required for authentication.
ReturnData	boolean	If set to «true» (note the lowercase!), additional information will be returned for each added subscriber. Especially useful with MultiData.
VerboseErrors	boolean	If set to “true” (note the lowercase!), errors will be returned in verbose way. See examples.
Data	complex	Object containing subscriber information. Required, unless you are adding multiple subscribers using MultiData element instead.
MultiData	complex	Object containing multiple subscribers information for adding subscribers in batches. Required, unless you are adding a single subscriber using Data element.

Request data format

Data element children:

Element/attribute	Type	Notes
xsi:type	—	Describes type of manipulated data. Value should always be “Subscriber” for this request
Mode	string	Adding mode. See below for list of supported modes. Optional. Defaults to “AddAndUpdate”
Force	boolean	If set to “true” (note the lowercase!), this parameter will force sending another confirmation email to subscriber. Applies only to Double Opt-In lists and non-confirmed subscribers. Optional. Defaults to “false”.
ListId	integer	Identifier of list the subscriber is added to. Required.
AllowUnsubscribed	boolean	If set to «false» (note the lowercase!), the system will not allow adding subscribers that previously unsubscribed from the system. Default is «true».
AllowRemoved	boolean	If set to «false» (note the lowercase!), the system will not allow adding subscribers that were previously removed from the system by the user. Default is «true».
MatchingMode	string	Subscriber’s matching mode. This field will be used as a primary identifier of a subscriber. Optional. Possible values: Email, CustomSubscriberId, Id, Phone (Phone is available only if unit has access to SMS channel). By default Email value is used when providing only Email, or Phone and Email. By default Phone value is used when providing only Phone. By default Id value is used when providing Id.
Id	integer	Subscriber’s unique identifier. Optional. * Read note below this table
Email	string	Subscriber’s email. Optional. * Read note below this table
EmailMd5	string	Subscriber’s MD5. Optional. * Read note below this table
EmailSha256	string	Subscriber’s SHA256. Optional. * Read note below this table
Phone	string	Subscriber’s phone number (available only if unit has access to SMS channel). Optional. ** Read note below this table
CustomSubscriberId	string	Subscriber’s custom ID. Optional.
CustomChannelId	string	Subscriber’s custom channel ID. Max 256 char. Optional.***
Firstname	string	Subscriber’s firstname. Optional.
Lastname	string	Subscriber’s lastname. Optional.
TrackingCode	string	Identifier of source of subscriber (e.g. particular webform on a webpage). Optional.
Name	string	Full name. Can be used when separate data for firstname and lastname is not available. It will be matched against following template: “Firstname Lastname”.
Vendor	string	Identifier/name of traffic vendor the subscriber came from. Optional.
Ip	string	IP address of subscriber. Optional.
Properties	complex	Collection of custom subscriber properties (Property elements). Optional.
SpamDecoy	string	A special field used to detect spam bots that automatically fill webforms. If you detect a spam bot on your website, you may fill this field with spam content, so it is saved for further analysis and reporting purposes. WARNING! If this field is filled, subscriber will NOT be added to database! Only an attempt will be registered and appropriate error code returned. Do NOT fill this field if you are adding regular subscribers.
DisableConfirmationEmail	boolean	If it is «true» the subscriber will be added to the double opt-in list without email confirmation. Optional.

* 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.).
***Only when custom channel is enabled. Adding a value to this field will subscribe user to a new channel – custom

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:

Mode	Behavior
AddAndUpdate	Add new subscribers and update custom fields of subscribers existing on the list.
AddAndReplace	Add new subscribers and replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).
AddAndIgnore	Add new subscribers and do not update or replace custom fields of subscribers existing on the list.
IgnoreAndUpdate	Do not add new subscribers, only update custom fields of subscribers existing on the list.
IgnoreAndReplace	Do not add new subscribers, only replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).

Property element children:

Element/attribute	Type	Notes
Id	integer	Identifier of predefined subscriber property. Required
Value	mixed	Property value. Required. Type depends of xsi:type attribute (also required). Value type should be consistent with predefined property type.*

* xsi:type should correspond with property type. Providing incorrect value type will result in an error. See the table below for details:

Property type	Allowed xsi:type	Example values
Text	xs:string	this is a test, foobar
Number	xs:integer	12345
Money	xs:decimal, xs:integer	123.45, 123
Date	xs:date	1985-03-12 **
Datetime	xs:dateTime, xs:date	1985-03-12T12:00:00
Boolean	xs:boolean	true, false, 1, 0
Url	xs:string	http://www.domain.com/page.html
SingleSelect	xs:string	value1, value2, M, F*

* 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:

Element/attribute	Type	Notes
MultiData	complex	Collection of Subscriber elements that have the same structure as Data element in request adding a single subscriber.

NOTE: With MultiData, it is possible to return error messages in a verbose mode. See examples below.

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:

Element/attribute	Type	Notes
ErrorMessage	complex	Object containing error information.

ErrorMessage element children:

Element/attribute	Type	Notes
Code	integer	Error code, e.g. «400».
Messages	complex	List of error messages.

Messages element children:

Element/attribute	Type	Notes
Message	complex	Object containing error information.

Message element children:

Element/attribute	Type	Notes
for	string	Indicates subscriber’s identifier (ID, email, phone, custom subscriber ID) the error is connected with. XML attribute.
(content)	string	Error message. XML element content.

OK response with ReturnData=true:

ApiResponse element children:

Element/attribute	Type	Notes
Data	complex	An array of SubscriberData elements.

Data element children:

Element/attribute	Type	Notes
SubscriberData	complex	An object containing information about single subscriber.

SubscriberData element children:

Element/attribute	Type	Notes
Email	string	Subscriber’s email. Returned always for unit without SMS channel. Returned only if exists for units with SMS channel.
Id	integer	Subscriber’s ID — returned only if subscriber was added or was already on the list.
Phone	string	Subscriber’s phone number. Returned only if exists for units with SMS channel.
CustomSubscriberId	string	Subscriber’s custom ID. Returned only if exists.
WasAdded	boolean	Flag indicating if subscriber was added to the list.
WasIgnored	boolean	Flag indicating if subscriber was ignored (depends on adding mode, e.g. AddAndIgnore mode will ignore subscribers already present on the list).

Examples

Request (creating single subscriber) in XML format:

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 single subscriber) in JSON format:

POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1
Content-Type: application/json
User-Agent: Mozilla/5.0
Host: api.esv2.com
Accept-Encoding: gzip, deflate, br
Content-Length: 775

{
   "ApiKey": "YOUR_API_KEY",
   "Data": {
       "Mode": "AddAndUpdate",
       "Force": false,
       "ListId": 4900,
       "Email": "john.smith@domain.com",
       "Firstname": "John",
       "Lastname": "Smith",
       "TrackingCode": 123,
       "Vendor": "xyz",
       "Properties": [
          {
             "Id": 4,
             "Value": "student"
          },
          {
             "Name": "integer",
             "Value": 1985
          },
          {
             "Id": 12,
             "Value": "true"
          },
           {
             "Id": 3,
             "Value": "2012-04-23T18:25:43.511Z"
          }
       ]
    }
 }

Request (creating multiple subscribers) in XML format:

<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>

Request (creating multiple subscribers) in JSON format:

POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1
Content-Type: application/json
Accept: application/json
User-Agent: Mozilla/5.0
Host: api-staging.3xr.pl
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 775

{
   "ApiKey":"YOUR_API_KEY",
   "MultiData":[
      {
         "Mode":"AddAndUpdate",
         "Force":true,
         "ListId":4947,
         "Email":"john.smith@domain.com",
         "Firstname":"John",
         "Lastname":"Smith",
         "TrackingCode":123,
         "Vendor":"xyz",
         "Ip":"11.22.33.44",
         "Properties": [
          {
             "Id": 4,
             "Value": "student"
          },
          {
             "Name": "integer",
             "Value": 1985
          }
       ]
      },
      {
         "Mode":"AddAndUpdate",
         "Force":true,
         "ListId":4947,
         "EmailMd5":"35ef0798f657327e7143f338aaec5e4e",
         "Firstname":"Jane",
         "Lastname":"Doe"
      }
   ]
}

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 in XML format:

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

OK response in JSON format:

HTTP/1.1 201 Created
Cache-Control: private
Access-Control-Allow-Origin: *
Date: Fri, 26 Apr 2024 08:54:54 GMT
Content-Length: 0

Error response in XML format:

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>

Error response in JSON format:

HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Date: Fri, 26 Apr 2024 08:56:18 GMT
Content-Length: 125

{
  "ErrorMessage":
  {
    "Code": 400,
    "Message": "john.smith@domain.com: Email is invalid"
  }
}

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>