MMS send & receive

MMS carries rich media — images, GIFs, and short video — on the same SMS rails and sender identity you already use for text. This guide covers when to pick MMS over SMS or WhatsApp, how to attach media, how to compose a single send or a multi-recipient group send, and how to read per-recipient delivery reports. You will:

Decide MMS vs SMS vs WhatsApp
Attach media
Send a single MMS
Send a group MMS
Read delivery reports
Understand provider behavior and cost

1. Decide MMS vs SMS vs WhatsApp

MMS is the right surface when the message needs inline media on US/Canada (NANP, +1) numbers — and the wrong surface anywhere else. Decide before you build:

Inline image, GIF, or short video to a US/Canada number — use MMS. Attachments render directly in the recipient’s messaging app; no link tap required.
Text-only copy — use plain SMS. If no attachment is present, SMS is the cheaper surface; MMS only buys you the media fields.
Non-NANP recipients — MMS stops at +1 destinations. A recipient that rejects with MMS_NANP_ONLY is telling you to switch to WhatsApp or RCS, not to retry MMS.
Documents and contact cards — MMS rejects PDFs and vCards at send time. Host the file over HTTPS and put the link in the message body instead.

MMS uses your SMS sender identity and Messaging Profile. If SMS is not connected yet, connect it in Settings → Channels first — the MMS workspace activates on the same sender.

2. Attach media

Attach media by pasting an HTTPS URL, or by uploading a file in the dashboard composer (uploads land on Orbit-hosted HTTPS storage, which then flows through the same URL path). Two constraints are enforced before dispatch: Accepted content types

Category	Accepted types
Image	`image/jpeg`, `image/png`, `image/gif`, `image/webp`
Video	`video/mp4`, `video/3gpp`
Audio	`audio/mpeg`, `audio/ogg`, `audio/aac`

Size limit Each attachment is capped at 5 MB; anything larger is rejected before dispatch. For reliable carrier delivery keep each attachment under 1 MB — larger media is frequently down-rendered or dropped by individual carrier gateways even under the 5 MB ceiling. Media URLs must be HTTPS and pass the send-time URL allowlist; URLs that fail validation are rejected before the send rather than silently dropped. Up to 10 attachments ride on one message, and the body is optional when at least one attachment is present.

3. Send a single MMS

From the dashboard

Open Messages → MMS (members with the owner, admin, or developer workspace role).
Click Compose to open the MMS composer.
Add one recipient (+1 E.164 number), an optional body, and your media — upload the file or paste its HTTPS URL.
Send. The composer shows the per-recipient result immediately, and the message appears in the MMS workspace history.

The same composer handles one recipient or twenty — a group send is just more recipients on the same surface.

From the API

Send through the standard SMS endpoint with a media field — the send auto-upgrades to MMS as soon as an attachment is present:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promo-flyer-98421" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Check out our new store!",
    "media_urls": ["https://storage.googleapis.com/your-bucket/flyer.jpg"]
  }'

The response confirms the upgrade with "channel": "mms":

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "mms"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-09-03T00:00:00Z"
  }
}

4. Send a group MMS

Group MMS fans one payload (body + media) out to up to 20 recipients in a single operation, with per-recipient status in the response.

From the dashboard

Open Messages → MMS and click Compose.
Add up to 20 recipients — paste a comma- or newline-separated list and the composer splits it into chips; non-+1 numbers and duplicates are flagged before send.
Add the body and media as for a single send.
Send, then read the per-recipient result panel: each recipient shows as sent or failed with its reason (for example MMS_NANP_ONLY for a non-US/Canada number).

The recipient cap is 20 per send. For larger broadcasts use the batch SMS endpoint (with media upgrade) or the campaigns module.

From the API

curl -X POST https://api.orbit.devotel.io/api/v1/messages/group \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+18005551234",
    "to": ["+14155552671", "+14155552672"],
    "body": "Weekend sale — 20% off everything!",
    "media_urls": ["https://storage.googleapis.com/your-bucket/sale.jpg"]
  }'

The endpoint returns a per-recipient breakdown — 200 OK when every recipient succeeded, 207 Multi-Status on partial failure:

{
  "group_id": "batch_grp_abc123",
  "messages": [
    { "message_id": "msg_0f1e2d3c4b5a69788796a5b4c3d2e1f0", "to": "+14155552671", "status": "sent" }
  ],
  "summary": { "total": 2, "succeeded": 2, "failed": 0, "scheduled": 0 }
}

Every recipient is recorded before dispatch, so a pre-send rejection (validation, compliance, media check) lands as a visible failed row rather than a silent drop.

5. Read delivery reports

Each MMS moves through the standard lifecycle — queued → sending → sent → delivered (or failed / undelivered) — and you have three ways to follow it: MMS workspace. Messages → MMS lists history, delivery status, and analytics filtered to the MMS channel in one place; search by recipient or message body, and export the list. Delivery log. Open Messages → Tools → Delivery log and set the Channel filter to MMS — or share a pre-filtered link:

/en/messages/delivery-log?channel=mms

API. Query with the channel=mms filter, or subscribe to message.sent / message.delivered / message.failed webhooks. For group sends one event fires per recipient, so a 20-recipient send produces 20 delivery traces — diagnose each one individually.

curl "https://api.orbit.devotel.io/api/v1/messages?channel=mms&direction=outbound" \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

6. Provider behavior and cost

Outbound MMS is delivered through Telnyx — MMS and fax are the named exceptions to Orbit’s outbound policy, which otherwise terminates voice and SMS on the Devotel softswitch. All MMS traffic routes through the standard messaging router; there is no provider bypass to wire up. Inbound MMS replies arrive over the reverse path and surface as inbound messages on your sender numbers, the same as SMS. On cost: MMS is billed per message, not per attachment — a message with three attachments costs the same as one with one. In a group send, each recipient is billed as an individual message, and the composer shows a cost estimate before you confirm. Rates vary by destination; check the pricing page or the pricing endpoint for current rates.

Common errors

Code	HTTP	Meaning	Fix
`MMS_NANP_ONLY`	422	Recipient is not a NANP (`+1`) number	Route to WhatsApp or RCS
`VALIDATION_ERROR`	422	Media type, size, or URL check failed	Read `details.issues`; fix the attachment
`INSUFFICIENT_BALANCE`	402	Wallet below the group floor	Top up before the send
`RATE_LIMITED`	429	Group sends exceed 30 req/min	Space the calls; use batch for volume

Next steps

MMS channel reference — every request field, cap, and response shape
Delivery log — cross-channel search and shareable filtered links
Batch SMS — same media upgrade at higher volume
Send & receive messages — the three-step send → track → receive pattern across channels

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

MMS send & receive

MMS send & receive

1. Decide MMS vs SMS vs WhatsApp

2. Attach media

3. Send a single MMS

From the dashboard

From the API

4. Send a group MMS

From the dashboard

From the API

5. Read delivery reports

6. Provider behavior and cost

Common errors

Next steps

​MMS send & receive

​1. Decide MMS vs SMS vs WhatsApp

​2. Attach media

​3. Send a single MMS

​From the dashboard

​From the API

​4. Send a group MMS

​From the dashboard

​From the API

​5. Read delivery reports

​6. Provider behavior and cost

​Common errors

​Next steps

MMS send & receive

1. Decide MMS vs SMS vs WhatsApp

2. Attach media

3. Send a single MMS

From the dashboard

From the API

4. Send a group MMS

From the dashboard

From the API

5. Read delivery reports

6. Provider behavior and cost

Common errors

Next steps