Sending Studio Templates

Templates can be built in Studio and sent using a template id via the same account. This provides all the benefits of a template building and editing interface to the Rich Content API.

Request Sample

POST https://connect.esendex.com/richcontent/v3/send

Authorization: YOUR PRIMARY KEY
Content-Type: application/json

Request Body

The templateId can be seen below in the content object.

{
"accountReference": "<ACCOUNT REFERENCE>",
"channels": [
"SMS"
],
"metadata":{
"Key": "value"
},
"recipient": {
"variables": {
"name": "Francesco"
},
"address": {
"msisdn": "<INTERNATIONALISED PHONE NUMBER>"
}
},
"content": {
"templateId": "<TEMPLATE ID>"
}
}

Send Request Elements

Request Body

Below are the available properties and descriptions.

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 (see section below about retrieving your templateId).
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.
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.it
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

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": "720cf6cb-9d65-4891-a40a-f93b275f0230",
"errors": [
{
"error": "Channels must be SMS, RCS or WhatsApp",
"code": "channels_invalid"
}
]
}

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.