Making API Requests
Calls to the API are made in the form of HTTP requests using the POST request method with UTF-8 encoded XML data passed inside the request body. All v1 API requests are expected to include a content-type HTTP header:
Content-Type: text/xml; charset=utf-8Note: All requests are made to the API URL which can be found in the API Settings.
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 v1 – 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 XML 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, E113Note: 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.
HTTP API PostBack
Certain messaging, email, and wallet API will generate a PostBack notification. Here you can turn on or off certain PostBacks. If you turn a particular PostBack on, make sure to provide the appropriate PostBack URL for the PostBack and press the ‘Save’ button.
PostBack IP Addresses
The following 3 PostBack IP addresses are used for whitelisting:
- 34.198.230.58
- 34.196.116.219
- 34.197.248.124
Settings FAQs
How can I get access to the API for my account?
Contact us to activate the API settings on your account.
How does the HTTP API work?
An HTTP request is sent through an XML POST request.
| Request | Description |
|---|---|
| XML | Use POST to send an XML to the API url. Our server receives the XML and executes the action encoded. The typical structure of the XML is $action $api_key $data1 $data2 … |
| API vars | Description |
|---|---|
| action | The name of the API. For instance, if you want to send an SMS, you would use the sendSMS API and pass the value ‘sendSMS’ in the ‘action’ field. |
| api_key | The api_key is a unique string of characters that identifies the account using the API. All API requests require the api_key to be passed within the ‘api_key’ field. An API key is generated for each account and can be found in the API settings page. |
| data | Each API generally has optional or mandatory data that can be passed within each request. For instance, if you want to send an SMS, you would need to include the phone number to send the SMS to and thus pass the phone number in the ‘to’ field. |
Is HTTPS the only protocol I can use with the API?
No, you may use standard HTTP but we highly recommend that you use HTTPS.
Can I receive API notifications about account activity?
Yes, you can via PostBack notifications. You can receive notifications when someone subscribes or unsubscribes from a campaign. You can also receive notifications upon message receipts or delivery confirmations.
What is SMS/MMS MT DLR?
SMS/MMS MT DLR is for delivery receipts. If you turn these PostBacks on, we will notify you when a message is sent and delivered to an end user.
What are stuck messages?
Stuck MMS messages are messages that the system was unable to process and send. Stuck SMS messages are messages that the system was unable to process the first time and again after the retry period of 5 minutes. Stuck SMS messages may become unstuck during subsequent retries.
Stuck messages indicate there may be some issues such as unreachable gateway server, parse error/sending execution terminated, data missing, or missing/unreachable pass/dynamic image/custom content. The stuck message will be cleared after the queue is cleaned up in 3 days.