# Introduction

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](/docs/mms/api-reference/api-status-codes/). For postback notification codes, click [here](/docs/mms/api-reference/postback-notification-codes/).

## Prerequisites

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`, and `Content-Type` headers.
- If receiving postbacks, a customer postback URL must be provisioned and reachable from Sinch postback source IP addresses.


## Authentication and security

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.

```http
Content-Type: application/json; charset=utf-8
x-api-key: YOUR_API_KEY_HERE
```

Note:
Do 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.

## Base URL, headers, and request conventions

| Server | URL |
|  --- | --- |
| General API | [https://api.ci.mblox.com/ep/v2/](https://api.ci.mblox.com/ep/v2/) |


All requests use the `POST` method and JSON payloads.

```http
POST https://api.ci.mblox.com/ep/v2/
Content-Type: application/json; charset=utf-8
x-api-key: YOUR_API_KEY_HERE
```

## Supported JSON actions

| Action | Purpose |
|  --- | --- |
| `sendmms` | [Sends an MMS](/docs/mms/api-reference/sendmms/) 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](/docs/mms/api-reference/savemms/). A saved template is referenced later through its `mms-id`. |
| `sendsavedmms` | [Sends a previously saved MMS template](/docs/mms/api-reference/sendsavedmms/) by referencing an `mms-id`. Optional group-display recipients may be included through `to-displayonly`. |


## Common behavior and special considerations

The following subsections detail common behaviors and special considerations for the MMS JSON API.

### International number format

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.

#### Correct number format

```json
"to": "17745559144"
```

#### Incorrect number format

```json
"to": "+17745559144"
```

```json
"to": "0017745559144"
```

### Media URL requirements

- Media URLs must include the full absolute path, including `http://` or `https://`.
- The hosting server must return a valid `Content-Length` header.
- The hosting server must return a valid `Content-Type` header.
- Chunked transfer encoding may be rejected if a `Content-Length` header is not provided.
- Accepted HTTP status codes for media retrieval are `200`, `301`, `302`, `303`, `307`, and `308`.
- For `3xx` redirects, only one redirect is followed.


### Slide rules

- 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-text` and 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-text` supports plain text and line breaks. Maximum text length is 5,000 characters per slide.


## Fallback SMS

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. |


## Content transcoding

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.

Note:
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 with `to-displayonly`

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.

Note:
`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. |


### Group messaging example pattern

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`.

```json
"to": "17745550001", "to-displayonly": "17745550002,17745550003"
```

```json
"to": "17745550002", "to-displayonly": "17745550001,17745550003"
```

```json
"to": "17745550003", "to-displayonly": "17745550001,17745550002"
```

## Postback notifications

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.

## API limitations

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.