This tutorial demonstrates how to send MMS messages with image, video, and audio attachments using the Twilio Python SDK's media_url parameter. It targets developers who need to include visual content in outbound messages, such as product photos, receipts, or event QR codes. You will send an MMS containing a publicly accessible image URL and verify the attachment arrives alongside the message body.
Prerequisites and Setup
You need the Twilio Python SDK installed with pip install twilio python-dotenv and a Twilio number that supports MMS, which requires a US or Canadian long code or short code. Your media file must be hosted at a publicly accessible HTTPS URL with the correct MIME type in the response headers, because Twilio fetches the file server-side before sending. Supported image types include JPEG, PNG, GIF, and WebP up to 5 MB per file, with a maximum of ten attachments per MMS. If you do not have a media host, upload your file to an S3 bucket with public read access or a CDN before running this code.
pip install twilio python-dotenv
# .env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567
The Complete Code
The media_url parameter in client.messages.create() accepts a list of strings, each pointing to a publicly hosted media file. Passing an empty body string while including media_url is valid, and the recipient will see only the image. Twilio transcodes media to match the capabilities of the destination carrier, so a PNG you provide may arrive as a JPEG on some networks. The returned MessageInstance has the same sid and status fields you use for SMS, letting you track the MMS through the same delivery pipeline.
import os
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException
from dotenv import load_dotenv
load_dotenv()
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
try:
message = client.messages.create(
body="Here is your confirmation image.",
from_=os.environ["TWILIO_PHONE_NUMBER"],
to="+15551234567",
media_url=[
"https://example.com/confirmation.png",
],
)
print(f"MMS SID: {message.sid}")
print(f"Status: {message.status}")
except TwilioRestException as e:
print(f"Error {e.code}: {e.msg}")
Testing and Debugging
If Twilio returns error code 21617, the media URL is not publicly reachable or is returning a non-200 HTTP status; use curl -I to verify the URL responds with 200 and a supported Content-Type header. Error code 21620 means the media type is not supported, so convert your file to a supported format before re-uploading. On trial accounts, MMS is still limited to verified numbers, just like SMS. Check the Twilio Console under Messaging Logs and click the SID to see the media fetch status and whether Twilio successfully retrieved your file.
Taking It Further
Pass multiple URLs in the media_url list to send up to ten attachments in a single MMS message. For video content, use MP4 files under 5 MB and verify the URL returns video/mp4 as the Content-Type. You can combine MMS with the StatusCallback feature to track when media messages are delivered or failed separately from text-only SMS. For production systems that generate dynamic images, render the image to a temporary file, upload it to S3, and pass the S3 URL to Twilio, then delete the file after the message is confirmed sent.
Contact Telphi Consulting to build rich media messaging workflows integrated into your existing Python application stack.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.