> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Send MMS with Vobiz
> Send MMS to US and Canadian numbers with the Vobiz Messaging API - media URL rules, text limits, the optional title, and how an SMS with media is upgraded to MMS automatically.
MMS carries text and media - images, audio, video or files - to US and Canadian mobile numbers. You send it through the same [Send a message](/docs/sms/api/messages/send-message) endpoint as SMS, with `channel: "mms"` and a list of `mediaUrls` that Vobiz fetches and hands to the carriers.
## What you need
* A messaging number on your account whose `channels` include `mms`. Check with [List your numbers](/docs/sms/api/numbers/list-numbers); US and Canadian numbers bought on the [Numbers](/docs/sms/numbers) page list `sms` and `mms`.
* Recipients with US or Canadian numbers.
* The same registration as SMS: US local numbers need a 10DLC campaign and US toll-free numbers need toll-free verification before production traffic. See the [compliance overview](/docs/sms/compliance/overview).
* Media hosted at public `https` URLs that the upstream network can fetch at send time.
## Media rules
The request is validated before it is routed. Each rule returns `400` with an `invalid mms: ...` error:
| Rule | Error returned otherwise |
| - | - |
| Provide `text`, at least one entry in `mediaUrls`, or both. | `invalid mms: text or at least one media URL is required` |
| `text` is at most 5000 characters. | `invalid mms: text is N characters, maximum is 5000` |
| `mediaUrls` holds at most 10 entries. | `invalid mms: N media items, maximum is 10` |
| Every entry is a parseable URL with a host. | `invalid mms: mediaUrls[i] is not a valid URL` |
| Every entry uses the `https` scheme. | `invalid mms: mediaUrls[i] must use https` |
`title` is an optional subject line for the MMS. It has no effect on other channels.
## Send an MMS
```bash cURL theme={null}
curl -X POST "https://api.vobiz.ai/api/v1/sms/messages" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": "+14155550100",
"to": ["+14155550123"],
"channel": "mms",
"title": "Your order has shipped",
"text": "Order #4821 is on its way. Track it at https://example.com/track/4821",
"mediaUrls": ["https://example.com/media/order-4821-label.png"],
"tag": "shipping"
}'
```
```python Python theme={null}
import requests
resp = requests.post(
"https://api.vobiz.ai/api/v1/sms/messages",
headers={
"X-Auth-ID": "MA_XXXXXXXX",
"X-Auth-Token": "YOUR_AUTH_TOKEN",
"Content-Type": "application/json",
},
json={
"from": "+14155550100",
"to": ["+14155550123"],
"channel": "mms",
"title": "Your order has shipped",
"text": "Order #4821 is on its way. Track it at https://example.com/track/4821",
"mediaUrls": ["https://example.com/media/order-4821-label.png"],
"tag": "shipping",
},
)
resp.raise_for_status()
print(resp.json()["id"], resp.json()["status"])
```
```javascript Node theme={null}
const resp = await fetch("https://api.vobiz.ai/api/v1/sms/messages", {
method: "POST",
headers: {
"X-Auth-ID": "MA_XXXXXXXX",
"X-Auth-Token": "YOUR_AUTH_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "+14155550100",
to: ["+14155550123"],
channel: "mms",
title: "Your order has shipped",
text: "Order #4821 is on its way. Track it at https://example.com/track/4821",
mediaUrls: ["https://example.com/media/order-4821-label.png"],
tag: "shipping",
}),
});
const message = await resp.json();
console.log(message.id, message.status);
```
```json Response - 201 Created theme={null}
{
"id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
"accountId": "MA_XXXXXXXX",
"direction": "out",
"channel": "mms",
"from": "+14155550100",
"to": "+14155550123",
"text": "Order #4821 is on its way. Track it at https://example.com/track/4821",
"mediaUrls": ["https://example.com/media/order-4821-label.png"],
"status": "sent",
"tag": "shipping",
"conversationId": "3c1d7e52-6f4b-4a8e-b2d9-0e5f1a7c9b34",
"createdAt": "2026-10-18T09:30:00.123456Z",
"updatedAt": "2026-10-18T09:30:00.123456Z"
}
```
MMS sends are billed at the MMS rate and deliver real media to the recipient. Run the examples only with your own credentials and numbers you intend to message.
## Media-only MMS
Leave `text` out (or empty) and send media alone:
```json theme={null}
{
"from": "+14155550100",
"to": ["+14155550123"],
"channel": "mms",
"mediaUrls": [
"https://example.com/media/menu-page-1.jpg",
"https://example.com/media/menu-page-2.jpg"
]
}
```
## Automatic upgrade from SMS
You can also attach `mediaUrls` to a send with `channel: "sms"` (or no `channel`). When **every** recipient in `to` is a US or Canadian number, Vobiz sends the message as MMS and the stored message shows `channel: "mms"`. When any recipient is outside the US and Canada, the message goes out as plain SMS and the media is left out.
Set `channel: "mms"` explicitly when you want the media rules above validated up front and a `400` instead of a silent fallback.
## Statuses, idempotency and replies
MMS shares everything else with SMS:
* Statuses `sent`, `delivered`, `failed` and `unknown`, with `statusHistory` on [Retrieve a message](/docs/sms/api/messages/get-message). See [SMS statuses](/docs/sms/channels/sms#message-statuses).
* `idempotencyKey`, `tag` and `scheduledAt` behave exactly as for [SMS](/docs/sms/channels/sms).
* Several recipients in `to` produce one record each, with the same `201` / `202` semantics as SMS.
* Inbound replies land in the same [conversation](/docs/sms/conversations) as your outbound messages; inbound media URLs appear in the message's `mediaUrls`.
* An `sms` opt-out also blocks MMS to that number. A send to an opted-out recipient returns `422`. See [Opt-outs](/docs/sms/opt-outs).
## Preview the cost
[Cost preview](/docs/sms/api/messages/cost-preview) accepts `channel=mms`:
```bash cURL theme={null}
curl -G "https://api.vobiz.ai/api/v1/sms/messages/cost-preview" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: YOUR_AUTH_TOKEN" \
--data-urlencode "from=+14155550100" \
--data-urlencode "to=+14155550123" \
--data-urlencode "channel=mms"
```
The response has the same shape as for SMS: `channel`, `segmentCount`, `unitCost`, `totalCost`, `currency`.
## Related
Every request field, response and error code.
Segments, idempotency, scheduling and statuses in detail.
Buy US and Canadian numbers with MMS capability.
10DLC and toll-free registration for US traffic.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.