Introduction

Sinch offers MMS capabilities for its customers over the JSON API. On this page, you will find general information on and considerations for the MMS JSON API. For the API reference, click here. For the API status code reference, click here.

Prerequisites

You must first request access to the API from your account manager. Once the API is turned on, your account manager can provide your API Key. The API Key is required in every API call and is passed in the x-api-key custom HTTP header.

Authentication

Secure access to the API is provided by making the interface available via HTTPS. Authentication of API calls is done by using the accounts API key as well as IP whitelisting. Authenticating your API call can be done by passing the account’s API key into the x-api-key header. Each API request must contain the API key passed into the header.

JSON action support

Action	Functionality
`sendmms`	Sends an MMS defined in a JSON schema to a single mobile number.
`savemms`	Stores an MMS defined in a JSON schema. Once saved, the MMS can be used by other functions through its `mms-id`.
`sendsavedmms`	Sends a saved MMS template from a specified account to a single mobile number.

Base URL

The following URL can be used by the JSON API:

Server	URL
General API	https://api.ci.mblox.com/ep/v2/

Content Transcoding

Every MMS created using the JSON API will be transcoded for the destination handset based on your Account Settings. Additionally, any MMS which triggers an SMS Fallback containing a link to the MMS content hosted on a web page is optimized for the mobile web browser. To transcode a binary MMS, we must know what type of handset the user has. We are able to obtain this handset type information from delivery receipts, and we store the record in a handset cache for later use. We have a database of attributes which we manually match to every new handset in the cache, allowing us to adapt the content during MMS delivery.

Postback notifications

Postback notifications use the POST request method and the request body is UTF-8 encoded and JSON formatted according to the schemas described in this document. Postback notifications are issued as HTTP requests to the pre-configured 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 acknowledgement.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. There is 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.

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. Please note that we may update the postback IP address in the future. You will be notified in advance of any changes.

Postback notifications and the `savemms` action

Once an MMS is saved using the savemms action, it can be used by other functions through the mms-id returned from the N003 postback response. When an MMS is saved and transcoded successfully, the system will generate a postback notification and unlock the MMS template for further use. If an MMS contains audio/video, the postback will be sent when the encoding of the MMS audio/video is finished. Otherwise, the postback notification will be sent instantly after image and other content is transcoded in real-time and stored. In the postback you will receive the mms-id for the MMS created and the tracking-id that was originally received as the API Request Acknowledgement.

Special considerations

Each MMS message must include at least one slide. That slide may containt text and an image, video, audio, or other supported object. A maximum of eight slides per submission is supported.
Line breaks are supported in the slide texts of the MMS.
Provided URLs must contain the full path to the content files.
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.
Delivery success takes precedence over audio and video content quality. Occasionally, the picture quality will be reduced to fit handset message size requirements.
Video content may be reduced in quality to fit delivery limitations and, if it still does not fit, will be delivered as a fallback SMS.
If transcoding is ON for the account, MMS containing audio/video can be used only when the audio/video encoding is completed.
- After message submission, you will not be given a successful acknowledgement of audio/video encoding.
- The status of audio/video encoding will be sent to your Postback URL after it has been completed.
Content validation rules:
- Supported MIME TYPE and Supported Extension SHALL pass at validation and transcoding.
- Supported MIME TYPE and Invalid Extension SHALL pass at validation and transcoding.
- Supported MIME TYPE and No Extension SHALL pass at validation and transcoding.
- "Octet-stream" MIME TYPE and Supported Extension SHALL pass at validation and transcoding assuming the content is what the extension claims. Otherwise, it SHALL fail at transcoding.
- "Octet-stream" MIME TYPE and Invalid Extension SHALL fail at validation.
- "Octet-stream" MIME TYPE and No Extension SHALL fail at validation.
On an IOS device, contact, calendar, and pdf objects are delivered as binary attachments in the MMS. On an Android device, only contact is delivered as binary attachment in the MMS and calendar/pdf are delivered as downloadable web links in the MMS. All other devices, contact, calendar, and pdf are delivered as downloadable web links in the MMS. If the handset is unknown, contact is delivered as binary attachment and calendar/pdf are delivered as downloadable web links by default.
Each supported source file has a maximum file size. See your API settings to see the current maximum file size value.
MMS messages are delivered in B64 encoding. To estimate the final size of Base64 encoded binary data, multiply the file size by 1.37 times the original data size + 814 bytes (for headers).

API Limitations

You may have a throughput limit set on the number of API requests allowed per second. These limits will be set on your Account API Settings and communicated to you through your account manager. API currently returns an 'API exceeded' error code E113 when your API requests exceed the throughput limit and instructs 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.