Messaging API V2 Introduction

Making API Requests

Calls to the API are made in the form of HTTP requests using the POST request method with UTF-8 encoded JSON data passed inside the request body. All v2 API requests are expected to include a content-type HTTP header:

Content-Type: application/json; charset=utf-8

Note: All requests are made to the API URL which can be found in the API Settings of your account.
Please note that future updates to our MMS service may change the API URL. We will provide advance notice of any URL change.

Receiving API Callbacks

Postback notifications from the API v2 – containing, for example, delivery reports – are issued as HTTP requests to the MMS postback URL you have provisioned to your account. Postback notifications are forwarded to your server one by one and require an HTTP STATUS 200 response as acknowledgment.

We expect your server to accept the postback HTTP request we send within 10 seconds by responding with a standard HTTP STATUS 200 header (success). If establishing a connection to your postback URL or your response takes longer than 10 seconds, the connection will time out and be dropped. If the connection times out or the HTTP code is not 200 we will retry the postback notification again approximately five minutes later for a maximum of 5 retries per notification. Postback notifications to your Postback URL are queued and will be sent over a single keep-alive connection as fast as you accept them. Consider storing the raw postback requests and performing any heavy database processing operations later asynchronously for better performance.

Postback notifications use the POST request method and the request body is a UTF-8 encoded JSON document formatted according to the schemas described in this document.

During your onboarding, we will provide you with the host IP addresses from where the postback notification request will originate. If you perform any IP whitelisting or have a firewall configured, these IP addresses must then be granted access to your server hosting the postback URL:

34.198.230.58
34.196.116.219
34.197.248.124

Please note that we may update the postback IP address in the future. You will be notified in advance of any changes.

API Limitations

You will have a throughput limit set on your account. If your API requests exceed the throughput set on your account then messages over that throughput will be queued and forwarded to carriers at a controlled rate. We will attempt to balance your queued messages based on the time it was requested as well as the velocity per originating number. There may also be limits on the number of API calls allowed per second in your account. These limits will be set by us and communicated to you through your account manager. We currently return an ‘API exceeded’ error code E113 when customers exceed the throughput limit and instruct your system to retry. If you receive this error code you should throttle back your request speed or number of connections and retry any rejected API calls with this E113 error code again.

Authentication and Security

Secure access to the API is provided by making the interface available via HTTPS/TLS. Authentication of API calls is done by using the accounts API key as well as IP whitelisting. In case an authentication error takes place, the following error codes are used to indicate the type of error.

Authentication Error codes

E100, E104, E105, E107, E108, E112, E113

Note: Please see API Error Code Reference for additional details.

Special Considerations

Always Use International Number Format.
You must use the international format when sending MMS. International format includes both the country code and the phone number. We use the country code to determine the routing of the message. There should be no dialing prefixes (e.g., 00 or 001) or special characters such as the plus symbol when submitting messages. (e.g., ‘642111111′ not ‘+642111111′)

For example, the US number (774)-319-9144 in international number format would be 17743199144 because the USA country code is 1.

Always set the proper file mime type headers and extensions.
Extensions are optional in the filename as long as the proper MIME type is set in the headers for that content. It is always recommended to use the proper file extension AND set the MIME type header. Query strings are supported for files.