# The `sendmms` action

The `sendmms` action sends an MMS defined directly in the JSON request to a single mobile number. It is useful when the customer does not need to store and reuse an MMS template.

The MMS may contain one or more slides with text and supported media objects such as image, audio, video, contact, calendar, PDF, and Excel content where enabled for the account. Slides are processed in the order provided in the request, although not all handsets or messaging clients render MMS content in the same way.

All requests are made as HTTPS `POST` requests with UTF-8 encoded JSON in the request body. Each request must include `Content-Type: application/json; charset=utf-8` and the account API key in the `x-api-key` HTTP header.

Note:
If the same content will be sent repeatedly, consider `savemms` followed by `sendsavedmms` so content can be stored/transcoded once and reused.

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.

## 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 `sendmms`. |
| `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. Do not include `+` or dialing prefixes. |
| `to-displayonly` | Optional | String | Comma-separated list of display-only group participants. Delivery is only attempted to `to`. |
| `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 | MMS subject. Limit to 40 characters for best deliverability. Maximum 80 characters. Unicode/emojis may not be supported. |
| `fallback-sms-text` | Required when fallback is enabled and `disable-fallback-sms` is `false` | String | Text sent if MMS is delivered as SMS fallback. Limit to 110 characters for best deliverability. |
| `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. ISO 8601 format. |
| `mms-expiry-timestamp` | Optional | String date-time | Stops MMS delivery attempts after this timestamp. Defaults to 3 days. Maximum 3 days. ISO 8601 format. |
| `client-reference` | Optional | String | Customer transaction ID. Passed back in postbacks. Maximum 64 characters. |
| `cache-content` | Optional | Boolean | Caching is enabled by default unless set to `false`. |
| `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. |


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


## Example: Send 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": "sendmms",
    "service-id": "campaign-123",
    "to": "17745550001",
    "from": "18885551234",
    "message-subject": "Deal of the Day",
    "fallback-sms-text": "We could not deliver the MMS. View it here:",
    "disable-fallback-sms": false,
    "disable-fallback-sms-link": false,
    "client-reference": "order-12345",
    "slide": [
      {
        "image": {
          "url": "https://example.com/content/deal.png"
        },
        "message-text": "Hello! Here is today's deal."
      }
    ]
  }'
```

## Example: Send 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": "sendmms",
    "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,
    "slide": [
      {
        "image": {
          "url": "https://example.com/content/group-image.jpg"
        },
        "message-text": "Team reminder: the event starts at 6 PM."
      }
    ]
  }'
```

## Success response example

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

## Failure response example

```json
{
  "status": "failure",
  "error-code": "E111",
  "error-info": "Invalid Sender."
}
```

## 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. |
| `to` | Success for `sendmms` | String | Destination phone number. |
| `from` | Success for `sendmms` | String | Sender number. |
| `error-code` | Failure only | String | Error code identifying the failure condition. |
| `error-info` | Failure only | String | Human-readable error details. |