# The `savemms` action

The `savemms` action creates an MMS template, transcodes the content, and stores it for later use. A saved MMS template can be sent later by using `sendsavedmms` with the returned `mms-id`.

The MMS may contain slides with text and supported media objects such as image, audio, video, contact, calendar, PDF, and Excel content where enabled for the account.

When the template is successfully saved and transcoded, an `N003` postback is generated. If audio or video content requires encoding, the template may not be immediately available for `sendsavedmms`. Attempting to send the template before encoding completes may return `E626`.

## Endpoint and headers

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

## Request parameters

| Parameter | Required/Optional | Type | Description |
|  --- | --- | --- | --- |
| `action` | Required | String | Must be `savemms`. |
| `message-subject` | Optional | String | MMS subject. Limit to 40 characters for best deliverability. Maximum 80 characters. |
| `fallback-sms-text` | Optional; required when fallback is enabled and `disable-fallback-sms` is `false` | String | Text sent if MMS is delivered as SMS fallback. |
| `disable-fallback-sms` | Optional | Boolean | Set `true` to disable fallback SMS. |
| `disable-fallback-sms-link` | Optional | Boolean | Set `true` to prevent appending the hosted MMS link to fallback SMS. |
| `fallback-sms-link-expiration` | Optional | String date-time | Expiration for SMS fallback link. Defaults to 1 year. Maximum 1 year. |
| `client-reference` | Optional | String | Customer transaction ID. Passed back in postbacks. Maximum 64 characters. |
| `name` | Required | String | MMS template name for internal reference only. |
| `slide` | Required | Array | One or more slide objects. Maximum 8 slides. |


## Slide parameters

| Parameter | Required/Optional | Type | Description |
|  --- | --- | --- | --- |
| `slide[].message-text` | Optional; required if no media/object is provided | String | Text delivered with the slide. Plain text. Maximum 5,000 characters. |
| `slide[].image.url` | Optional | String | Public URL for image content. Supports JPG/JPEG, PNG, GIF, and WEBP when enabled. |
| `slide[].audio.url` | Optional | String | Public URL for audio content. Supports MP3, WAV, and AMR. |
| `slide[].video.url` | Optional | String | Public URL for video content. Supports MP4, MPEG, AVI, WMV, MOV, and 3GP. |
| `slide[].contact.url` | Optional | String | Public URL for vCard contact object. |
| `slide[].calendar.url` | Optional | String | Public URL for iCalendar object. |
| `slide[].pdf.url` | Optional | String | Public URL for PDF object. |
| `slide[].ms-excel.url` | Optional | String | Public URL for Excel object where supported. |


## Fallback SMS considerations

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.

The following content is never transcoded: `contact`, `calendar`, `pdf`.

## Special considerations

- 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.
- 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.
- Object slides such as contact, calendar, PDF, and Excel should not be combined with image, audio, or video.
- Unicode characters may not be supported in the subject of an MMS message.
- Slides with text support Unicode characters, including emoji or emoticon. Destination devices may have limited Unicode capabilities. The preferred encoding is UTF-8.


## Example: Save MMS template

```bash
curl -i -X POST \
  https://api.ci.mblox.com/ep/v2/ \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "action": "savemms",
    "message-subject": "Monthly Update",
    "fallback-sms-text": "We could not deliver the MMS. View it here:",
    "disable-fallback-sms": false,
    "disable-fallback-sms-link": false,
    "client-reference": "template-build-001",
    "name": "monthly-update-template",
    "slide": [
      {
        "image": {
          "url": "https://example.com/content/update.png"
        },
        "message-text": "Here is this month's update."
      },
      {
        "pdf": {
          "url": "https://example.com/content/details.pdf"
        },
        "message-text": "See the attached PDF for details."
      }
    ]
  }'
```

## Success response example

```json
{
  "status": "success",
  "mms-id": "123456",
  "status-details": "MMS saved successfully."
}
```

## Failure response example

```json
{
  "status": "failure",
  "error-code": "E311",
  "error-info": "Invalid MMS Name or MMS Name is required."
}
```

## Postback notification: Saved MMS ready

When a saved MMS has completed transcoding and is available to send, an `N003` postback is generated.

```json
{
  "origin": "MMS_MT",
  "code": "N003",
  "status": "Transcoding successful",
  "status-details": "MMS template is available for sending.",
  "mms-id": "123456",
  "tracking-id": "template-build-001",
  "client-reference": "template-build-001",
  "timestamp": "2026-04-24T18:33:00Z"
}
```

## Response schema

| Field | Presence | Type | Description |
|  --- | --- | --- | --- |
| `status` | Always | String | `success` or `failure`. |
| `status-details` | Success only | String | Additional information about the accepted request. |
| `mms-id` | Success for `savemms` | String | MMS template ID. |
| `error-code` | Failure only | String | Error code identifying the failure condition. |
| `error-info` | Failure only | String | Human-readable error details. |