Back to Blog
Language How-Tos

How to Send MMS with Media in Twilio Using Node.js

Send MMS messages with image and media attachments from Node.js using the Twilio SDK with proper media URL and content type handling.

DA
Danial A
Senior Twilio Consultant, Telphi Consulting
June 22, 2026
8 min read
Twilio
Node.js
JavaScript
How-To
Code
How to Send MMS with Media in Twilio Using Node.js

This tutorial shows how to send MMS messages with image and media attachments using the Twilio Node.js SDK's mediaUrl parameter. It targets Node.js developers who need to include visual content in outbound messages, such as product images, receipts, or QR codes. You will send an MMS with a publicly accessible media URL and verify the attachment reaches the recipient's device alongside the message text.

Prerequisites and Setup

You need Node.js 14 or higher and the Twilio SDK installed with npm install twilio dotenv. Your Twilio number must support MMS, which requires a US or Canadian long code or short code; voice-only numbers cannot send MMS. The media file must be hosted at a publicly reachable HTTPS URL that returns the correct MIME type in its response headers, because Twilio fetches the file server-side before sending it. Supported formats include JPEG, PNG, GIF, and WebP for images, and MP4 for video, each with a maximum file size of 5 MB.

npm install twilio dotenv

# .env
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+15551234567

The Complete Code

The mediaUrl field in client.messages.create() accepts an array of strings, each a fully qualified HTTPS URL pointing to the media file you want to attach. You can include up to ten attachments per MMS message by adding multiple URLs to the array. Twilio transcodes the media to match destination carrier capabilities, so the format that arrives may differ slightly from what you uploaded. The returned MessageInstance has the same sid and status fields as a standard SMS, giving you a consistent way to track delivery.

require('dotenv').config();
const twilio = require('twilio');

const client = twilio(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);

async function sendMMS() {
  try {
    const message = await client.messages.create({
      body: 'Here is your confirmation image.',
      from: process.env.TWILIO_PHONE_NUMBER,
      to: '+15551234567',
      mediaUrl: ['https://example.com/confirmation.png'],
    });
    console.log('MMS SID:', message.sid);
    console.log('Status:', message.status);
  } catch (err) {
    console.error('Error', err.code, err.message);
  }
}

sendMMS();

Testing and Debugging

If Twilio returns error code 21617, the media URL is not publicly reachable or is returning a non-200 HTTP status; test the URL with curl -I to verify it responds with 200 and a supported Content-Type header. Error code 21620 means the media type is not supported by Twilio; convert the file to JPEG, PNG, or MP4 before re-uploading. On trial accounts, MMS is still restricted to verified destination numbers just like SMS. Check the Twilio Console under Messaging Logs, click the message SID, and inspect the media fetch status to see whether Twilio successfully retrieved your file from the URL.

Taking It Further

Generate images dynamically using the canvas npm package or a service like Sharp, write the output to a temporary file, upload it to S3 with a public read ACL, and pass the S3 URL to mediaUrl. Combine MMS with the StatusCallback feature to track when media messages are delivered and distinguish MMS failures from SMS failures in your logs. For marketing use cases, A/B test different product images by randomly selecting one from an array and recording which image correlated with higher response rates. Delete the S3 object after the message SID confirms delivery to avoid accumulating unused media files in your bucket.

Contact Telphi Consulting to build rich media messaging workflows integrated into your Node.js application stack.

Share this article:
0 views

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)

Protected by AI moderation

Be the first to comment

No comments yet. Share your thoughts below.