Overview
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:
Action | Functionality |
---|---|
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.
Messaging Throughput Limit
The Messaging 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.
API Throttling
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 a ‘Throughput exceeded’ status code 3510 when customers exceed the throughput limit and instruct your system to retry. If you receive this status code you should throttle back your request speed or number of connections and retry any rejected API calls with this 3510 status code again.
Authentication
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.
Special Considerations
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
Setting | 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.