Sinch offers MMS capabilities over the JSON API. Customers can submit JSON requests to send an MMS directly, save an MMS template for later use, or send a previously saved MMS template by referencing its mms-id.
The API supports MMS slides containing message text and supported media objects such as image, audio, video, contact, calendar, PDF, and Excel content where enabled for the account. MMS content is retrieved from customer-provided public URLs and processed according to account configuration, carrier requirements, and handset capabilities.
All API calls are made as HTTPS POST requests with UTF-8 encoded JSON in the request body.
For the API status code reference, click here. For postback notification codes, click here.
The prerequisites to use the MMS JSON API are detailed below:
- API access must be enabled for the customer account by Sinch.
- The customer must have a valid API key.
- The sender number must be provisioned for the account and authorized for MMS.
- The sender number must be a supported Short Code, Toll-Free number, or 10DLC number.
- Customer-hosted media URLs must be reachable by Sinch and must return valid HTTP status codes,
Content-Length, andContent-Typeheaders. - If receiving postbacks, a customer postback URL must be provisioned and reachable from Sinch postback source IP addresses.
Secure access to the API is provided over HTTPS using TLS version 1.2 or higher. Each API request must include the account API key in the x-api-key HTTP header. IP whitelisting may also be used as an additional access control.
Content-Type: application/json; charset=utf-8
x-api-key: YOUR_API_KEY_HEREDo not place the API key in the JSON request body or query string. The API key must be passed in the x-api-key HTTP header.
| Server | URL |
|---|---|
| General API | https://api.ci.mblox.com/ep/v2/ |
All requests use the POST method and JSON payloads.
POST https://api.ci.mblox.com/ep/v2/
Content-Type: application/json; charset=utf-8
x-api-key: YOUR_API_KEY_HERE| Action | Purpose |
|---|---|
sendmms | Sends an MMS defined in the JSON request to a single destination number. Optional group-display recipients may be included through to-displayonly. |
savemms | Creates and stores an MMS template. A saved template is referenced later through its mms-id. |
sendsavedmms | Sends a previously saved MMS template by referencing an mms-id. Optional group-display recipients may be included through to-displayonly. |
The following subsections detail common behaviors and special considerations for the MMS JSON API.
Always submit destination and sender numbers in international number format. Include the country code and phone number. Do not include dialing prefixes such as 00 or 001 and do not include the plus sign.
"to": "17745559144""to": "+17745559144""to": "0017745559144"- Media URLs must include the full absolute path, including
http://orhttps://. - The hosting server must return a valid
Content-Lengthheader. - The hosting server must return a valid
Content-Typeheader. - Chunked transfer encoding may be rejected if a
Content-Lengthheader is not provided. - Accepted HTTP status codes for media retrieval are
200,301,302,303,307, and308. - For
3xxredirects, only one redirect is followed.
- Each MMS must include at least one slide.
- A maximum of 8 slides per submission is supported in this implementation.
- Each slide may include
message-textand one supported media/object type. - Do not include more than one file of the same MIME type on the same slide.
- Image slides may include audio and text, but not video.
- Audio slides may include text, but not video.
- Video slides may include text, but not image or audio.
- Object slides such as contact, calendar, PDF, and Excel should not be combined with image, audio, or video.
message-textsupports plain text and line breaks. Maximum text length is 5,000 characters per slide.
If an MMS is too large to deliver or if a carrier does not support MMS delivery, the API may deliver the content as fallback SMS if enabled. Fallback SMS consists of fallback-sms-text and, by default, a link to view the MMS content.
| Field | Behavior |
|---|---|
fallback-sms-text | Text sent when MMS is delivered as SMS fallback. Required when fallback is enabled and disable-fallback-sms is false. |
disable-fallback-sms | When true, fallback SMS delivery is disabled. |
disable-fallback-sms-link | When true, the hosted MMS content link is not appended to fallback SMS text. |
fallback-sms-link-expiration | Expiration date/time for the fallback SMS link. Defaults to 1 year. Maximum 1 year. |
When transcoding is enabled for the account, Sinch may reformat supported content so it can be delivered to the destination handset. Delivery success takes priority over image, audio, or video quality. Content may be reduced in quality to satisfy carrier and handset size restrictions.
For sendmms, image content is optimized, but audio and video are not transcoded in the same way as saved templates. For video-heavy use cases, savemms followed by sendsavedmms is recommended.
Group messaging or group chat display behavior is supported by using the to-displayonly field in the sendmms and sendsavedmms actions. The field contains a comma-separated list of phone numbers with country code.
to-displayonly is a display/pass-through field. Delivery is only attempted to the recipient in the to field. To deliver to every participant, submit one API request per recipient in the to field and include the other participants in to-displayonly.
| Parameter | Required/Optional | Data Type | Description |
|---|---|---|---|
to | Required | String | The actual destination phone number that Sinch will deliver the MMS to. |
to-displayonly | Optional | String | Comma-separated list of additional participants displayed in the group thread. These numbers are not separately delivered by this request. |
To deliver a group-style MMS to three recipients, submit three requests. Each request changes the to value to the active recipient while listing the other participants in to-displayonly.
"to": "17745550001", "to-displayonly": "17745550002,17745550003""to": "17745550002", "to-displayonly": "17745550001,17745550003""to": "17745550003", "to-displayonly": "17745550001,17745550002"Postback notifications are sent as HTTP POST requests to the configured postback URL. The customer's server must respond with HTTP 200 OK within 10 seconds.
If the response takes longer than 10 seconds, the connection may time out and the notification may be retried. If the response is not HTTP 200, Sinch will retry the postback notification approximately five minutes later. A maximum of 5 retries is attempted per notification.
For best performance, store the raw postback immediately and perform heavy database or file processing asynchronously.
During onboarding, Sinch will provide the source IP addresses from which postback notifications originate. If IP whitelisting or firewall rules are used, allow those source IP addresses to reach the customer postback URL.
You may have a throughput limit set on the number of API requests allowed per second. These limits are set on the account API settings and communicated during onboarding. If requests exceed the configured throughput limit, the API may return error code E113. If you receive E113, throttle back your request rate or number of connections and retry rejected API calls.