The new ReST API is simple, lightweight and built on simple and established standards, reducing the need for special toolkits. This means Esendex can support a wider range of programming languages more easily than ever before.
Communication between client and server via is HTTP and the data passed between is formatted XML. These webpages are designed to provide you with all the information you require to get you started using the API.
Setup depends greatly upon the development environment being used. The basic funtionality required to integrate with our API is:
- Internet connectivity
- HTTP request/response functionality
- XML parsing functionality
Requests should use a UTF-8 encoding and reponses will similarly be sent with a UTF-8 response encoding.
All requests should also include basic access authentication, which is a standard, commonly used username/password method to authenticate clients on the web.
For successful requests, responses are sent with a 200 status code and if there is a response expected, the content type will be "text/xml".
For unsuccessful requests, an appropriate status code is returned along with an error message; therefore the response content-type will be "text/plain" in this scenario.
Sending Messages
For sending messages you'll need to make use of our Message Dispatcher service. Once you have managed to succesfully submit a message you'll receive a URI for the message (this holds the unique id value for the message). This can be used to retrieve details of the message, including it's delivery status via our Message Header service.
Receive Messages
There are two ways to receive messages from your account. You can either poll our API Inbox service or make use of our Account Event Handler push mechanism.
Other Functionality
You may have noticed the Inbox and Message Header services not returning the entire body text; by default they just return a summary of the message. You may also have noticed an empty body element with a uri attribute; this is the link to the message body text. More information on the Message Body service is also available.
FAQ
What encoding should I submit my XML in?
The XML data submitted to the Esendex API should be in UTF-8 encoding. The responses will similarly be returned in UTF-8.
What are the possible HTTP status codes and their relevant meanings for unsuccesful requests?
- 400 - Bad Request
- 402 - Payment Required
- 403 - Not Authorised
- 404 - Resource Not Found
- 405 - Method not Allowed
- 408 - Request Timed Out
- 500 - Problem with Esendex
- 503 - Server Under Maintenance
Have the expected XML requests/responses been formaly defined?
The XML requests/responses are defined using our custom API schema definitions.
What are the possible statuses of my sent messages?
Possible statuses along with brief definition are below:
- Submitted - being processed by Esendex
- Sent - message has been passed to the Mobile Networks
- Delivered - message has been delivered to the recipient
- Expired - message could not be delievered within the validity period
- Failed - message could not be delievered
- FailedAuthorisation - premium message could not be authorised to this recipient
- Acknowledged - message has been acknowledged by the recipient
- Connecting - voice message is currently being delievered to the customer
- Cancelled - scheduled message has been cancelled
- Scheduled - message is scheduled