Skip to main content
MMS messages let you send images, videos, and other media files alongside text. This guide covers supported media types, carrier size limits, and how to use Telnyx’s automatic transcoding to ensure delivery.
MMS is supported on Long Code, Toll-Free, and Short Code numbers in the US and Canada. International MMS support varies by carrier.

​
Send an MMS message

Include one or more media_urls in your message request to send an MMS: 
curl -X POST https://api.telnyx.com/v2/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Check out this image!",
    "media_urls": ["https://example.com/image.jpg"]
  }'
You can include up to 10 media URLs per MMS message. Each URL must be publicly accessible — Telnyx fetches the media at send time.

​
Supported media types

CategoryFormatsNotes
ImagesJPEG, PNG, GIF, BMP, TIFF, WebPMost widely supported across carriers
VideoMP4, 3GP, MOVH.264 codec recommended
AudioMP3, WAV, AMR, OGGLimited carrier support
DocumentsPDF, vCard (.vcf), iCal (.ics)Limited carrier support
Animated GIFs are not supported for transcoding. If you send animated GIFs, ensure they are under the carrier size limit — they will not be resized.

​
Carrier size limits

Each US carrier imposes different maximum MMS message sizes based on the sender type. Messages exceeding these limits will be rejected by the carrier.
CarrierLong CodeToll-FreeShort Code
AT&T1 MB600 KB600 KB
T-Mobile1.5 MB600 KB1 MB
Verizon1 MB600 KB1.2 MB
The safe maximum across all carriers and sender types is 600 KB. To guarantee delivery to all recipients regardless of carrier, keep your total media under this limit — or enable transcoding.

​
Automatic transcoding

Telnyx can automatically resize media to comply with carrier size limits. When enabled, oversized images and videos are resized before delivery.

​
How transcoding works

  1. You send an MMS with media that exceeds the destination carrier’s size limit
  2. Telnyx detects the destination carrier and its size restriction
  3. Media is resized to fit within the limit:
    • Images → converted to JPEG
    • Videos → converted to H.264 MP4
  4. The resized media is delivered to the recipient
Transcoding reduces media quality to meet size constraints. For best results, optimize your media before sending.

​
Enable transcoding

Enable mms_transcoding on your messaging profile to apply it to all MMS sent through that profile. 
curl -X PATCH https://api.telnyx.com/v2/messaging_profiles/{profile_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "mms_transcoding": true
  }'

​
Best practices

Pre-optimize your media for the best balance of quality and deliverability:
  • Images: Resize to 640×480 or smaller, use JPEG at 80% quality
  • Videos: Compress to H.264, keep under 30 seconds, target 480p
  • Target size: Stay under 600 KB for universal carrier compatibility
This gives you control over quality rather than relying on automatic transcoding.
Media URLs must be publicly accessible — Telnyx fetches them at send time. Ensure:
  • URLs don’t require authentication
  • URLs respond quickly (timeouts cause delivery failures)
  • URLs return the correct Content-Type header
  • URLs use HTTPS for security
Inbound MMS media URLs in webhooks are ephemeral — they expire after a short period. Always download and store important media to your own storage (e.g., AWS S3) immediately upon receiving the webhook.See the Send & Receive MMS tutorial for a complete implementation.
If your message doesn’t include media, send it as SMS instead of MMS. SMS is:
  • Cheaper — MMS messages cost more than SMS
  • Faster — No media download/processing overhead
  • More reliable — Fewer points of failure
Only use MMS when you actually need to include media content.

Send & Receive MMS Tutorial

Full tutorial for building an MMS application with media storage.

SMIL Templates

Customize the layout of your MMS media with SMIL templates.

Send Your First Message

Get started with the Telnyx Messaging API.

Messages API Reference

API reference for sending messages with media.