Overview
Twilio Programmable SMS supports sending picture messages (AKA MMS or multimedia messages) by adding the MediaUrl parameter to your API request. Continue reading for more details on the supported file types, and attachment file size limitations.
For help with sending MMS messages, please see Simple Example for Sending Programmable SMS Text or Picture Messages.
What You Need To Know
Supported File Types 🔗
Twilio Programmable SMS supports MediaUrl attachments with the following image file formats:
- jpeg
- png
- gif
These image file types are supported by Twilio and will be formatted for delivery on destination devices.
Twilio accepts a number of additional file formats as MediaUrl attachments, but these file types are not formatted for destination device compatibility. For a full list of media formats accepted by the Twilio API, please see Accepted Content Types for Media (Twilio Docs)
MMS Message Size Limitations (for non-image messages) 🔗
For file types other than jpeg, png and gif, the total file size limit for MediaUrl attachments depends on the receiving carrier. Here are the attachment size limitations for MMS sent from either long code or short code numbers to the top 4 US-based carriers:
| Carrier | Long code MMS attachment size | Toll-Free MMS attachment size | Short code MMS attachment size |
| AT&T* | 1.0 MB | 0.6 MB | 0.6 MB |
| T-mobile | 1.5 MB | 0.6 MB | 1.0 MB |
| Verizon | 1.0 MB | 0.6 MB | 1.2 MB |
We recommend using attachments no larger than 600KB when sending files that are not jpeg, png, or gif images.
*We recommend 600KB when sending over AT&T from Long Code to avoid the potential of file resize failures occurring at the carrier partner's network.
Twilio File Transcoding 🔗
Twilio will automatically transcode image file attachments in one of the supported file formats (jpeg, png, and gif). We will not transcode or resize any other types of media.
To ensure compatibility with all MMS-supported carriers, we recommend reducing the file size of any attachments with an "accepted" file type before attempting to send them.
If your media is not an image file and is larger than the limit shown above for the destination carrier, your MMS message will fail on Twilio with error 11751.
Number of Attachments Supported 🔗
Twilio supports up to 10 MediaUrl attachments, as long as the total size of the message body text and all attachments is less than 5 MB. An MMS message body can be up to 1600 characters long, which equals 4.8KB or roughly 1% of the total size limit.
- If your message (including body text and media) is larger than 5 MB, your message request will fail.
- Each MMS message, regardless of size, will always be counted as a 1-segment message.
Incoming MMS messages 🔗
There is no size limit for incoming MMS to your Twilio numbers. Twilio does not perform any transcoding or resizing on incoming media attachments, but the handset or sending carrier will likely apply transcoding before the file reaches Twilio.
In the rare case that an inbound MMS message contains more than 10 media attachments, Twilio's /Messages API will currently only surface the first 10 media attachments in the MediaUrl parameters. However, the Twilio Console will display all media attachments associated with that message record.
Typically, mobile handsets will restrict the number of attachments on an MMS message, or the total size of the message; because of this, messages with more than 10 attachments are uncommon.