Send MMS with Node.js, Express, and Vonage: A Developer Guide

Multimedia Messaging Service (MMS) enables sending messages that include media like images, GIFs, or videos, offering richer communication than standard SMS. This guide provides a complete walkthrough for building a Node.js application using the Express framework to send MMS messages via the Vonage Messages API.

We will build a simple Express API endpoint that accepts a recipient phone number and an image URL, then uses the Vonage Node.js SDK to send an MMS message. This guide covers everything from project setup and Vonage configuration to implementation, error handling, and testing.

Goal: Create a robust Node.js service capable of sending MMS messages reliably using Vonage.

Technology Stack:

Node.js: A JavaScript runtime environment for server-side development.
Express: A minimal and flexible Node.js web application framework used to create the API endpoint.
Vonage Messages API: A unified API for sending messages across various channels, including MMS.
Vonage Node.js SDK (@vonage/messages): The official library for interacting with the Vonage Messages API in Node.js applications.
dotenv: A module to load environment variables from a .env file.
ngrok (Optional but Recommended for Development): A tool to expose local servers to the internet for testing webhooks.

System Architecture:

The system follows this flow:

A client (e.g., Postman, curl, another application) sends an HTTP POST request to the Node.js / Express API endpoint.
The Express application validates the request and uses the Vonage Node.js SDK (authenticated with API credentials and application details) to send an MMS request to the Vonage Messages API.
The Vonage Messages API handles the delivery of the MMS message to the recipient's mobile device.
Vonage sends status updates (e.g., delivery receipts) back to a configured Webhook URL (which might be an ngrok tunnel during development) handled by the Express application.
The Express application sends an API response back to the original client.

Prerequisites:

Vonage API Account: Sign up for a free Vonage account if you don't have one. You'll get some free credits to start.
Vonage API Key and Secret: Find these at the top of your Vonage API Dashboard.
Vonage US Number (MMS Capable): Purchase a US-based virtual number capable of sending SMS and MMS. You can do this via the Vonage Dashboard (Numbers > Buy Numbers). MMS sending via Vonage is primarily supported from US numbers to US recipients.
Node.js and npm (or yarn): Install a recent LTS version of Node.js, which includes npm. Download from nodejs.org.
ngrok (Optional): Download and set up ngrok if you need to test webhook functionality locally. ngrok.com. A free account is sufficient.
Basic Understanding: Familiarity with JavaScript, Node.js, REST APIs, and terminal/command line usage.

1. Setting Up the Project

Let's create the project directory, initialize Node.js, and install the necessary dependencies.

Create Project Directory: Open your terminal or command prompt and create a new directory for your project, then navigate into it.
```
mkdir vonage-mms-sender
cd vonage-mms-sender
```
Initialize Node.js Project: Initialize the project using npm. The -y flag accepts default settings.
```
npm init -y
```
This creates a package.json file.
Install Dependencies: Install Express for the web server, @vonage/messages for the Vonage SDK, and dotenv for managing environment variables.
```
npm install express @vonage/messages dotenv --save
```
- express: Web framework for creating the API endpoint.
- @vonage/messages: The correct Vonage SDK specifically for the Messages API (handles SMS, MMS, WhatsApp, etc.). Do not use the older @vonage/server-sdk for sending MMS via the Messages API.
- dotenv: Loads environment variables from a .env file into process.env.
Create Project Files: Create the main application file and a file for environment variables.
```
touch index.js .env .gitignore
```
- index.js: Will contain our Express application code.
- .env: Will store sensitive credentials (API keys, etc.).
- .gitignore: Specifies files that Git should ignore (like .env and node_modules).
Configure .gitignore: Add node_modules and .env to your .gitignore file to prevent committing them to version control.
```
# .gitignore

node_modules/
.env
private.key
```
Note: We also add private.key here, which we'll generate later.

2. Vonage Account Configuration

Before writing code, we need to configure our Vonage account and application correctly.

Get API Key and Secret:
- Log in to your Vonage API Dashboard.
- Your API Key and API Secret are displayed prominently at the top. Copy these; you'll need them for the .env file.
Purchase a US MMS-Capable Number:
- Navigate to Numbers > Buy Numbers in the dashboard.
- Search for numbers in the USA. Ensure the capabilities include SMS and MMS.
- Purchase a number. Note this number down; it will be your sender number.
Set Default SMS API to Messages API:
- This is a crucial step often missed. Go to your Account Settings in the Vonage Dashboard.
- Find the ""API Settings"" or ""SMS Settings"" section.
- Ensure the Default SMS setting is set to Messages API. This determines the format of webhooks and ensures compatibility with the @vonage/messages SDK. Save the changes.
Create a Vonage Application: Vonage Applications act as containers for your communication settings and handle authentication using public/private key pairs for certain APIs like Messages.
- Navigate to Applications > Create a new application.
- Give your application a descriptive name (e.g., ""Node MMS Sender"").
- Generate Public/Private Key Pair: Click the ""Generate public and private key"" link. A public key will be added to the form, and a private.key file will be downloaded. Save this private.key file securely in your project's root directory (the one containing index.js). Do not commit this file to Git.
- Enable Capabilities: Toggle ON the Messages capability.
- Configure Webhooks: Even though this guide focuses on sending, the Messages API application requires webhook URLs for status updates and inbound messages.
  - Status URL: Where Vonage sends delivery receipts and status updates for outgoing messages.
  - Inbound URL: Where Vonage sends incoming messages sent to your Vonage number linked to this application.
  - For Development: Use ngrok to create temporary public URLs that forward to your local machine. Open a new terminal window and run:
    # Make sure you are NOT in your project directory for this command ngrok http 3000
    ngrok will provide a forwarding URL (e.g., https://<unique-id>.ngrok.io). Use this URL for your webhooks:
    - Status URL: https://<unique-id>.ngrok.io/webhooks/status
    - Inbound URL: https://<unique-id>.ngrok.io/webhooks/inbound
    - Set the HTTP method for both to POST.
  - For Production: Replace the ngrok URLs with your actual, publicly accessible API endpoints designed to handle these webhooks. These endpoints must respond with a 200 OK status quickly, otherwise Vonage will retry sending the webhook.
- Click Create application.
Note the Application ID: After creating the application, you'll be redirected to its overview page. Copy the Application ID. You'll need this for the .env file.
Link Your Vonage Number: On the application overview page, scroll down to the ""Linked numbers"" section. Find the US MMS-capable number you purchased earlier and click the Link button next to it. This connects incoming messages and associates outgoing messages sent via this application with that number.

3. Secure Configuration with `.env`

Store your sensitive credentials and configuration details in the .env file. Never commit this file to version control.

Populate your .env file with the information gathered:

# .env

# Vonage API Credentials (from Dashboard)
VONAGE_API_KEY=YOUR_API_KEY
VONAGE_API_SECRET=YOUR_API_SECRET

# Vonage Application Details (from Application Settings)
VONAGE_APPLICATION_ID=YOUR_APPLICATION_ID
# Path relative to the project root where private.key is stored
VONAGE_PRIVATE_KEY_PATH=./private.key

# Vonage Number (The US MMS number you purchased and linked)
VONAGE_MMS_SENDER_NUMBER=YOUR_VONAGE_US_NUMBER

# Server Port
PORT=3000

Replace the placeholder values (YOUR_...) with your actual credentials.
VONAGE_PRIVATE_KEY_PATH: Ensure this path correctly points to your downloaded private.key file. ./private.key assumes it's in the same directory as index.js.
VONAGE_MMS_SENDER_NUMBER: Use the E.164 format (e.g., 12015550123).

4. Implementing the Core Functionality (Express API)

Now, let's write the Node.js code using Express to create an API endpoint for sending MMS.

// index.js
'use strict';

// Load environment variables from .env file
require('dotenv').config();

const express = require('express');
const { Messages, MMSImage } = require('@vonage/messages'); // Use the correct SDK

// --- Vonage Client Initialization ---
// Validate essential environment variables
const requiredEnv = [
  'VONAGE_API_KEY',
  'VONAGE_API_SECRET',
  'VONAGE_APPLICATION_ID',
  'VONAGE_PRIVATE_KEY_PATH',
  'VONAGE_MMS_SENDER_NUMBER',
];

const missingEnv = requiredEnv.filter(key =&gt; !process.env[key]);
if (missingEnv.length &gt; 0) {
  console.error(`Error: Missing required environment variables: ${missingEnv.join(', ')}`);
  console.error('Please check your .env file.');
  process.exit(1); // Exit if configuration is incomplete
}

let vonageMessages;
try {
  vonageMessages = new Messages({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET,
    applicationId: process.env.VONAGE_APPLICATION_ID,
    privateKey: process.env.VONAGE_PRIVATE_KEY_PATH, // SDK handles reading the file path
  });
} catch (initError) {
  console.error('Error initializing Vonage Messages SDK:', initError);
  console.error('Please check your .env configuration and private key path/permissions.');
  process.exit(1);
}


// --- Express Application Setup ---
const app = express();
app.use(express.json()); // Middleware to parse JSON bodies
app.use(express.urlencoded({ extended: true })); // Middleware for URL-encoded bodies

const PORT = process.env.PORT || 3000;

// --- API Endpoint for Sending MMS ---
app.post('/send-mms', async (req, res) =&gt; {
  console.log('Received /send-mms request:', req.body);

  // 1. Basic Input Validation
  const { recipientNumber, imageUrl, caption } = req.body;
  if (!recipientNumber || !imageUrl) {
    return res.status(400).json({
      success: false,
      message: 'Missing required fields: recipientNumber and imageUrl',
    });
  }

  // Basic validation: checks if it's digits after removing optional leading '+'. E.164 format is recommended for the 'to' field.
  if (!/^\d+$/.test(recipientNumber.replace(/^\+/, ''))) {
      return res.status(400).json({
          success: false,
          message: 'Invalid recipientNumber format. Please provide digits only (optionally starting with +). E.164 format is recommended.',
      });
  }

  // Basic validation for image URL format
  try {
      new URL(imageUrl);
  } catch (error) {
      return res.status(400).json({
          success: false,
          message: 'Invalid imageUrl format.',
      });
  }

  // 2. Construct the MMS Message Payload
  const mmsPayload = new MMSImage({
    to: recipientNumber,               // Recipient's phone number (E.164 format recommended)
    from: process.env.VONAGE_MMS_SENDER_NUMBER, // Your Vonage US MMS number from .env
    image: {
      url: imageUrl,                   // Publicly accessible URL of the image
      caption: caption || 'Image message', // Optional caption
    },
    // Optional: client_ref for tracking messages on your side
    // client_ref: `my-internal-id-${Date.now()}`
  });

  // 3. Send the MMS using Vonage SDK
  try {
    console.log(`Attempting to send MMS to ${recipientNumber} from ${process.env.VONAGE_MMS_SENDER_NUMBER}`);
    const response = await vonageMessages.send(mmsPayload);

    console.log('Vonage API Response:', response);

    // Check response for success indication (structure might vary slightly)
    if (response.message_uuid) {
        console.log(`MMS submitted successfully! Message UUID: ${response.message_uuid}`);
        return res.status(200).json({
          success: true,
          message: 'MMS submitted successfully',
          message_uuid: response.message_uuid,
        });
    } else {
        // Handle cases where Vonage might return 2xx but without a message_uuid (unlikely for success)
        console.error('MMS submission failed or response format unexpected:', response);
        return res.status(500).json({
           success: false,
           message: 'MMS submission failed or Vonage response format unexpected.',
           details: response // Include Vonage response for debugging
        });
    }

  } catch (error) {
    console.error('Error sending MMS via Vonage:', error);

    // Provide more specific feedback based on potential Vonage errors
    let statusCode = 500;
    let errorMessage = 'Failed to send MMS due to an internal server error.';

    // Check if the error object has Vonage-specific structure
    if (error.response && error.response.data) {
        console.error('Vonage Error Details:', error.response.data);
        errorMessage = `Vonage API Error: ${error.response.data.title || error.message}`;
        // Use status from Vonage response if available, otherwise keep 500
        statusCode = typeof error.response.status === 'number' ? error.response.status : 500;
    } else if (error.request) {
        // The request was made but no response was received
        errorMessage = 'Failed to send MMS: No response received from Vonage API.';
    } else {
        // Something happened in setting up the request that triggered an Error
        errorMessage = `Failed to send MMS: ${error.message}`;
    }

    return res.status(statusCode).json({
      success: false,
      message: errorMessage,
      // Safely access potential error details
      errorDetails: error.response?.data
    });
  }
});

// --- Basic Root Route (Optional) ---
app.get('/', (req, res) =&gt; {
  res.send('Vonage MMS Sender API is running!');
});

// --- Webhook Endpoints (Placeholder - Must return 200 OK) ---
// These are required by the Vonage Application configuration but are not
// fully implemented in this sending-focused guide.
// In production, you'd process status updates and inbound messages here.
app.post('/webhooks/status', (req, res) =&gt; {
  console.log('Received Status Webhook:', req.body);
  res.status(200).end(); // Always respond with 200 OK quickly
});

app.post('/webhooks/inbound', (req, res) =&gt; {
  console.log('Received Inbound Webhook:', req.body);
  res.status(200).end(); // Always respond with 200 OK quickly
});


// --- Start Server ---
app.listen(PORT, () =&gt; {
  console.log(`Server listening on port ${PORT}`);
  console.log(`MMS sending endpoint available at http://localhost:${PORT}/send-mms`);
  if (process.env.NODE_ENV !== 'production') {
      console.log('Ensure ngrok is running and forwarding to this port if testing webhooks locally.');
  }
});

Code Explanation:

Dependencies & Setup: Imports necessary modules (express, @vonage/messages, dotenv). Loads environment variables using dotenv.config().
Vonage Client Initialization:
- Performs essential validation to ensure all required environment variables are set. Exits if any are missing.
- Creates an instance of the Messages client using credentials from process.env within a try...catch block to handle potential initialization errors (e.g., bad key path).
Express Setup: Initializes the Express app and adds middleware to parse JSON and URL-encoded request bodies.
/send-mms Endpoint (POST):
- Defines an asynchronous route handler for POST /send-mms.
- Input Validation: Retrieves recipientNumber, imageUrl, and caption from the request body (req.body). Performs basic checks to ensure required fields are present and formats are plausible (digit-based number, valid URL). Returns a 400 Bad Request if validation fails.
- Payload Creation: Creates an MMSImage object. This is the specific payload type for sending image MMS via the Messages API. It requires:
  - to: The recipient's phone number. E.164 format (e.g., +12125551234) is recommended for international compatibility, but Vonage often handles US numbers without the +.
  - from: Your Vonage US MMS number from the .env file.
  - image: An object containing:
    - url: A publicly accessible URL pointing directly to the image file (.jpg, .png, .gif supported). Vonage needs to fetch the image from this URL.
    - caption: Optional text to accompany the image.
- Sending MMS: Calls vonageMessages.send(mmsPayload) within a try...catch block. This method returns a promise that resolves with the API response or rejects with an error.
- Response Handling:
  - If the send call is successful and returns a message_uuid, it logs success and sends a 200 OK response back to the client including the UUID.
  - If the call fails (throws an error), the catch block executes.
Error Handling:
- The catch block logs the detailed error.
- It attempts to extract useful information from the Vonage error response (if available) like the status code and error message (error.response.data).
- Sends an appropriate HTTP status code (e.g., 500, or the status from Vonage) and a JSON error message back to the client.
Webhook Placeholders: Includes basic handlers for /webhooks/status and /webhooks/inbound. These simply log the incoming webhook data and immediately return 200 OK. This is crucial because Vonage expects a quick success response for webhooks. In a real application, you would add logic here to process delivery statuses or handle incoming messages.
Server Start: Starts the Express server, listening on the port specified in .env (or 3000). Logs messages indicating the server is running and the endpoint is available.

5. Testing the API

You can test the /send-mms endpoint using tools like curl or Postman.

Start the Server: Open your terminal in the project directory and run:
```
node index.js
```
You should see output indicating the server is listening on port 3000.
Test with curl: Open a new terminal window. Replace placeholders with a valid recipient number (remember trial account restrictions) and a publicly accessible image URL.
```
curl -X POST http://localhost:3000/send-mms \
-H 'Content-Type: application/json' \
-d '{
  ""recipientNumber"": ""RECIPIENT_PHONE_NUMBER"",
  ""imageUrl"": ""https://placekitten.com/g/200/300"",
  ""caption"": ""Hello from Vonage MMS!""
}'
```
- Replace RECIPIENT_PHONE_NUMBER with the target phone number (e.g., 15551234567). If using a trial Vonage account, this number must be added to your allowed list in the Vonage Dashboard (under your profile/settings).
- You can use the placekitten.com URL for testing or any other direct link to a public image.

Expected Output (curl): If successful, you should receive a JSON response like this:

{
  ""success"": true,
  ""message"": ""MMS submitted successfully"",
  ""message_uuid"": ""some-unique-message-identifier""
}

Check Server Logs: Look at the terminal where node index.js is running. You should see logs indicating the request was received and the Vonage API response.
Check Recipient Phone: The recipient number should receive the MMS message with the image and caption shortly. Delivery times can vary.
Testing Errors:
- Invalid Input: Send a request missing recipientNumber or imageUrl. You should get a 400 Bad Request response.
- Invalid Credentials: Temporarily modify your .env file with incorrect API keys and restart the server. Send a request; you should get an authentication error (likely 401).
- Non-Whitelisted Number (Trial Account): If using a trial account, send to a number not on your whitelist. You should receive an error indicating the destination is not allowed.

6. Troubleshooting and Caveats

Trial Account Limitations: Vonage trial accounts can only send messages to phone numbers you have verified and added to your ""Allowed Numbers"" or ""Test Numbers"" list in the dashboard settings. Add your test recipient number there.
A2P (Application-to-Person) Only: The Vonage Messages API (and MMS in general via this method) is intended for Application-to-Person traffic. You generally cannot send MMS from one Vonage virtual number to another virtual number. The recipient must be a real mobile subscriber number.
US Sending Focus: Vonage MMS sending via the Messages API is primarily supported from US 10DLC, Toll-Free, or Short Code numbers to recipients within the US. International MMS support is limited and may vary. Check Vonage documentation for specifics.
Publicly Accessible Image URL: The imageUrl must point directly to the image file and be accessible from the public internet without requiring logins or special headers. Vonage servers need to fetch this image. Test the URL in an incognito browser window.
Correct SDK (@vonage/messages): Ensure you are using @vonage/messages and initializing it correctly, not the older @vonage/server-sdk's vonage.message.sendSms or similar methods, which do not support MMS via the Messages API standard flow.
Webhook URLs Must Be Public & Respond 200 OK: Even if you aren't processing them yet, the Status and Inbound URLs configured in your Vonage Application must be reachable by Vonage and return a 200 OK quickly. ngrok handles the public accessibility during development. Your placeholder routes in index.js handle the 200 OK response. Failure to respond correctly can lead to Vonage disabling webhooks for your application.
Private Key Path: Double-check the VONAGE_PRIVATE_KEY_PATH in your .env file exactly matches the location of your private.key file relative to where you run node index.js. The SDK expects a path to the file.
Application ID & Linked Number: Ensure you are using the correct Application ID and that your sending number is properly linked to that specific application in the Vonage dashboard.
Default API Set to Messages API: Re-verify the account-level setting mentioned in Step 2.3. Using the wrong default API (e.g., ""SMS API"") will cause incompatibility with the @vonage/messages SDK and webhook formats.
Rate Limiting: Vonage applies rate limits to API calls. For high-volume applications, implement proper queuing and potentially request limit increases from Vonage. The basic Express app doesn't include rate limiting; consider libraries like express-rate-limit for production.
Error Handling: The provided error handling is basic. Production applications should use a dedicated logging library (like Winston or Pino) and integrate with error tracking services (like Sentry). Parse Vonage error codes for more specific retry logic if needed.

7. Deployment and CI/CD (Conceptual)

Environment Variables: In production environments (like Heroku, AWS, Docker containers), do not commit your .env file. Use the hosting provider's mechanism for setting environment variables securely.
Hosting: Deploy this Node.js application like any other:
- PaaS (Heroku, Vercel): Configure environment variables via their dashboards/CLI. Ensure your Procfile (for Heroku) or build settings correctly start the server (node index.js).
- Docker: Create a Dockerfile to containerize the application, manage dependencies, and securely inject environment variables during container runtime.
- VPS/Server: Use process managers like pm2 to run the Node.js application reliably in the background. Configure environment variables via system environment or .env (with appropriate file permissions).
Webhooks in Production: Replace ngrok URLs in your Vonage Application settings with your production server's public URLs for the /webhooks/status and /webhooks/inbound endpoints. Ensure these endpoints are secured (e.g., via signature verification if needed, although basic 200 OK is often sufficient for status/inbound if processing happens elsewhere).
CI/CD: Set up pipelines (e.g., GitHub Actions, GitLab CI, Jenkins) to automate testing, building (if using TypeScript or a build step), and deploying your application to staging/production environments upon code changes.

8. Verification and Further Steps

Verification Checklist:

Vonage Account Created
API Key & Secret obtained and stored in .env
US MMS-Capable Number Purchased
Default SMS API set to Messages API in Vonage Settings
Vonage Application Created
Public/Private Key Pair Generated, private.key saved securely
Messages Capability Enabled in Application
Webhook URLs (Status/Inbound) configured (using ngrok or production URL)
Application ID obtained and stored in .env
Vonage Number Linked to the Application
Project initialized (npm init)
Dependencies installed (express, @vonage/messages, dotenv)
.gitignore configured correctly
.env file populated with all credentials and paths
index.js code implemented as shown
Server starts without errors (node index.js)
Test request sent via curl or Postman to /send-mms
Successful 200 OK response received from API with message_uuid
Server logs show successful submission
MMS message (image + caption) received on the recipient's phone

Next Steps:

Robust Error Handling: Implement more detailed parsing of Vonage error codes and potentially add retry logic for transient network issues.
Logging: Integrate a production-grade logging library (Winston, Pino).
Webhook Processing: Build out the logic in /webhooks/status to store or react to delivery receipts (e.g., delivered, failed). Implement /webhooks/inbound if you need to receive MMS/SMS replies.
Security: Implement webhook signature verification (if required for your security posture), add rate limiting (express-rate-limit), and sanitize all inputs thoroughly.
Input Validation: Use a dedicated validation library (like Joi or express-validator) for more complex validation rules.
Database Integration: Store message UUIDs, statuses, and other relevant information in a database for tracking and reporting.
Send Other Media: Explore sending video or other file types supported by MMS and the Vonage API.
Frontend Integration: Build a user interface that interacts with this API.

You now have a functional Node.js Express application capable of sending MMS messages using the Vonage Messages API. Remember to handle credentials securely and consult the Vonage Messages API documentation for more advanced features and details.