Send MMS with Vobiz

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 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; US and Canadian numbers bought on the 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.
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

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"
  }'

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"])

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);

Response - 201 Created

{
  "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:

{
  "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. See SMS statuses.
idempotencyKey, tag and scheduledAt behave exactly as for SMS.
Several recipients in to produce one record each, with the same 201 / 202 semantics as SMS.
Inbound replies land in the same conversation 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.

Preview the cost

Cost preview accepts channel=mms:

cURL

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.

Send a message

Every request field, response and error code.

SMS

Segments, idempotency, scheduling and statuses in detail.

Numbers

Buy US and Canadian numbers with MMS capability.

US compliance

10DLC and toll-free registration for US traffic.

Getting Started

API Reference

Guides

Send MMS with Vobiz

What you need

Media rules

Send an MMS

Media-only MMS

Automatic upgrade from SMS

Statuses, idempotency and replies

Preview the cost

Send a message

SMS

Numbers

US compliance

​What you need

​Media rules

​Send an MMS

​Media-only MMS

​Automatic upgrade from SMS

​Statuses, idempotency and replies

​Preview the cost

​Related

Send a message

SMS

Numbers

US compliance

What you need

Media rules

Send an MMS

Media-only MMS

Automatic upgrade from SMS

Statuses, idempotency and replies

Preview the cost

Related