---
title: "Send MMS Message"
method: POST
path: "/messages/send/mms"
tags: ["Messages > mms"]
---

# Send MMS Message

`POST /messages/send/mms`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/messages/send/mms`
- Auth: API key in header `PINNACLE-API-KEY`

Send a MMS immediately or schedule it for future delivery.

## Request body

- SendMmsSchema
  - `from` string, required: Phone number you want to send the message from in E.164 format.
  - `mediaUrls` string[], required: Media file URLs to send.<br> See [supported media types](https://app.pinnacle.sh/supported-file-types?type=MMS).
  - `options` SendMmsOptions: Control how your MMS is processed and delivered.
    - `multiple_messages` boolean, required: Allow splitting large content into multiple MMS messages if size limits are exceeded. <br> If `false`, MMS over the limit will throw an error and won't be sent.
    - `schedule` ScheduleSchema: Define when and how your message should be sent.
      - `sendAt` string, required: The date and time you want your message to be sent. - Use [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), for example: `2024-12-17T14:30:00Z`. Format: `YYYY-MM-DDThh:mm` (e.g., `2024-12-25T14:30`). - This time must be at least 5 minutes in the future. - The message will be scheduled based on the `timezone` you provide. - If you set a `recurrence` schedule, this is the start date and time for the recurring schedule.
      - `recurrence` string: AWS cron expression for recurring schedules (6 fields). <br> [Learn more about cron expressions](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html). <br> **Examples:** - `0 10 * * ? *` - Every day at 10:00 AM - `0/30 * * * ? *` - Every 30 minutes - `0 9 ? * MON-FRI *` - Every weekday at 9:00 AM - `0 12 1 * ? *` - First day of every month at noon
      - `timezone` string: IANA timezone identifier (e.g., `America/New_York`, `UTC`). <br> Defaults to `UTC` if not specified.
      - `endDate` string: Date and time when recurring messages should stop. <br> Format: `YYYY-MM-DDThh:mm`. Required if `recurrence` is set.
    - `tracking` 'ID' | 'HIDDEN': Enable tracking on sent messages. If not provided, messages are not tracked. You will not be able to react to these messages unless you provide the [options.force](./react#request.body.options.force) field. `ID` - Append an explicit ID at the end of the message for tracking. Users will see this ID. <br> `HIDDEN` - Invisible IDs are sent with messages for tracking. Will not be visible to users but will lead to slightly longer message lengths.
    - `validate` boolean, required: Set to true to check this message and throw an error when validation fails. <br> If errors occur, the message is not sent. Otherwise message is sent after validation.
  - `text` string, required: Message text to accompany the media.
  - `to` string, required: Recipient's phone number in E.164 format.

## Response `200`

Successfully sent or scheduled the message. <br>

Each message part can be tracked independently using its unique message ID. Use our [/messages/:id](./get) endpoint to track your messages.

- union
  - SendMmsResponse
    - `messageIds` string[], required: Array of unique message identifiers for an individual MMS send. Each identifier is a string that always begins with the prefix `msg_`, for example: `msg_1234567890`. <br><br> When media assets are too large to fit in a single MMS and `options.multiple_messages` is set to true, the content is automatically split across multiple messages. Each split message gets its own ID, and all IDs are returned in this array. <br><br> Note: When sending to audiences, you'll receive multiple response objects (one per recipient), each containing its own messageIds array.
    - `segments` number, double, required: Total number of segments used across the message.
    - `totalCost` number, double, required: Total cost of sending the message.
    - `sender` string, required: Sender's phone number in E.164 format.
    - `recipient` string, required: Recipient's phone number in E.164 format.
    - `status` 'queued', required: Message is queued for delivery.
  - ScheduledSendResponse
    - `scheduleId` string, required: Unique identifier for the scheduled send. This identifier is a string that always begins with the prefix `msg_sched_`, for example: `msg_sched_1234567890`.
    - `config` ScheduledSendResponseConfig, required: Configuration for the scheduled message.
      - `sendAt` string, required: When the message will be sent in ISO 8601 format.
      - `recurrence` string: AWS cron expression used for recurring messages.
      - `timezone` string, required: IANA timezone identifier.
      - `endDate` string: When the recurring messages stops in ISO 8601 format.

## Other responses

- `400`: The request was unacceptable, often due to providing an invalid update. <br> Errors may originate from invalid payload or from Pinnacle's additional validation checks. For example, providing an URL that cannot be accessed, updating a campaign that is currently being reviewed, updating data that you cannot access, sending a malformed message, and so on. <br> For `Pinnacle Validation Error` inspect the `error` payload to determine the source of the failure. These errors are likely due to additional validation and business logic checks.<br> For `Request Validation Error` inspect the `description` and `errors` payload to determine the source of failure. These errors are likely due to invalid payload inside the request.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `402`: Insufficient credits to complete this request. <br> This occurs when your account balance is below the required amount for processing the operation. Please add credits to your account to continue using the service.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.
- `501`: The requested functionality is not implemented on the server. <br> This typically indicates that the feature or endpoint you attempted to access is unavailable or not yet supported.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)