Introduction
The new Esendex API (application programming interface) is simple, lightweight and built on simple and established standards that reduce the need for special toolkits. This allows Esendex to support a wider range of programming languages more easily than ever before.
The supporting document describes the ‘RESTful’ approach the API offers to the business messaging services provided by Esendex. It is intended to provide all the information required to get started using the API. The Esendex API documentation is available to download as a PDF.
Esendex API Documentation
The Esendex API has been based on the REST architectural style and has been implemented on the HTTP protocol. It uses the standard HTTP methods of GET, POST, PUT and DELETE to interact with a set of defined resources. The requests made to and the responses from the REST API are UTF-8 encoded XML representations.
In order to use the Esendex API, the following items are required:
- An active internet connection
- Handling for HTTP Request / Response objects
- XML Parsing functionality
HTTP Methods
There are four main HTTP methods or verbs which are used to interact with the Esendex API. These are GET, POST, PUT and DELETE.
The use of these verbs describes operations on a resource in the following manner:
- GET: Retrieves a representation of the requested resource (current state)
- POST: Create a new instance of a resource
- PUT: Update an existing instance of a resource
- DELETE: Remove an existing instance of a resource
Quick Start
The two basic tasks of sending and receiving messages are introduced here to help quickly identify the Resource required to carry out these core operations.
Using the Esendex API
Each interaction with the Esendex API follows the same basic steps:
- Collect any data needed to make the request.
- Build an HTTP Request. Be sure to include the Authentication header and any additional data parameters.
- Invoke the HTTP Request to the appropriate Resource URI using a supported HTTP method.
- Retrieve the HTTP Response and parse it.
- If appropriate, use the response data to continue performing other operations.
Sending Messages
To send messages, you will need to use the Message Dispatcher resource. Each message that is sent successfully through Esendex will be assigned a unique GUID (globally unique identifier) value. This ID can be used to retrieve the message details later including its delivery status through the Message Headers resource.
Receiving Messages
To receive messages, you can either ‘pull’ (retrieve) messages from the Inbox resource or make use of the Account Event Handler push notification mechanism.
For example, retrieving your inbox messages is as simple as making a GET request to http://api.esendex.com/v1.0/inbox/messages
