MENU
Rich Content API
This API allows you to send richer content (images, buttons, files) using multiple communication channels.
Prerequisites
Your account must be allowed to send Rich Content.
Please ask your account manager to give you access to the Rich Content API.
Channels
SMS
SMS is the channel available by default. Sending a message that contains rich content via SMS will result in the rich content platform creating a landing page to display your content. You will be able to customise the link that is displayed in the SMS to match your branding.
RCS
RCS can be used in conjunction with SMS or as the sole channel. When used with SMS, the channels will be attempted in order and the platform will send only once to the first compatible channel. For example a request with the channel "RCS" will attempt to look up the Esendex account's RCS agent before sending. If the agent has been set up, and the recipient is capable of RCS the message will be delivered over RCS.
WhatsApp is now available via the Rich Content API in preview mode. Once we have registered your account as an official WhatsApp business account you can set the channels object to ["WhatsApp"]. The channels object does not currently support combining WhatsApp with RCS/SMS. Please discuss with your account manager to find out more.
Authentication
First time setup
- Access the Esendex developer console https://console.esendex.com
- Sign in using your normal Esendex credentials.
- Ensure your user has a subscription to the Rich Content Product
- Retrieve your Rich Content Primary Key from your Developer Profile
Send a text message
Request sample
POST https://connect.esendex.com/richcontent/v3/send
Authorization: YOUR_PRIMARY_KEY
Content-Type: application/json
Request Body
{
"accountReference": "{ESENDEX_ACCOUNT_REFERENCE}",
"channels": [
"SMS"
],
"metadata":{
"key": "value"
},
"recipient": {
"variables": {
"name": "Fred"
},
"address": {
"msisdn": "{INTERNATIONALISED_PHONE_NUMBER}"
}
},
"content": {
"body": {
"text": {
"value": "Hello [[name]]"
}
}
},
"channelSettings": {
"sms": {
"originator": "{MESSSAGE_ORIGINATOR}",
"characterSet": "GSM"
}
},
"expiry": "30"
}
For more information, see Send Request Elements and Send Responses.
Send a Messaging Studio template
Request sample
POST https://connect.esendex.com/richcontent/v3/send
Authorization: YOUR_PRIMARY_KEY
Content-Type: application/json
Request Body
{
"accountReference": "{ESENDEX_ACCOUNT_REFERENCE}",
"channels": [
"SMS"
],
"metadata":{
"key": "value"
},
"recipient": {
"variables": {
"name": "Fred"
},
"address": {
"msisdn": "{INTERNATIONALISED_PHONE_NUMBER}"
}
},
"content": {
"templateId": "{TEMPLATE_ID}"
}
}
For more information, see Send Request Elements and Send Responses.
Send Request Elements
Request Body
| Property | Description |
|---|---|
| accountReference | Your Esendex account reference which was whitelisted for the Rich Content Platform on sign up (e.g. EX000000) |
| channels | See the section on channels |
| metadata | Metadata is used to provide any additonal data with your message that we will then post back to you in all webhook events relating to this message |
| recipient.address.msisdn | This should be set to a MSISDN in E.164 internationalised format. |
| recipient.variables | Key-Value pairs that will be substituted in to the message body before sending. See below for more details. |
| content | The message content to send |
| content.templateId | The ID (not name) of your Messaging Studio template. Retrieve your template Id |
| channelSettings.sms.originator | This value will appear as the sender of the SMS message. |
| channelSettings.sms.characterSet | The character set used to send SMS messages. Valid values are: GSM or Unicode or Auto. When using Auto the character set is detected automatically.What are GSM and Unicode? |
| expiry | This is the number of days that data for this send will be kept for. After this time, no data for this send will be available from the rich content platform. |
Template ID
To retrieve your template ID
- Sign into https://studio.esendex.com
- Locate your template and click the edit button
- Retrieve the template ID from the URL
In this example, the template ID is d055fa56-fca1-4097-8a47-9b361ab62d57
Recipient Variables
Variables allow you to specify placeholders within your message body to be replaced by a value of your choice. The key for your placeholder can be anything you choose, but it can be useful to have them named relevant to the data they are representing.
Example Text Variable Usage
{
"recipient": {
"variables": {
"first_name": "John",
"last_name": "Smith"
},
"address": {
"msisdn": "+447123456789"
}
},
"content": {
"text": "Hello [[first_name]] [[last_name]]"
}
}
Variables can also be used to specify values within more complex body components. When creating a template with calendar buttons in Studio, you can choose to have the start and end date as variables.
Here you can also specify a custom name for the variables, in case the template contains more than one calendar button
Once your template contains calendar button variables, you can provide values in the recipient, just like you would for text variables. It's important to note that the dates used for calendar buttons must be in the UTC timezone, and in the format yyyy-mm-ddThh:mm:ssZ.
Example Calendar Button Variable Usage
{
"recipient": {
"variables": {
"calendar_test_start": "2019-01-01T12:00:00Z",
"calendar_test_end": "2019-01-01T14:00:00Z"
},
"address": {
"msisdn": "+447123456789"
}
},
"content": {
"templateId": "194edbcb-f5ca-459a-b368-59d35e5a0cb1"
}
}
E.164 MSISDN Format
The telephone number of the message recipient must be in E.164 format. This means the number must be in the format:
+{Country Dial Code}{Rest of phone number}
Examples
| Phone Number | Country | Dial Code | E.164 Formatted Number |
|---|---|---|---|
| 07948751633 | UK | 44 | +447948751633 |
| 0123456789 | France | 33 | +33123456789 |
| 912345678 | Spain | 34 | +34912345678 |
| 0491570156 | Australia | 61 | +61491570156 |
| 5417543010 | USA | 1 | +15417543010 |
Send Responses
Successful Response
HTTP Status Code: 202 Accepted
Example Response Body
Content-Type: application/json
{
"gatewayId": "720cf6cb-9d65-4891-a40a-f93b275f0230"
}
Gateway ID
The Gateway ID, returned from the API when submitting a message, is your reference to the message. It is highly recommended to store this, as it can be used to retrieve the status of your message, and also acts as a request ID. Providing your Gateway ID when contacting support can help us understand more about what happened to your message.
Error Responses
HTTP Status Code: 400 Bad Request
If there are validation errors in the request the API will return a 400 BAD REQUEST response containing all errors to be rectified by the consumer.
Example Response Body
Content-Type: application/json
{
"gatewayId": "f0dcb290-cfcf-4f03-8fec-8beb9f55a609",
"errors": [
{
"error": "Channels must be SMS or RCS",
"code": "channels_invalid"
}
]
}
| HTTP Status Code | Reason |
|---|---|
| 401 Unauthorized | Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription. |
| 422 Unprocessable Entity | The request was not valid JSON and could not be validated. |
| 502 Bad Gateway / 503 Service Unavailable | There is a temporary problem contacting the API. Retry the request. |
Get the status of a message
GET https://connect.esendex.com/richcontent/v3/accounts/{AccountReference}/messages/{GatewayId}
Request sample
GET https://connect.esendex.com/richcontent/v3/accounts/EX0000123/messages/2f77cb1a-15ae-48d7-a80e-5223f47f4366
Authorization: YOUR_PRIMARY_KEY
Send Status Responses
Successful Response
HTTP Status Code: 200 OK
Example Response Body
Content-Type: application/json
{
"gatewayId": "2f77cb1a-15ae-48d7-a80e-5223f47f4366",
"status": "Delivered",
"channel": "rcs",
"recipient": {
"address": {
"msisdn": "+447123456789"
}
},
"lastUpdatedUtc": "2019-05-28T09:47:21Z",
"events": [
{
"metaData": {
"customButtonKey1": "value1",
"customButtonKey2": "value2"
},
"type": "Clicked",
"occurredAt": "2019-10-09T02:29:37Z"
},
{
"type": "Read",
"occurredAt": "2019-10-09T02:29:27Z"
},
],
"metadata": {
"customKey1": "value1",
"customKey2": "value2"
},
}
Response body breakdown
| Property | Description |
|---|---|
| gatewayId | The gateway ID from the response of the original send request |
| status | Message status. Values: Submitted, Delivered, Failed |
| reason | Failure reason. Only present if status is Failed |
| channel | Communication channel used to send the message. Lowercase. See channels |
| recipient.address.msisdn | Formatted recipient phone number. See E.164 MSISDN Format |
| events | Analytics events associated to the message (e.g. Read, Clicked) |
| lastUpdatedUtc | The UTC date & time when the message reached this status |
Error Responses
| HTTP Status Code | Reason |
|---|---|
| 400 Bad Request | Your request must contain the expected properties with acceptable data. Will include an error message explaining the problem. |
| 401 Unauthorized | Your request must contain a valid subscription key. You must have access to the account. The account must have access to the rich content platform. |
| 404 Not found | The send cannot be found. |
| 429 Too many requests | Number of requests has exceeded allowance. Please wait and try again. |
| 502 Bad Gateway / 503 Service Unavailable | There is a temporary problem contacting the API. Retry the request. |
Webhooks
Use webhooks to track the status of a message
Esendex's Webhooks system delivers events directly to your applications, letting you know when something has happened, such as a customer sending you a message. They can be used to create conversational experiences for your customers and advanced reports on customer engagement.
Prerequisites
Webhooks has restricted access. Please contact your account manager if you wish to use this feature.
First time setup
- Navigate to https://console.esendex.com/products
- Sign in using your normal Esendex credentials.
- Check that you have a subscription to the Webhooks Product
- Retrieve your Webhooks Subscription Key from your Developer Profile
Create a subscription
Request sample
POST https://connect.esendex.com/webhooks/v1/accounts/{accountReference}/subscriptions
Authorization: Your webhooks subscription key
Body
Content-Type: application/json
{
"productId": "richcontentapi",
"eventId": "failed",
"endpoints": [
{
"type": "HTTP",
"uri": "https://example.com/callback"
}
],
"notificationEmails": ["[email protected]"]
}
| Property | Description |
|---|---|
| productId | The product containing the event you wish to receive. |
| eventId | The specific event you wish to receive. |
| endpoints | An array of endpoints to receive events |
| endpoints[...].type | Must be "HTTP" |
| endpoints[...].uri | The publicly accessible web address for webhooks to send events to |
Successful Response
HTTP Status Code: 200 OK
Example Response Body
Content-Type: application/json
{
"productId": "richcontentapi",
"eventId": "failed",
"version": "1",
"endpoints": [{
"type": "HTTP",
"status": 0,
"uri": "https://example.com/callback"
}],
"notificationEmails": ["[email protected]"]
}
List existing subscriptions
GET https://connect.esendex.com/webhooks/v1/accounts/{accountReference}/subscriptions
Authorization: Your webhooks subscription key
Content-Type: application/json
Response body
[
{
"productId": "richcontentapi",
"eventId": "delivered",
"version": "1",
"endpoints": [
{
"type": "default",
"status": 0,
"uri": "https://example.com/callback"
}
],
"notificationEmails": [
"[email protected]"
]
}
]
Remove a subscription
https://connect.esendex.com/webhooks/v1/accounts/{accountReference}/subscriptions/{productId}/{eventId}
Authorization: Your Webhooks Subscription Key
Path parameters
| Property | Description |
|---|---|
| accountReference | Esendex account reference. E.g. EX0001234. |
| productId | The product containing the event you are subscribed to. |
| eventId | The specific event you no longer wish to receive |
Successful Response
200 OK
Types of events
Below are the payloads for the different types of events that your application can receive. When your application receives a webhook, it will receive an array of events.
Example
[
{
"productId": "richcontentapi",
"eventId": "delivered",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
...
}
},
{
"productId": "richcontentapi",
"eventId": "delivered",
"eventVersion": "1",
"eventTime": "2020-07-07T17:18:12Z",
"data": {
...
}
}
]
Rich content API message events
productId: richcontentapi
These events are related to a message that you have sent through the Rich Content API. Messages sent through Studio or Chat will not result in message events.
When your application sends a message, the Rich Content API response will contain a gatewayId property.
{
"gatewayId": "720cf6cb-9d65-4891-a40a-f93b275f0230"
}
This identifier will also be present on message events, allowing your application to relate these events to the message you sent.
Delivered
You will receive this event when a message is delivered to the recipient.
{
"productId": "richcontentapi",
"eventId": "delivered",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"gatewayId": "076911ca-8db5-4839-9e45-cf660ec59a92",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"metadata": {},
"recipient": {
"address": {
"msisdn": "+447123456789"
}
},
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
Failed
You will receive this event when we are unable to deliver a message.
{
"productId": "richcontentapi",
"eventId": "failed",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"gatewayId": "076911ca-8db5-4839-9e45-cf660ec59a92",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"errorCode": "RC001",
"description": "Account-level error",
"metadata": {},
"recipient": {
"address": {
"msisdn": "+447123456789"
}
},
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
Failure reasons It is possible we may add more failure reasons in the future. You should write your application such that it can handle failure reasons that it does not recognise.
| errorCode | Description | Details |
|---|---|---|
| RC000 | Platform error | An unknown error has occurred. Please contact support. |
| RC001 | Account-level error | This occurs when something is wrong with your account's configuration. Please contact your account manager. |
| RC002 | Insufficient balance | You have run out of credits and cannot send any more messages down this channel. |
| RC003 | Network provider-level error | The network is unable to deliver the message to this recipient. The recipient may not be reachable. |
| RC004 | Message expired | We were unable to deliver your message after multiple attempts. We will no longer try to deliver the message. |
| RC005 | Recipient has opted out | This recipient has opted out of receiving messages from you. Retrying will not help. |
| RC006 | Platform error | An unknown error has occurred. Please contact support. |
| RC007 | Out of session | The session for this recipient has expired. You must send a pre-approved template, or wait for the recipient to contact you first. |
| RC008 | The message could not be delivered to the phone number. The recipient may not have a WhatsApp client | This recipient cannot be reached over WhatsApp. |
| RC009 | Messaging this recipient is temporarily restricted. | A product, such as a chatbot, has temporarily restricted other sources from messaging this recipient. Try again later. |
Read
When an RCS/WhatsApp message has been read, or an SMS landing page has been opened.
{
"productId": "richcontentapi",
"eventId": "read",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"gatewayId": "076911ca-8db5-4839-9e45-cf660ec59a92",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"metadata": {},
"recipient": {
"address": {
"msisdn": "+447123456789"
}
},
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
Clicked
When a rich card button has been clicked.
In order to identify which button has been clicked, consider setting Metadata on your rich card buttons.
{
"productId": "richcontentapi",
"eventId": "clicked",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"gatewayId": "076911ca-8db5-4839-9e45-cf660ec59a92",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"metadata": {},
"recipient": {
"address": {
"msisdn": "+447123456789"
}
},
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
Account events
productId: account
Inbound
This event occurs when a message is sent to your account over SMS, RCS, etc.
Text
{
"productId": "account",
"eventId": "inbound",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"from": "+447123456789",
"text": "Hello! This is an inbound message",
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
File
{
"productId": "account",
"eventId": "inbound",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"from": "+447123456789",
"file": {
"url": "https://www.example.com/fakeimage.jpg",
"sizeBytes": 12345,
"contentType": "jpeg"
},
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
Stop
This occurs when a recipient has requested that you no longer send them messages.
{
"productId": "account",
"eventId": "stop",
"eventVersion": "1",
"eventTime": "2020-07-07T17:16:42Z",
"data": {
"accountReference": "EX0123456",
"messageId": "23c4cb4c-9eaf-4326-9495-bda7e87c4e08",
"from": "+447123456789",
"text": "Stop",
"channel": "sms",
"occurredAt": "2020-07-07T17:16:40Z"
}
}
Surveys API
Send Survey
The Send Survey endpoint allows you to send a survey to a specified recipient, you must supply content for all template fields required by your survey. Requests can be made in either JSON or XML.
Request
Method: POST
Authentication: Basic / Session
https://surveys.api.esendex.com/v1.0/surveys/d89f6514-268c-43de-bb99-d676311aad63/send
Example Request Body
Content-Type: application/json
{
"recipients": [
{
"phonenumber": "447700900123",
"templatefields": {
"Name": "John Doe",
"City": "Nottingham"
},
"metadata": {
"Customer Number" : "12345"
}
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<recipients xmlns="http://api.esendex.com/ns/">
<recipient>
<phonenumber>447700900123</phonenumber>
<templatefields>
<templatefield>
<name>Name</name>
<value>John Doe</value>
</templatefield>
<templatefield>
<name>City</name>
<value>Nottingham</value>
</templatefield>
</templatefields>
<metadata>
<metadataitem>
<name>Customer Number</name>
<value>12345</value>
</metadataitem>
</metadata>
</recipient>
</recipients>
Successful Response
HTTP Status Code: 200 OK
Error Responses
If a request is missing mandatory template fields, the following response will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "templatefields_missing",
"description": "Template fields that are required by this Survey were not supplied",
"values": ["Name", "Age"]
}
]
}
Content-Type: application/xml
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>templatefields_missing</code>
<description>Template fields that are required by this Survey were not supplied</description>
<values>
<value>Name</value>
<value>Age</value>
</values>
</error>
</errors>
</response>
If a request contains an invalid phone number, the following response will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "phonenumber_invalid",
"description": "Phone number is invalid"
}
]
}
Content-Type: application/xml
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>phonenumber_invalid</code>
<description>Phone number is invalid</description>
</error>
</errors>
</response>
If a request does not have a phone number, the following response will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "phonenumber_missing",
"description": "Phone number is missing"
}
]
}
HTTP Status Code 400
Content-Type: application/xml
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>phonenumber_missing</code>
<description>Phone number is missing</description>
</error>
</errors>
</response>
If the survey provided in the request is inactive, the following response will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "survey_inactive",
"description": "Survey is no longer active"
}
]
}
Content-Type: application/xml
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>survey_inactive</code>
<description>Survey is no longer active</description>
</error>
</errors>
</response>
If the data provided for a recipient exceeds 5000 characters, the following error will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "recipient_too_large",
"description": "Recipient data is greater than 5000 characters"
}
]
}
Content-Type: application/xml
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>recipient_too_large</code>
<description>Recipient data is greater than 5000 characters</description>
</error>
</errors>
</response>
| HTTP Status Code | Reason |
|---|---|
401 Not Authorised |
No authentication header provided. |
403 Forbidden |
Failed authentication or not authorised to access feature. |
404 Not Found |
Survey doesn't exist. |
413 Payload Too Large |
Request contains more than one recipient. |
415 Unsupported Media Type |
Content type is not supported or unspecified. |
Standard Report
The Standard Report endpoint allows you to download a report for the data collected through a survey.
Request
Method: GET
Authentication: Basic / Session
https://surveys.api.esendex.com/v1.0/surveys/d89f6514-268c-43de-bb99-d676311aad63/report/standard
Optional Parameters You can provide optional start and end date parameters for the report. The dates will correspond to either when a question was sent or when an answer was received. Providing just a start date will return data from the start date to 35 days after this date. Providing just an end date will return data from 35 days prior to that date until the end date. If no dates are provided then the report will default to return all questions sent within the last 35 days.
| Parameter | Description |
|---|---|
questionsentafter=yyyy-MM-ddTHH:mm:ssZ |
The start of the date range for when questions were sent out. |
questionsentbefore=yyyy-MM-ddTHH:mm:ssZ |
The end of the date range for when questions were sent out. |
answerreceivedafter=yyyy-MM-ddTHH:mm:ssZ |
The start of the date range for when answers were received. |
answerreceivedbefore=yyyy-MM-ddTHH:mm:ssZ |
The end of the date range for when answers were received. |
The format is yyyy-MM-ddThh:mm:ssZ where y=year, M=month, d=day, T=separator, h=hour, m=min and s=seconds. The value is treated as per ISO 8601 semantics, e.g. without time zone information the value is assumed to be the local time of the server, otherwise as an offset from UTC with Z representing a UTC time.
Successful Response
HTTP Status Code: 200 OK
Example Response Body
Content-Type: application/json
{
"rows": [
{
"phonenumber": "44123456789",
"status": "Delivered",
"questionlabel": "1",
"questiondatetime": "2016-11-24T08:15:36.163",
"answerlabel": "Yes",
"answerdatetime": "2016-11-24T08:20:51.1",
"answertext": "Yes",
"recipientdata": {}
},
{
"phonenumber": "448811772212",
"status": "Delivered",
"questionlabel": "1",
"questiondatetime": "2016-12-01T14:25:57.677",
"answerlabel": null,
"answerdatetime": null,
"answertext": null,
"recipientdata": {
"FirstName": "John",
"LastName": "Smith",
"FavoriteFruit": "Kiwi"
}
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<rows xmlns="http://api.esendex.com/ns/">
<row>
<phonenumber>44123456789</phonenumber>
<status>Delivered</status>
<questionlabel>1</questionlabel>
<questiondatetime>2016-11-24T08:15:36.163</questiondatetime>
<answerlabel>Yes</answerlabel>
<answerdatetime>2016-11-24T08:20:51.1</answerdatetime>
<answertext>Yes</answertext>
<recipientdata />
</row>
<row>
<phonenumber>448811772212</phonenumber>
<status>Delivered</status>
<questionlabel>1</questionlabel>
<questiondatetime>2016-12-01T14:25:57.677</questiondatetime>
<answerlabel d3p1:nil="true" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance" />
<answerdatetime d3p1:nil="true" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance" />
<answertext d3p1:nil="true" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance" />
<recipientdata>
<recipientdataitem>
<key>FirstName</key>
<value>John</value>
</recipientdataitem>
<recipientdataitem>
<key>LastName</key>
<value>Smith</value>
</recipientdataitem>
<recipientdataitem>
<key>FavoriteFruit</key>
<value>Kiwi</value>
</recipientdataitem>
</recipientdata>
</row>
Error Responses
If a request uses an invalid combination of date parameters, the following response will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "mismatched_date_range",
"description": "Must supply matching pair of date times for either questions sent or answers received"
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>mismatched_date_range</code>
<description>Must supply matching pair of date times for either questions sent or answers received</description>
</error>
</errors>
</response>
If the date range provided spans more than 35 days, the following response will be receieved:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "date_range_too_long",
"description": "Date range must be 35 days or fewer"
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>date_range_too_long</code>
<description>Date range must be 35 days or fewer</description>
</error>
</errors>
</response>
If the specified date range includes time in the future, the following response will be received:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "date_in_future",
"description": "Cannot download report for dates in future"
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>date_in_future</code>
<description>Cannot download report for dates in future</description>
</error>
</errors>
</response>
If a date range is requested with the dates the wrong way around, the following response will be receieved:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "date_range_invalid",
"description": "Start date must be before end date"
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>date_range_invalid</code>
<description>Start date must be before end date</description>
</error>
</errors>
</response>
If a date range is requested that contains either 3 or 4 date parameters, the following response will be receieved:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "invalid_number_of_dates",
"description": "Must supply date times for only questions sent or answers received"
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>invalid_number_of_dates</code>
<description>Must supply date times for only questions sent or answers received</description>
</error>
</errors>
</response>
If any datetime parameters included in the request couldn't be parsed, the following response will be receieved:
HTTP Status Code: 400
Content-Type: application/json
{
"errors": [
{
"code": "invalid_date",
"description": "Could not parse datetime"
}
]
}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://api.esendex.com/ns/">
<errors>
<error>
<code>invalid_date</code>
<description>Could not parse datetime</description>
</error>
</errors>
</response>
| HTTP Status Code | Reason |
|---|---|
401 Not Authorised |
No authentication header provided. |
403 Forbidden |
Failed authentication or not authorised to access feature. |
404 Not Found |
Survey doesn't exist. |
413 Payload Too Large |
Request contains more than one recipient. |
415 Unsupported Media Type |
Content type is not supported or unspecified. |