Przejdź do treści

Add subscriber

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:

ParameterTypeNotes
ApiKeystringYour API key. Required for authentication.
ReturnDatabooleanIf set to „true” (note the lowercase!), additional information will be returned for each added subscriber. Especially useful with MultiData.
VerboseErrorsbooleanIf set to “true” (note the lowercase!), errors will be returned in verbose way. See examples.
DatacomplexObject containing subscriber information. Required, unless you are adding multiple subscribers using MultiData element instead.
MultiDatacomplexObject 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/attributeTypeNotes
xsi:type–Describes type of manipulated data. Value should always be “Subscriber” for this request
ModestringAdding mode. See below for list of supported modes.
Optional. Defaults to “AddAndUpdate”
ForcebooleanIf 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”.
ListIdintegerIdentifier of list the subscriber is added to.
Required.
AllowUnsubscribedbooleanIf set to „false” (note the lowercase!), the system will not allow adding subscribers that previously unsubscribed from the system. Default is „true”.
AllowRemovedbooleanIf 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”.
MatchingModestringSubscriber’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.
IdintegerSubscriber’s unique identifier. Optional. * Read note below this table
EmailstringSubscriber’s email. Optional. * Read note below this table
EmailMd5stringSubscriber’s MD5. Optional. * Read note below this table
EmailSha256stringSubscriber’s SHA256. Optional. * Read note below this table
PhonestringSubscriber’s phone number (available only if unit has access to SMS channel). Optional. ** Read note below this table
CustomSubscriberIdstringSubscriber’s custom ID. Optional.
CustomChannelIdstringSubscriber’s custom channel ID. Max 256 char. Optional.***
FirstnamestringSubscriber’s firstname. Optional.
LastnamestringSubscriber’s lastname. Optional.
TrackingCodestringIdentifier of source of subscriber (e.g. particular webform on a webpage). Optional.
NamestringFull name. Can be used when separate data for firstname and lastname is not available. It will be matched against following template: “Firstname Lastname”.
VendorstringIdentifier/name of traffic vendor the subscriber came from. Optional.
IpstringIP address of subscriber. Optional.
PropertiescomplexCollection of custom subscriber properties (Property elements). Optional.
SpamDecoystringA 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. 
DisableConfirmationEmailbooleanIf 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:

ModeBehavior
AddAndUpdateAdd new subscribers and update custom fields of subscribers existing on the list.
AddAndReplaceAdd new subscribers and replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).
AddAndIgnoreAdd new subscribers and do not update or replace custom fields of subscribers existing on the list.
IgnoreAndUpdateDo not add new subscribers, only update custom fields of subscribers existing on the list.
IgnoreAndReplaceDo 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/attributeTypeNotes
IdintegerIdentifier of predefined subscriber property. Required
ValuemixedProperty 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 typeAllowed xsi:typeExample values
Textxs:stringthis is a test, foobar
Numberxs:integer12345
Moneyxs:decimal, xs:integer123.45, 123
Datexs:date1985-03-12 **
Datetimexs:dateTime, xs:date1985-03-12T12:00:00
Booleanxs:booleantrue, false, 1, 0
Urlxs:stringhttp://www.domain.com/page.html
SingleSelectxs:stringvalue1, 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/attributeTypeNotes
MultiDatacomplexCollection 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/attributeTypeNotes
ErrorMessagecomplexObject containing error information.

ErrorMessage element children:

Element/attributeTypeNotes
CodeintegerError code, e.g. „400”.
MessagescomplexList of error messages.

Messages element children:

Element/attributeTypeNotes
MessagecomplexObject containing error information.

Message element children:

Element/attributeTypeNotes
forstringIndicates subscriber’s identifier (ID, email, phone, custom subscriber ID) the error is connected with. XML attribute.
(content)stringError message. XML element content. 

OK response with ReturnData=true:

ApiResponse element children:

Element/attributeTypeNotes
DatacomplexAn array of SubscriberData elements.

Data element children:

Element/attributeTypeNotes
SubscriberDatacomplexAn object containing information about single subscriber.

SubscriberData element children:

Element/attributeTypeNotes
EmailstringSubscriber’s email. Returned always for unit without SMS channel. Returned only if exists for units with SMS channel.
IdintegerSubscriber’s ID – returned only if subscriber was added or was already on the list. 
PhonestringSubscriber’s phone number. Returned only if exists for units with SMS channel.
CustomSubscriberIdstringSubscriber’s custom ID. Returned only if exists.
WasAddedbooleanFlag indicating if subscriber was added to the list.
WasIgnoredbooleanFlag 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>
Polityka prywatności
Na tej stronie
Do góry