# The `sendsavedmms` action

The `sendsavedmms` action sends a previously saved MMS template to a single mobile number. The request must include a valid `mms-id` that exists under the same account/API key.

The sender number must be provisioned for the account and authorized for MMS. Optional group-display recipients may be included through `to-displayonly`.

## 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 `sendsavedmms`. |
| `mms-id` | Required | String | MMS template ID returned by `savemms`/`N003`. |
| `service-id` | Required if configured for the account | String | Campaign or service identifier when required by account configuration. |
| `to` | Required | String | Destination phone number with country code. |
| `to-displayonly` | Optional | String | Comma-separated list of display-only group participants. |
| `from` | Required | String | Provisioned Short Code, Toll-Free, or 10DLC sender with country code. |
| `from-mask` | Optional | String | Alphanumeric sender mask where supported. Not supported in the USA. |
| `message-subject` | Optional | String | Overrides the subject saved in the MMS template. |
| `fallback-sms-text` | Required when fallback is enabled and `disable-fallback-sms` is `false` | String | Overrides fallback SMS text saved in the MMS template. |
| `disable-fallback-sms` | Optional | Boolean | Overrides the saved template fallback SMS setting. |
| `disable-fallback-sms-link` | Optional | Boolean | Overrides the saved template fallback SMS link setting. |
| `fallback-sms-link-expiration` | Optional | String date-time | Expiration for SMS fallback link. Defaults to 1 year. Maximum 1 year. |
| `mms-expiry-timestamp` | Optional | String date-time | Stops delivery attempts after this timestamp. Defaults to 3 days. Maximum 3 days. |
| `client-reference` | Optional | String | Customer transaction ID. Passed back in postbacks. Maximum 64 characters. |
| `custom-slides` | Optional | Array | Replaces text on specified saved template slides at send time. |


## `custom-slides` parameters

`custom-slides` can be used to replace the text on one or more slides in the saved template at send time. This is supported for replacing slide text, not for unsupported dynamic personalization or merge tag behavior.

| Parameter | Required/Optional | Type | Description |
|  --- | --- | --- | --- |
| `custom-slides[].custom-slide` | Required when `custom-slides` is used | String/integer | Slide number whose text will be replaced. |
| `custom-slides[].custom-message-text` | Required when `custom-slides` is used | String | Replacement text for the specified saved template slide. Line breaks are 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. |


## Group messaging with `to-displayonly`

Group messaging or group chat display behavior is supported by using the `to-displayonly` field. 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`.

## Special considerations

- 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.
- The `mms-id` must exist under the same account/API key.
- `custom-slides` only replaces text on saved template slides. It does not provide dynamic image, contact, calendar, or merge tag behavior.
- Line breaks are supported in `custom-message-text`.


## Example: Send saved MMS without group messaging

```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": "sendsavedmms",
    "mms-id": "123456",
    "service-id": "campaign-123",
    "to": "17745550001",
    "from": "18885551234",
    "fallback-sms-text": "We could not deliver the MMS. View it here:",
    "disable-fallback-sms": false,
    "client-reference": "send-001"
  }'
```

## Example: Send saved MMS with group messaging display

```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": "sendsavedmms",
    "mms-id": "123456",
    "service-id": "campaign-123",
    "to": "17745550001",
    "to-displayonly": "17745550002,17745550003",
    "from": "18885551234",
    "fallback-sms-text": "We could not deliver the MMS. View it here:",
    "disable-fallback-sms": false,
    "client-reference": "group-send-001"
  }'
```

## Example: Send saved MMS with `custom-slides`

```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": "sendsavedmms",
    "mms-id": "123456",
    "service-id": "campaign-123",
    "to": "17745550001",
    "from": "18885551234",
    "client-reference": "custom-slide-001",
    "custom-slides": [
      {
        "custom-slide": "1",
        "custom-message-text": "Reminder: your appointment is tomorrow at 2 PM."
      }
    ]
  }'
```

## Success response example

```json
{
  "status": "success",
  "mms-id": "123456",
  "tracking-id": "abc123xyz",
  "to": "17745550001",
  "from": "18885551234",
  "status-details": "MMS request accepted and queued for delivery."
}
```

## Failure response example

```json
{
  "status": "failure",
  "error-code": "E241",
  "error-info": "Invalid MMS ID or MMS does not exist."
}
```

## Response schema

| Field | Presence | Type | Description |
|  --- | --- | --- | --- |
| `status` | Always | String | `success` or `failure`. |
| `status-details` | Success only | String | Additional information about the accepted request. |
| `tracking-id` | Success for send actions | String | Transaction ID used to link API requests to postbacks. |
| `mms-id` | Success for `sendsavedmms` | String | MMS template ID. |
| `to` | Success for `sendsavedmms` | String | Destination phone number. |
| `from` | Success for `sendsavedmms` | String | Sender number. |
| `error-code` | Failure only | String | Error code identifying the failure condition. |
| `error-info` | Failure only | String | Human-readable error details. |