The MMS API is currently offered using an implementation of the MM7 protocol. MM7 is the standard protocol used to send and receive A2P MMS messages. The protocol is SOAP-based and sent over HTTPS. The MM7 API supports the following API actions:
|MM7_Submit||Send an MMS MT to the device.|
|MM7_Deliver||Receive an MMS MO from the device.|
|MM7_DeliveryReport||Receive a Delivery report for a previously submitted MMS MT.|
The use of our MM7 API is only available for accounts with a paid plan. We support submitting MMS messages with MM7 version 5.3.0 and 6.8.0. Your VASPID will be your API Key. All the traffic must be encrypted in transit via TLS.
Finding your VASPID (API Key)
Your VASPID is your API Key. You must first request access to the API from your account manager. Once the API is turned on, you can find your API Key in your account. Alternatively, your account manager will provide you with the API Key. You can reset the API Key at any time to revoke access.
Finding your API Endpoint
Once the MM7 API is turned on, you can also find the MM7 API URL in your account. You may also obtain the MM7 API endpoint from your account manager.
Receiving Delivery Reports and MOs
Your Delivery Report URL and MO URL are configured in your account. SOAP requests will be forwarded to your URL every second and require an HTTP STATUS 200 and a proper MM7 SOAP Response or else we will retry. You can also turn off the SOAP notifications to your URL if required.
We expect your server to accept our postback within 10 seconds by responding with a standard HTTP STATUS 200 header (success) and proper SOAP Response with matching MM7 TransactionID and Status 1000. If establishing a connection to your Postback URL 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 notification again five minutes later for a maximum of 5 retries per notification.
There are two types of limitations placed on your account. You may be given an API request limit and an account throughput limit. If your API requests exceed the account throughput limit then we will queue the messages for delivery and your messages that exceed the limit may have some latency being delivered. We priority queue messages based on the sending number so that two senders in the same account will be given equal priority. We also optimize queues around different carrier limitations so you may clear certain carrier queues before others if capacity is available. There may also be limits on the number of API calls allowed per second. If you exceed your API request limit then your API request will be rejected with a temporary error code and you will be required to retry the API request later.
We authenticate your account with your VASPID by default. We can optionally whitelist your IP Address or apply a “basic authorization” username and password requirement to your account which adds an additional level of security to your API request.
Always Use International Number Format: You must use an international format when submitting an MM7 message to the system. 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 (eg 00 or 001) or special characters such as the plus symbol when submitting messages. (example: ‘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.
MM7 API Setting and Description
|MM7 Throughput||The MM7 request throughput (per second).|
|Basic AUTH Username/Password||The username/password used for authentication when making an MM7 request.|
|MM7 Version||The MM7 version. Version 5.3.0 or 6.8.0 is supported.|
MM7 API Postback URLs
Your account manager can turn on or off MM7 DLR (MM7_DeliveryReport) and MO (MM7_Deliver) in your account. Once a number is provisioned, these URLs will be activated automatically for that number. These URLs can be the same or different endpoints.