Send MMS Messages with Vonage, Node.js & Express

Build a production-ready Node.js application using the Express framework to send Multimedia Messaging Service (MMS) messages via the Vonage Messages API.

Learn everything from initial project setup and Vonage configuration to implementing the core sending logic, handling errors, securing credentials, and preparing for deployment. This tutorial covers all essential aspects of programmatic MMS sending, including A2P 10DLC registration requirements, file size optimization, and webhook handling for delivery tracking.

Project Overview and Goals

What You're Building:

A simple Node.js web server using Express that exposes an API endpoint. When this endpoint receives a request containing a recipient phone number, a sender number (your Vonage number), an image URL, and an optional caption, it uses the Vonage Messages API to send an MMS message.

Problem Solved:

This guide enables you to programmatically send rich media content (images) directly to users' mobile devices within the US, enhancing communication beyond simple text messages. Use this for sending product images, event flyers, visual alerts, or personalized media. Common applications include e-commerce order confirmations with product images, appointment reminders with QR codes, real estate listings with property photos, and marketing campaigns with promotional graphics.

Technologies Used:

• Node.js: A JavaScript runtime environment ideal for building efficient I/O-bound applications like web servers and APIs.
• Express: A minimal and flexible Node.js web application framework that simplifies building APIs and handling HTTP requests.
• Vonage Messages API: A powerful Vonage API that allows sending messages across various channels, including SMS and MMS, using a unified interface. We'll use it specifically for MMS.
• @vonage/server-sdk: The official Vonage Server SDK for Node.js, simplifying interaction with Vonage APIs.
• dotenv: A module to load environment variables from a .env file into process.env, keeping sensitive credentials out of source code.
• ngrok (for development): A tool to expose your local development server to the internet, necessary for receiving webhook callbacks from Vonage (like message status updates).

Critical MMS Technical Specifications:

• File Size Limits: MMS file size limits vary by carrier. All US carriers reliably handle up to 300 KB. Most US carriers support up to 1 MB, with some accepting up to 3.5 MB maximum. Recommended: Keep images under 500–600 KB for optimal delivery success and to avoid carrier compression or rejection. Files over 600 KB may be compressed or fail delivery on certain carriers/devices.
• Supported Image Formats: JPEG (.jpg, .jpeg), PNG (.png), and GIF (.gif) are universally supported. These three formats ensure maximum compatibility across carriers and devices. Other formats may be accepted but are not guaranteed to deliver successfully.
• US-Only Restriction: Vonage MMS is currently limited to sending from US numbers (10DLC, Toll-Free, or Short Code) to US destinations for Application-to-Person (A2P) messaging. MMS is not available for international destinations via Vonage Messages API as of January 2025.
• A2P 10DLC Registration: US carriers mandate 10DLC (10-Digit Long Code) registration for all A2P messaging, including MMS. Register your brand and campaign with Vonage before sending to US numbers. Toll-Free numbers and Short Codes have separate registration processes. Unregistered numbers face severe filtering and blocking.
• Content Restrictions: SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) is strictly prohibited on all US number types. Violations result in immediate suspension.

System Architecture:

A simplified view of the interaction:

+-------------+       +------------------------+       +----------------+       +-----------------+       +-----------------+
| HTTP Client | ----> | Node.js/Express Server | ----> | Vonage SDK     | ----> | Vonage Messages | ----> | Recipient Phone |
| (e.g., curl)|       | (API Endpoint)         |       | (@vonage/server|       | API             |       | (US Mobile)     |
+-------------+       +------------------------+       +----------------+       +-----------------+       +-----------------+
                          |                                                         ^
                          |                                                         | (Status Webhook)
                          +---------------------------------------------------------+
                          (Receives optional status updates via webhook endpoint)

Prerequisites:

• Node.js and npm (or yarn): Installed on your development machine. (Download Node.js)
• Vonage API Account: Sign up for free if you don't have one. (Sign up for Vonage)
• MMS-Capable US Vonage Number: You need a US-based virtual number from Vonage that supports both SMS and MMS. Purchase one via the Vonage dashboard (Numbers > Buy Numbers). Note: MMS via Vonage is currently restricted to sending from US numbers (10DLC, Toll-Free, Short Code) to US destinations for Application-to-Person (A2P) use cases.
• ngrok (Recommended for Development): For exposing your local server to receive status webhooks. (Download ngrok)
• Basic understanding of JavaScript, Node.js, REST APIs, and terminal commands.
• Estimated Time: 45–60 minutes for complete setup and testing.

Final Outcome:

By the end of this guide, you will have a functional Express application capable of sending MMS messages via a secure API endpoint, complete with basic error handling and configuration management using environment variables.

1. Setting up the Node.js Project

Initialize your Node.js project and install the necessary dependencies.

1. Create Project Directory: Open your terminal or command prompt and create a new directory for your project, then navigate into it.

   bash

   mkdir vonage-mms-sender
   cd vonage-mms-sender
   

2. Initialize Node.js Project: Use npm to create a package.json file. The -y flag accepts the default settings.

   bash

   npm init -y
   

3. Install Dependencies: Install Express, the Vonage Server SDK, and dotenv.

   bash

   npm install express @vonage/server-sdk dotenv
   
   • express: Web framework.
   • @vonage/server-sdk: Vonage API client library.
   • dotenv: Loads environment variables from a .env file.

4. Enable ES Modules (Optional but Recommended): To use modern import/export syntax, open your package.json file and add the following line at the top level:

   json

   // package.json
   {
     "name": "vonage-mms-sender",
     "version": "1.0.0",
     "description": "",
     "main": "index.js",
     "type": "module",
     "scripts": {
       "start": "node index.js",
       "dev": "node --watch index.js"
     },
     "keywords": [],
     "author": "",
     "license": "ISC",
     "dependencies": {
       "@vonage/server-sdk": "^3.x.x",
       "dotenv": "^16.x.x",
       "express": "^4.x.x"
     }
   }
   

   (Adjust version numbers based on what npm install added). If you prefer CommonJS (require), omit the "type": "module" line and use require syntax throughout the code. This guide uses ES Modules syntax.

5. Create Project Files: Create the main application file and the environment file.

   bash

   touch index.js .env .gitignore
   

6. Configure .gitignore: Add node_modules and your .env file to .gitignore to prevent committing them to version control. This is crucial for security.

   # .gitignore
   
   # Dependencies
   node_modules/
   
   # Environment variables
   .env
   
   # Vonage Private Key (if stored in project)
   private.key
   *.key
   
   # Logs
   *.log
   
   # OS generated files
   .DS_Store
   Thumbs.db
   

7. Project Structure: Your basic structure should now look like this:

   vonage-mms-sender/
   ├── node_modules/
   ├── .env
   ├── .gitignore
   ├── index.js
   └── package.json
   

This foundational setup provides a clean structure and installs the necessary tools for building your MMS sending application.

Note on SDK Version Compatibility: The current version of the Vonage Server SDK is v3.24.1 as of January 2025. This guide is designed to work with this version. If you encounter issues, ensure you are using the compatible SDK version. Check the SDK version in your package.json file or by running npm list @vonage/server-sdk in your project directory. To update the SDK, use npm update @vonage/server-sdk to get the latest compatible version. For more information on SDK compatibility and updates, refer to the Vonage Server SDK documentation.

2. Implementing Core Functionality (Sending MMS)

Write the core logic to interact with the Vonage SDK and send an MMS message. We'll encapsulate this in a reusable function.

1. Import Dependencies and Load Environment Variables: Open index.js and add the necessary imports. We use dotenv/config to load variables immediately.

   javascript

   // index.js
   import 'dotenv/config'; // Load .env variables immediately
   import { Vonage } from '@vonage/server-sdk';
   import path from 'path'; // Needed for resolving private key path
   
   // --- Environment Variable Validation (Optional but Recommended) ---
   const requiredEnvVars = [
       'VONAGE_APPLICATION_ID',
       'VONAGE_PRIVATE_KEY_PATH',
       'VONAGE_MMS_NUMBER', // Your Vonage MMS-capable number
   ];
   
   const missingEnvVars = requiredEnvVars.filter(varName => !process.env[varName]);
   
   if (missingEnvVars.length > 0) {
       console.error(`Error: Missing required environment variables: ${missingEnvVars.join(', ')}`);
       console.error('Please check your .env file.');
       process.exit(1); // Exit if critical configuration is missing
   }
   // --- End Environment Variable Validation ---
   
   
   // --- Vonage Client Initialization ---
   const vonage = new Vonage({
       applicationId: process.env.VONAGE_APPLICATION_ID,
       privateKey: path.resolve(process.env.VONAGE_PRIVATE_KEY_PATH) // Use path.resolve for robustness
   }, {
       // Optional: Custom settings like timeouts or appending user agent
       // appendUserAgent: 'my-mms-app/1.0.0'
   });
   
   const messagesClient = vonage.messages; // Access the Messages client
   // --- End Vonage Client Initialization ---
   
   /**
    * Sends an MMS message using the Vonage Messages API.
    *
    * @param {string} to - The recipient phone number (E.164 format, e.g., +14155550100).
    * @param {string} from - Your Vonage MMS-capable number (E.164 format).
    * @param {string} imageUrl - Publicly accessible URL of the image to send. MUST be HTTPS and publicly accessible without authentication. JPEG, PNG, or GIF format recommended. Keep files under 500–600 KB for best delivery rates.
    * @param {string} [caption] - Optional caption for the image.
    * @returns {Promise<object&gt;} - Promise resolving with the API response or rejecting with an error.
    *
    * @note Image URL Requirements:
    * - Must be publicly accessible via HTTPS (HTTP not supported)
    * - Cannot require authentication or have CORS restrictions
    * - Vonage servers must be able to fetch the image
    * - Common hosting: AWS S3 (public bucket), Cloudinary, Imgur, CDNs
    * - Avoid: localhost URLs, private networks, authenticated endpoints
    */
   async function sendMmsMessage(to, from, imageUrl, caption = '') {
       console.log(`Attempting to send MMS from ${from} to ${to} with image: ${imageUrl}`);
   
       // Input validation (basic)
       if (!to || !from || !imageUrl) {
           throw new Error('Missing required parameters: to, from, or imageUrl');
       }
       // Add more robust validation (e.g., E.164 format check, URL validation) in production
   
       try {
           const resp = await messagesClient.send({
               message_type: 'image', // Specify message type as image for MMS
               to: to,
               from: from,
               channel: 'mms', // Specify channel as MMS
               image: {
                   url: imageUrl,
                   caption: caption // Include caption if provided
               },
               // Optional: Client reference for tracking
               // client_ref: `my-mms-ref-${Date.now()}`
           });
   
           console.log('MMS Submitted Successfully:');
           console.log(`Message UUID: ${resp.message_uuid}`);
           return resp; // Return the success response
   
       } catch (err) {
           console.error('Error sending MMS:', err.response ? err.response.data : err.message);
           // Throw a more specific error or the original error
           throw err; // Re-throw the error for handling upstream
       }
   }
   
   // --- Placeholder for Express server setup (will add in next step) ---
   console.log('Core MMS sending logic initialized.');
   // --- End Placeholder ---
   
   // Example usage (for direct testing, uncomment and ensure TEST_RECIPIENT_NUMBER is set in .env)
   /*
   if (process.env.TEST_RECIPIENT_NUMBER) {
       sendMmsMessage(
           process.env.TEST_RECIPIENT_NUMBER,
           process.env.VONAGE_MMS_NUMBER,
           'https://placekitten.com/200/300', // Example image URL
           'Hello from Vonage MMS!'
       ).catch(err =&gt; console.error('Standalone test failed:', err));
   }
   */
   

2. Explanation:

   • Import necessary modules, including dotenv/config to load environment variables immediately.
   • Add basic environment variable validation to catch configuration errors early.
   • Initialize the Vonage client using the applicationId and privateKey path obtained from environment variables. path.resolve ensures the path works correctly regardless of where you run the script from.
   • Access the messages client specifically (vonage.messages).
   • The sendMmsMessage function takes to, from, imageUrl, and an optional caption.
   • Inside the function, perform basic validation checks for required parameters.
   • Call messagesClient.send() with the specific structure required for MMS:
     • message_type: 'image'
     • channel: 'mms'
     • image: { url: ..., caption: ... }
   • Use async/await for cleaner asynchronous code.
   • A try...catch block handles potential errors during the API call, logging details and re-throwing the error.
   • Logging provides visibility into the sending attempt and success/failure.
   • A commented-out example shows how you could test this function directly if needed.
   • Authentication: The Vonage SDK uses JWT (JSON Web Token) authentication. When you initialize the client with your application ID and private key, the SDK automatically generates a JWT for each API request. The private key signs the JWT, and Vonage validates it using the corresponding public key stored in your application settings. This ensures secure, authenticated communication without exposing your private key in API calls.

This core function encapsulates the interaction with Vonage for sending MMS, making it easy to integrate into your API layer.

3. Building the API Layer with Express

Create an Express server and define an API endpoint to trigger your sendMmsMessage function.

1. Set up Express Server: Add the following code to index.js, replacing the placeholder comments.

   javascript

   // index.js
   // ... (Keep imports, validation, Vonage init, and sendMmsMessage function from Step 2) ...
   
   import express from 'express';
   
   // --- Express App Setup ---
   const app = express();
   const PORT = process.env.PORT || 3000; // Use port from .env or default to 3000
   
   // Middleware
   app.use(express.json()); // Parse JSON request bodies
   app.use(express.urlencoded({ extended: true })); // Parse URL-encoded request bodies
   
   // Basic logging middleware (optional)
   app.use((req, res, next) => {
       console.log(`${new Date().toISOString()} – ${req.method} ${req.path}`);
       next();
   });
   // --- End Express App Setup ---
   
   
   // --- API Endpoints ---
   
   // Health check endpoint
   app.get('/health', (req, res) => {
       res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
   });
   
   // POST endpoint to send MMS
   app.post('/send-mms', async (req, res) => {
       const { to, imageUrl, caption } = req.body;
       const from = process.env.VONAGE_MMS_NUMBER; // Use the configured Vonage number
   
       // --- Request Validation ---
       if (!to || !imageUrl) {
           console.error('Validation Error: Missing "to" or "imageUrl" in request body');
           return res.status(400).json({
               success: false,
               message: 'Missing required fields: "to" and "imageUrl".'
           });
       }
   
       // Basic phone number format check (improve as needed)
       // Note: This regex is basic and checks for a plausible E.164-like format,
       // but doesn't guarantee the number is actually valid or routable.
       // For production, consider a more robust library like 'libphonenumber-js'.
       if (!/^\+?[1-9]\d{1,14}$/.test(to)) {
            console.error(`Validation Error: Invalid 'to' number format: ${to}`);
            return res.status(400).json({
                success: false,
                message: 'Invalid "to" phone number format. Use E.164 format (e.g., +14155550100).'
            });
       }
   
       // Basic URL format check (improve as needed)
        try {
           new URL(imageUrl);
        } catch (_) {
           console.error(`Validation Error: Invalid 'imageUrl' format: ${imageUrl}`);
           return res.status(400).json({
               success: false,
               message: 'Invalid "imageUrl" format. Provide a valid URL.'
           });
        }
       // --- End Request Validation ---
   
   
       try {
           const result = await sendMmsMessage(to, from, imageUrl, caption);
           console.log(`MMS request processed successfully for ${to}. Message UUID: ${result.message_uuid}`);
           res.status(202).json({ // 202 Accepted: Request received, processing initiated
               success: true,
               message: 'MMS sending request accepted.',
               message_uuid: result.message_uuid
           });
       } catch (error) {
           console.error(`API Error sending MMS to ${to}:`, error.message);
           // Provide a generic error message to the client for security
           res.status(500).json({
               success: false,
               message: 'Failed to send MMS due to an internal server error.'
               // Optionally include an error code or reference for tracking
               // error_ref: 'some-unique-id'
           });
       }
   });
   
   // --- Webhook Endpoint for Status Updates ---
   // This endpoint will receive delivery receipts from Vonage
   app.post('/webhooks/status', (req, res) => {
       console.log('--- Status Webhook Received ---');
       console.log('Body:', JSON.stringify(req.body, null, 2)); // Log the full status payload
       // Add logic here to process the status update (e.g., update database)
       // Example: Check for 'delivered', 'failed', 'rejected' status
       const { message_uuid, status, timestamp, error } = req.body;
       if (message_uuid && status) {
            console.log(`Status for ${message_uuid}: ${status} at ${timestamp}`);
            if (status === 'failed' || status === 'rejected') {
                console.error(`MMS Delivery Failed/Rejected: ${message_uuid}`, error || 'No error details provided');
            }
       }
   
       res.status(200).send('OK'); // Important: Respond with 200 OK quickly
   });
   // --- End Webhook Endpoint ---
   
   // --- End API Endpoints ---
   
   
   // --- Start Server ---
   app.listen(PORT, () => {
       console.log(`Server listening on port ${PORT}`);
       console.log(`API Endpoint: POST http://localhost:${PORT}/send-mms`);
       console.log(`Status Webhook: POST http://localhost:${PORT}/webhooks/status`);
       console.log(`Health Check: GET http://localhost:${PORT}/health`);
   });
   // --- End Start Server ---
   

2. Explanation:

   • Import express and create an app instance.
   • Define the PORT using an environment variable or defaulting to 3000.
   • Add essential middleware (express.json, express.urlencoded) to parse incoming request bodies.
   • A simple logging middleware shows basic request information.
   • Add a /health endpoint for basic service monitoring.
   • The /send-mms endpoint is a POST route:
     • Extract to, imageUrl, and caption from the req.body.
     • Retrieve the from number directly from the environment variable.
     • Request Validation: Perform checks for required fields and basic format validation for the phone number (with added note about limitations) and URL. Send appropriate 400 Bad Request responses on failure.
     • Call the sendMmsMessage function within a try...catch block.
     • Success Response: On success, return a 202 Accepted status (as sending is asynchronous) along with the message_uuid.
     • Error Response: On failure, log the detailed error internally and return a generic 500 Internal Server Error response to the client.
   • Add a /webhooks/status endpoint to receive delivery status updates from Vonage. It logs the incoming payload and sends back a 200 OK immediately. This endpoint is crucial for tracking message delivery.
   • Finally, app.listen starts the server.

3. Testing the API Endpoint:

   • Set up your Vonage credentials first (see next section).
   • Run the server: npm start or npm run dev.
   • Use curl or a tool like Postman to send a POST request:
   bash

   curl -X POST http://localhost:3000/send-mms \
   -H "Content-Type: application/json" \
   -d '{
     "to": "+14155550100",
     "imageUrl": "https://placekitten.com/g/300/200",
     "caption": "Test MMS from Express!"
   }'
   
   • Replace +14155550100 with a valid US test number (whitelisted if on trial).
   • Expected Success Response (JSON):
     json

     {
       "success": true,
       "message": "MMS sending request accepted.",
       "message_uuid": "some-unique-message-identifier"
     }
     
   • Expected Error Response (e.g., missing field):
     json

     {
       "success": false,
       "message": "Missing required fields: \"to\" and \"imageUrl\"."
     }
     

This API layer provides a structured way to interact with your MMS sending logic via HTTP requests.

4. Integrating with Vonage (Configuration & Credentials)

Proper configuration is key to connecting your application with Vonage.

1. Vonage API Account: Ensure you have a Vonage account.

2. Purchase/Verify MMS Number:

   • Navigate to your Vonage API Dashboard.
   • Go to Numbers > Buy numbers.
   • Search for numbers in the "United States".
   • Ensure the number has "SMS" and "MMS" capabilities listed.
   • Purchase the number. Note down this number in E.164 format (e.g., +12015550123).

3. Create a Vonage Application: The Messages API uses Applications and public/private key pairs for authentication when sending.

   • In the Dashboard, go to Applications > Create a new application.
   • Give your application a name (e.g., "My Express MMS App").
   • Click "Generate public and private key". Immediately save the private.key file that downloads. Store this securely and do not commit it to Git. A good practice is to place it outside your project directory or in a secure location referenced by your environment variables. For simplicity in this guide, you could place it in the project root, but ensure it's in .gitignore.
   • Enable the "Messages" capability.
   • Configure Webhooks: Provide URLs for Vonage to send status updates and potentially inbound messages (though we aren't handling inbound MMS in this guide).
     • Status URL: This is where Vonage sends delivery receipts (DLRs). Use your /webhooks/status endpoint. During local development, you need ngrok:
       • Run ngrok http 3000 (assuming your server runs on port 3000).
       • Copy the https Forwarding URL provided by ngrok (e.g., https://<unique-id&gt;.ngrok.io).
       • Enter <your-ngrok-url&gt;/webhooks/status into the "Status URL" field (e.g., https://<unique-id&gt;.ngrok.io/webhooks/status). Set the method to POST.
     • Inbound URL: Even if not used now, it's often required. You can reuse the Status URL or point it to a different endpoint if you plan to receive MMS/SMS later. Enter <your-ngrok-url&gt;/webhooks/inbound (or reuse status) and set method to POST.
   • Click "Generate new application".
   • On the next page, note down the Application ID.
   • Link Your Number: Scroll down to "Link virtual numbers" and link the MMS-capable US number you purchased earlier to this application.

4. Configure Environment Variables (.env): Create or open the .env file in your project root and add the following, replacing the placeholder values:

   bash

   # .env
   
   # Vonage Credentials
   # Found in Application settings after creating an application
   VONAGE_APPLICATION_ID="YOUR_APPLICATION_ID"
   
   # Path to the private key file you downloaded when creating the application
   # Example: ./private.key (if in project root) or /path/to/secure/storage/private.key
   VONAGE_PRIVATE_KEY_PATH="./private.key" # MAKE SURE THIS IS IN .gitignore
   
   # Your Vonage MMS-capable number (E.164 format)
   # Purchased from the Vonage dashboard and linked to the application
   VONAGE_MMS_NUMBER="+12015550123"
   
   # --- Optional / Development ---
   
   # Port for the Express server
   PORT=3000
   
   # Test recipient number (whitelisted if on Vonage trial account)
   # Used ONLY for the commented-out standalone test block in Section 2 of index.js
   # TEST_RECIPIENT_NUMBER="+14155550100"
   
   • VONAGE_APPLICATION_ID: The ID generated when you created the Vonage application.
   • VONAGE_PRIVATE_KEY_PATH: The file path to the private.key file you saved. Ensure this path is correct relative to where you run node index.js.
   • VONAGE_MMS_NUMBER: Your purchased US Vonage number capable of sending MMS, in E.164 format.
   • PORT: The port your Express server will listen on.
   • TEST_RECIPIENT_NUMBER: Only used if you uncomment the test block at the end of Section 2. Needs to be a number whitelisted on your Vonage trial account if applicable.
   • Security: Remember, the .env file and the private.key file contain sensitive credentials. Never commit them to version control. Use your .gitignore file properly.

5. Vonage Trial Account Restrictions: If your Vonage account is new and still in trial mode (you haven't added payment details and made a payment), you can typically only send messages to phone numbers you have verified and added to your Vonage dashboard's "test numbers" list. Navigate to your Dashboard > Account > Settings > Test Numbers to add and verify them.

6. Webhook Security (Important for Production): In production, verify that webhook requests actually come from Vonage by validating the signature. Vonage signs webhook requests using your application's signature secret. Implement signature verification in your webhook handler to prevent malicious requests. Refer to the Vonage webhook signature verification documentation for implementation details.

With these steps, your application is configured to authenticate with Vonage using your application credentials and send messages from your designated Vonage number. The status webhook configuration enables you to receive feedback on message delivery.

5. Implementing Error Handling, Logging, and Retry Mechanisms

Robust applications need proper error handling and logging.

1. Error Handling (Improved):

   • Specific Errors: The current sendMmsMessage function catches errors from the Vonage SDK. The SDK might throw errors for various reasons (invalid credentials, network issues, invalid parameters, API errors from Vonage). The error object often contains valuable details in err.response.data or err.message.
   • API Endpoint Errors: The /send-mms endpoint handles errors from sendMmsMessage and validation errors. It correctly logs detailed errors internally while returning user-friendly messages (e.g., 500 Internal Server Error) to the client, preventing potential information leakage.
   • Status Webhook Errors: Failures in processing the status webhook should be logged, but the endpoint must still return 200 OK quickly to Vonage to prevent unnecessary retries from their side. Handle processing asynchronously if it's complex.

2. Logging:

   • Current Logging: We have basic console.log and console.error statements. This is sufficient for development but not ideal for production.
   • Production Logging: Consider using a dedicated logging library like winston or pino. These offer:
     • Log Levels: (debug, info, warn, error) to control verbosity.
     • Structured Logging: Outputting logs in JSON format for easier parsing by log management systems (e.g., Datadog, Splunk, ELK stack).
     • Transports: Sending logs to files, databases, or external services.
   • Example (Conceptual pino integration):
     javascript

     // --- Add near top of index.js ---
     import pino from 'pino';
     const logger = pino({ level: process.env.LOG_LEVEL || 'info' });
     
     // --- Replace console.log/error with logger ---
     // Example in sendMmsMessage catch block:
     // logger.error({ err: err.response?.data || err.message, to, from, imageUrl }, 'Error sending MMS');
     // Example in API success:
     // logger.info({ to, message_uuid: result.message_uuid }, 'MMS request processed successfully');
     // Example in Status Webhook:
     // logger.info({ body: req.body }, 'Status Webhook Received');
     

3. Retry Mechanisms:

   • Vonage Delivery Retries: Vonage automatically handles retries for delivering the message to the carrier/handset if temporary issues occur. Monitor this via the Status Webhook.
   • API Call Retries: Your call from Express to the Vonage API might fail due to transient network issues or temporary Vonage hiccups (e.g., 5xx errors from Vonage). You could implement a retry strategy here, potentially with exponential backoff. Libraries like async-retry can help.
   • Caution: Be careful retrying API calls that might have partially succeeded or have side effects. Check Vonage documentation for idempotency guarantees or use the client_ref parameter if supported for tracking. Retrying on validation errors (4xx) is generally pointless.
   • Simple Retry Example (Conceptual):
     javascript

     // Using a library like 'async-retry'
     import retry from 'async-retry';
     // Assuming 'logger' is initialized as shown previously
     import pino from 'pino';
     const logger = pino({ level: process.env.LOG_LEVEL || 'info' });
     
     async function sendMmsWithRetry(to, from, imageUrl, caption) {
         return retry(async (bail, attempt) => {
             logger.info(`Attempt ${attempt} to send MMS to ${to}`);
             try {
                 // Assume sendMmsMessage function exists as defined earlier
                 return await sendMmsMessage(to, from, imageUrl, caption);
             } catch (err) {
                 // Don't retry on client errors (4xx)
                 // Use optional chaining ?. to safely access nested properties
                 if (err.response?.status >= 400 && err.response?.status < 500) {
                     logger.warn(`Non-retryable error sending MMS (status ${err.response.status}). Bailing.`);
                     bail(err); // Stop retrying
                     return; // Needed to prevent fall-through
                 }
                  // For other errors (network_ 5xx)_ throw to trigger retry
                  logger.warn(`Retryable error sending MMS: ${err.message}. Retrying…`);
                  throw err; // Re-throw the error to signal retry is needed
             }
         }_ {
             retries: 3_ // Number of retries
             factor: 2_ // Exponential backoff factor
             minTimeout: 1000_ // Minimum delay ms
             onRetry: (error_ attempt) => {
                 logger.warn(`Retrying MMS send to ${to} (Attempt ${attempt}) after error: ${error.message}`);
             }
         });
     }
     
     // In the API endpoint, call sendMmsWithRetry instead of sendMmsMessage
     // try {
     //   const result = await sendMmsWithRetry(to, from, imageUrl, caption);
     //   // ... rest of success handling
     // } catch (error) {
     //   // ... error handling (log final failure, return 500)
     // }
     

Choose logging and retry strategies appropriate for your application's scale and reliability requirements. Start simple and enhance as needed.

6. Creating a Database Schema and Data Layer (Optional)

While not strictly required for just sending MMS, storing message information is common in real-world applications for tracking, reporting, and debugging.

• Why Store Data?

  • Keep a record of sent messages (recipient, time, content reference).
  • Track message status updates received via webhook (delivered, failed, etc.).
  • Correlate sending requests with delivery outcomes.
  • Enable reporting and analytics.

• Potential Schema (Conceptual – e.g., PostgreSQL with Prisma):

  sql

  // schema.prisma
  
  datasource db {
    provider = "postgresql" // or mysql, sqlite
    url      = env("DATABASE_URL")
  }
  
  generator client {
    provider = "prisma-client-js"
  }
  
  model MmsMessage {
    id            String   @id @default(cuid()) // Unique internal ID
    messageUuid   String   @unique @map("message_uuid") // Vonage Message UUID
    recipient     String
    sender        String
    imageUrl      String   @map("image_url")
    caption       String?
    status        String   @default("submitted") // e.g., submitted, delivered, failed, rejected
    clientRef     String?  @unique @map("client_ref") // Optional client reference
    submittedAt   DateTime @default(now()) @map("submitted_at")
    lastUpdatedAt DateTime @updatedAt @map("last_updated_at")
    errorCode     String?  @map("error_code") // From status webhook on failure
    errorReason   String?  @map("error_reason") // From status webhook on failure
  
    @@index([status])
    @@index([submittedAt])
  }
  

• Implementation Steps (If Adding Database):

  1. Choose a database (PostgreSQL, MySQL, MongoDB, etc.).
  2. Select an ORM/ODM (like Prisma, Sequelize, Mongoose).
  3. Define your schema.
  4. Set up database connection logic with connection pooling for performance.
  5. Modify the API endpoint (/send-mms) to create a record in the database before or after calling sendMmsMessage. Store the message_uuid returned by Vonage.
  6. Modify the webhook handler (/webhooks/status) to find the corresponding message record using message_uuid and update its status, lastUpdatedAt, and potentially errorCode/errorReason.
  7. Use database transactions when updating records to ensure data consistency.
  8. Implement proper indexing on frequently queried fields (status, submittedAt, messageUuid) for optimal query performance.

Frequently Asked Questions (FAQ)

What is the maximum MMS file size I can send with Vonage?

While some carriers accept up to 3.5 MB, all US carriers reliably handle up to 300 KB. For optimal delivery rates and to avoid carrier compression or rejection, keep images under 500–600 KB. Files over 600 KB may be compressed by carriers or fail delivery on certain devices.

Which image formats are supported for MMS messaging?

JPEG (.jpg, .jpeg), PNG (.png), and GIF (.gif) are universally supported formats that ensure maximum compatibility across all US carriers and devices. While other formats may be accepted, these three formats guarantee successful delivery.

Can I send MMS internationally with Vonage?

No, Vonage MMS is currently limited to sending from US numbers (10DLC, Toll-Free, or Short Code) to US destinations only for Application-to-Person (A2P) messaging. International MMS is not available via Vonage Messages API as of January 2025.

What is A2P 10DLC registration and do I need it for MMS?

A2P 10DLC (Application-to-Person 10-Digit Long Code) registration is mandatory for all business messaging in the US, including MMS. Register your brand and campaign with Vonage before sending to US numbers. Unregistered numbers face severe filtering and blocking by carriers. Registration typically takes 1–2 weeks and costs vary by throughput tier.

How do I handle MMS delivery status updates?

Configure a webhook endpoint in your Vonage application settings to receive delivery receipts (DLRs). Vonage will POST status updates (submitted, delivered, failed, rejected) to your webhook URL. Your endpoint must respond with HTTP 200 OK quickly to acknowledge receipt.

Why must my image URL be publicly accessible HTTPS?

Vonage servers need to fetch the image from your URL to send it via MMS. The URL must be publicly accessible via HTTPS (HTTP not supported), without authentication or CORS restrictions. Common hosting solutions include AWS S3 (public bucket), Cloudinary, Imgur, or CDN services.

What happens if my MMS message fails to deliver?

Vonage will attempt delivery and send a status webhook with failure details. Common reasons include invalid recipient numbers, carrier rejections, file size limits exceeded, unsupported formats, or unregistered 10DLC numbers. Check the error code and reason in the webhook payload for specific details.

How do I test MMS sending on a Vonage trial account?

Trial accounts can only send to verified test numbers. Add and verify test numbers in your Vonage Dashboard under Account > Settings > Test Numbers. Once verified, you can send MMS to these numbers for testing. Upgrade your account to send to any US number.

What are SHAFT content restrictions for MMS?

SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) is strictly prohibited on all US number types for A2P messaging. Violations result in immediate account suspension. Ensure your MMS content complies with carrier guidelines and CTIA messaging principles.

Can I send MMS with captions using Vonage?

Yes, the Vonage Messages API supports optional captions for MMS images. Include the caption parameter in your API request. The caption appears as text alongside the image in the recipient's messaging app.

How long does it take for an MMS to be delivered?

MMS delivery is typically near-instantaneous (within seconds) but can vary based on carrier processing, network conditions, and recipient device status. Monitor delivery status via webhooks to track actual delivery times for each message.

What version of the Vonage Node.js SDK should I use?

This guide uses @vonage/server-sdk v3.24.1 (latest as of January 2025). Version 3.x provides Promise-based APIs, TypeScript support, and improved error handling. Use npm install @vonage/server-sdk to install the latest compatible version.

How do I deploy this application to production?

For production deployment:

1. Use environment-specific configuration for different environments (development, staging, production).
2. Implement security headers (helmet.js), CORS configuration, and API authentication.
3. Set up connection pooling for database connections.
4. Use a process manager like PM2 or deploy to a platform like Heroku, AWS, or Google Cloud.
5. Configure proper logging and monitoring (New Relic, Datadog, CloudWatch).
6. Implement rate limiting to prevent abuse.
7. Set up proper SSL/TLS certificates for webhook endpoints.
8. Use a load balancer for horizontal scaling if needed.

Related Resources

• Vonage SMS API with Node.js & Express – Learn to send text messages using the Vonage SMS API
• Understanding E.164 Phone Number Format – Complete guide to international phone number formatting
• A2P 10DLC Registration Guide – Step-by-step instructions for registering your brand and campaign
• Vonage Webhook Configuration Best Practices – Optimize webhook handling for production applications
• MMS vs SMS: When to Use Which – Compare capabilities and use cases for multimedia vs text messaging
• Vonage Messages API Reference – Official API documentation for all messaging channels