Data format

GET requests are simple. All required data should be provided inside URL using standard GET syntax.

For most other methods, all request data should be provided in XML format. Responses are also generated as XML data.

For example, POST requests with XML data should be constructed so POST request body contains XML. Content type for such request should be set to text/xml.

Authentication

To access ExpertSender API, you must provide your API key with every request. API key is a random string of numbers and letters and is generated for every account in ExpertSender system.

You can get your API key from “Service Settings > API” page in ExpertSender system. API key is unique to you and providing it automatically identifies you in the system.

API key should be provided as URL parameter (for GET requests) or in request XML body (for other methods: see Request for details).

IMPORTANT: all examples in the API doc need to be modified to include your correct API server and API key.

Request

Request body should be XML, UTF-8 encoded, without XML header (<?xml…), for example:

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <ApiKey>YOUR_API_KEY_HERE</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 is composed of two parts:

1. ApiKey – this is your API key, required for authentication
2. Data – this is the request data. Its contents may vary, depending on resource that is manipulated. Data type should always be specified using xsi:type attribute.

Response

Response XML data is provided if any data is to be returned (mostly for GET methods) or in case of error. The response content-type is set to text/xml and response body contains XML. The format is as below:

Correct response:

<ApiResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Data xsi:type="...">
    ...
  </Data>
</ApiResponse>

Data element type and content depends on type of resource accessed (see below for details for different resources).

Error response:

<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 code (consisting with returned HTTP response code) is returned as well as human-readable error message.