​

MMS

1. Single MMS — POST /api/v1/messages/sms with media_url / media_urls. The SMS endpoint auto-upgrades the send to MMS as soon as one or more attachments are present.
2. Group MMS — POST /api/v1/messages/group fans a single payload (body + media) out to up to 20 recipients in one call.

​

Single MMS

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

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit(process.env.ORBIT_API_KEY);

// The typed sendSms input accepts media_urls alongside media_url.
const response = await orbit.messages.sendSms({
  to: '+14155552671',
  from: '+18005551234',
  body: 'Check out our new store!',
  media_urls: [
    'https://storage.googleapis.com/your-bucket/flyer.jpg',
    'https://storage.googleapis.com/your-bucket/map.png',
  ],
});

from orbit_sdk import OrbitClient

client = OrbitClient(api_key="dv_live_sk_...")

# The typed send_sms helper omits a media field, so route through
# the client.request(...) escape hatch with the curl payload shape.
response = client.request(
    "POST",
    "/messages/sms",
    json_body={
        "to": "+14155552671",
        "from": "+18005551234",
        "body": "Check out our new store!",
        "media_urls": [
            "https://storage.googleapis.com/your-bucket/flyer.jpg",
            "https://storage.googleapis.com/your-bucket/map.png",
        ],
    },
)

// SendSMSInput does not surface a MediaURLs field, so call the raw
// client.Request escape hatch when you attach media.
payload := map[string]any{
    "to":   "+14155552671",
    "from": "+18005551234",
    "body": "Check out our new store!",
    "media_urls": []string{
        "https://storage.googleapis.com/your-bucket/flyer.jpg",
        "https://storage.googleapis.com/your-bucket/map.png",
    },
}
var out map[string]any
err := client.Request(ctx, "POST", "/messages/sms", nil, payload, &out, "")
if err != nil { /* handle */ }

​

Media fields

• Body is optional when at least one attachment is present — an MMS may be media-only.
• Each URL must be HTTPS and resolve through the send-time SSRF allowlist (e.g. storage.googleapis.com). URLs that fail the allowlist or DNS-rebind check are rejected before dispatch.
• Up to 10 attachments per message are forwarded to the provider.

​

Supported media types and size limit

• Maximum size: 5 MB per attachment (hard limit). For the most reliable delivery across carriers, keep each attachment under 1 MB — larger images are frequently down-rendered or dropped by individual carrier gateways even under the 5 MB ceiling.
• Not supported: documents (PDF), contact cards (vCard), and other content types outside the table above. To deliver those, link to an HTTPS-hosted file in the message body, or send the content over WhatsApp or RCS instead.

​

Response

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "mms",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-06-08T00:00:00Z"
  }
}

​

Group MMS

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

{
  "group_id": "batch_grp_abc123",
  "messages": [
    { "message_id": "msg_0f1e2d3c4b5a69788796a5b4c3d2e1f0", "to": "+14155552671", "status": "sent" },
    { "message_id": "msg_112233445566778899aabbccddeeff00", "to": "+14155552672", "status": "sent" },
    {
      "message_id": "msg_ffeeddccbbaa99887766554433221100",
      "to": "+16505553000",
      "status": "failed",
      "error_code": "MMS_NANP_ONLY",
      "error_message": "MMS is only available for NANP (US/Canada) recipients"
    }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "scheduled": 0
  }
}

​

Request body

​

Response — 200 / 207

• 200 OK — every recipient succeeded.
• 207 Multi-Status — any recipient failed (partial or total failure). Inspect the body for per-recipient status / error_code.
• 402 Payment Required — the org balance cannot cover the group floor (pre-flight check).
• 500 — bulk pre-insert failure (no recipients dispatched).

​

Error recovery: pre-filter NANP recipients

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit(process.env.ORBIT_API_KEY);

const recipients = ['+14155552671', '+442071234567', '+16505553000'];

// Split NANP (`+1...`) recipients from non-NANP ones before dispatch:
// only `+1` numbers reach the MMS provider; the rest would come back
// failed with MMS_NANP_ONLY in the fanout-recipient-status body.
const nanp = recipients.filter((n) => n.startsWith('+1'));
const skipped = recipients.filter((n) => !n.startsWith('+1'));

if (skipped.length) {
  console.log('Skipping non-NANP recipients:', skipped);
}

for (const to of nanp) {
  // sendSms takes a single recipient per call — iterate the NANP-only list.
  await orbit.messages.sendSms({
    from: '+18005551234',
    to,
    body: 'Weekend sale!',
    media_urls: ['https://storage.googleapis.com/your-bucket/sale.jpg'],
  });
}

from orbit_sdk import OrbitClient

client = OrbitClient(api_key="dv_live_sk_...")

recipients = ["+14155552671", "+442071234567", "+16505553000"]

# Same guard in Python: partition NANP vs non-NANP before POSTing.
nanp = [n for n in recipients if n.startswith("+1")]
skipped = [n for n in recipients if not n.startswith("+1")]

if skipped:
    print("Skipping non-NANP recipients:", skipped)

response = client.request(
    "POST",
    "/messages/group",
    json_body={
        "from": "+18005551234",
        "to": nanp,
        "body": "Weekend sale!",
        "media_urls": ["https://storage.googleapis.com/your-bucket/sale.jpg"],
    },
)

​

Rate Limits

​

Outbound provider

​

Limits

​

Deciding when to use MMS

• Inline image, video, or audio — use MMS. Attach up to 10 files, 5 MB each, on the SMS endpoint or the group endpoint. NANP recipients only.
• Contact card, document, or anything outside the media table — MMS rejects it with a 422. Prefer an HTTPS link in the message body (vCard files, PDFs, boarding passes, receipts): host the file, send the URL. The recipient taps through and no carrier media filter can down-grade it.
• Non-NANP recipients — MMS stops at US/Canada. Route picture and video traffic to WhatsApp or RCS for international numbers. A recipient that soft-fails with MMS_NANP_ONLY is telling you to switch channels, not retry.
• Text-only copy — use plain SMS. If the body carries the whole message and there is no attachment, SMS is the cheaper and simpler surface; MMS only buys you the media fields. A rejected MMS (media-type or size rejection) also does not silently fall back to SMS — re-send on the right surface.

​

Still not delivering?

1. Confirm the message is in delivered state, not sent — sent means the carrier accepted it, not that the device received it. The message status model maps every state transition and what each one proves.
2. For undelivered or failed states, use the undelivered / failed message guide — it covers the carrier-rejection and handset-rejection classes that MMS specifically raises (MMS_NANP_ONLY, media-type rejection, size rejection, destination unreachable).
3. For inbound MMS that sends but never arrives in your webhook, check inbound channel routing.

​

Pricing