Send MMS with Images Using Twilio Node.js and Express

mkdir twilio-mms-sender
cd twilio-mms-sender

npm init -y

npm install express twilio dotenv

touch index.js .env .gitignore

# Dependencies
node_modules

# Environment variables
.env

# Logs
*.log

# Operating system files
.DS_Store
Thumbs.db

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

# Twilio API Credentials
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+14155552671

# Server Configuration
PORT=3000

// index.js
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const twilio = require('twilio');

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

// ---- Twilio Client Initialization ----
// Validate essential environment variables
const requiredEnv = [
    'TWILIO_ACCOUNT_SID',
    'TWILIO_AUTH_TOKEN',
    'TWILIO_PHONE_NUMBER'
];
requiredEnv.forEach(key => {
    if (!process.env[key]) {
        console.error(`Error: Missing required environment variable ${key}`);
        process.exit(1); // Exit if critical config is missing
    }
});

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

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

    // Basic Input Validation
    const { to, imageUrl, caption } = req.body;
    const from = process.env.TWILIO_PHONE_NUMBER; // Sender number from .env

    if (!to || !imageUrl) {
        console.error('Validation Error: Missing `to` or `imageUrl` in request body');
        return res.status(400).json({ success: false, error: 'Missing required fields: `to` and `imageUrl`' });
    }

    // Validate 'to' number format (basic check for E.164 potential, allows optional +)
    if (!/^\+?[1-9]\d{1,14}$/.test(to)) {
        console.error(`Validation Error: Invalid 'to' number format: ${to}`);
        return res.status(400).json({ success: false, error: 'Invalid `to` number format. Use E.164 format (e.g., +14155552671).' });
    }

    // Ensure imageUrl is a valid URL (basic check)
    try {
        new URL(imageUrl);
    } catch (_) {
        console.error(`Validation Error: Invalid 'imageUrl': ${imageUrl}`);
        return res.status(400).json({ success: false, error: 'Invalid `imageUrl`. Must be a valid, publicly accessible URL.' });
    }

    // Construct the MMS payload for Twilio
    const mmsPayload = {
        body: caption || '', // Optional text caption
        from: from,
        to: to,
        mediaUrl: [imageUrl] // Array of media URLs (Twilio supports multiple)
    };

    console.log('Attempting to send MMS with payload:', JSON.stringify(mmsPayload, null, 2));

    // ---- Send the MMS using Twilio SDK ----
    try {
        const message = await client.messages.create(mmsPayload);
        console.log('Twilio API Success Response:', message);
        // Success response structure: { sid: '...', status: '...', ... }
        res.status(200).json({
            success: true,
            messageSid: message.sid,
            status: message.status
        });

    } catch (error) {
        console.error('Twilio API Error:', error);

        // Provide more specific feedback if possible
        let errorMessage = 'Failed to send MMS.';
        let statusCode = 500;
        let errorDetails = null;

        if (error.code) {
            // Twilio-specific error codes
            errorDetails = {
                code: error.code,
                message: error.message,
                moreInfo: error.moreInfo
            };

            // Handle common Twilio error codes
            if (error.code === 21408) {
                errorMessage = 'Permission denied: Check your Twilio account status or number capabilities.';
                statusCode = 403;
            } else if (error.code === 21614) {
                errorMessage = 'Invalid phone number format. Use E.164 format (e.g., +14155552671).';
                statusCode = 400;
            } else if (error.code === 21610) {
                errorMessage = 'Unsubscribed recipient: The recipient has opted out of messages from this number.';
                statusCode = 400;
            } else if (error.code === 63016) {
                errorMessage = 'Media file too large or invalid format. Keep images under 5MB.';
                statusCode = 400;
            } else {
                errorMessage = `Twilio Error ${error.code}: ${error.message}`;
                statusCode = error.status || 500;
            }
        } else if (error.status) {
            errorMessage = `Twilio API request failed with status: ${error.status}`;
            statusCode = error.status;
        } else {
            errorMessage = `Failed to send MMS: ${error.message}`;
        }

        res.status(statusCode).json({ success: false, error: errorMessage, details: errorDetails });
    }
});

// ---- Basic Health Check Endpoint ----
app.get('/health', (req, res) => {
    res.status(200).json({ status: 'UP' });
});

// ---- Start the Server ----
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
    console.log(`Twilio Number (Sender): ${process.env.TWILIO_PHONE_NUMBER}`);
    console.log(`Try POSTing to http://localhost:${PORT}/send-mms`);
});

# Start the server
node index.js

# In another terminal, send a test request
curl -X POST http://localhost:3000/send-mms \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552672",
    "imageUrl": "https://demo.twilio.com/owl.png",
    "caption": "Check out this image!"
  }'

npm install async-retry

const retry = require('async-retry');

// Inside the /send-mms route's main try block, after validation and payload construction:
try {
    // ... (input validation code remains here) ...
    // ... (mmsPayload construction remains here) ...
    console.log('Attempting to send MMS with payload:', JSON.stringify(mmsPayload, null, 2));

    // ---- Wrap only the Twilio call with retry logic ----
    const message = await retry(async bail => {
        // bail is a function to stop retrying for non-recoverable errors
        try {
            console.log('Calling client.messages.create...'); // Log each attempt
            const result = await client.messages.create(mmsPayload);
            console.log('Twilio API call successful within retry block.');
            return result; // Success, return result
        } catch (error) {
            console.error('Twilio API call failed within retry block:', error.code, error.message);

            // Don't retry on client errors (4xx) except 429 (Rate Limit)
            if (error.status && error.status >= 400 && error.status < 500 && error.status !== 429) {
                bail(new Error(`Non-retriable Twilio error: ${error.code}`));
                return;
            }
            // For other errors (5xx, network issues, 429), throw to trigger retry
            throw error;
        }
    }, {
        retries: 3, // Number of retries
        factor: 2, // Exponential backoff factor
        minTimeout: 1000, // Initial delay ms (1 second)
        maxTimeout: 10000, // Maximum delay between retries (10 seconds)
        onRetry: (error, attempt) => {
            console.warn(`Twilio API call failed (attempt ${attempt}), retrying... Error: ${error.message}`);
        }
    });

    console.log('Twilio API Success Response (after potential retries):', message);
    res.status(200).json({
        success: true,
        messageSid: message.sid,
        status: message.status
    });

} catch (error) {
    // Handle final errors after all retries
    console.error('Error sending MMS (final):', error);
    // ... error response handling
}

-- PostgreSQL example
CREATE TABLE mms_messages (
    id SERIAL PRIMARY KEY,
    message_sid VARCHAR(255) UNIQUE NOT NULL,
    recipient_number VARCHAR(20) NOT NULL,
    sender_number VARCHAR(20) NOT NULL,
    image_url TEXT NOT NULL,
    caption TEXT,
    status VARCHAR(50) DEFAULT 'queued',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE delivery_receipts (
    id SERIAL PRIMARY KEY,
    message_sid VARCHAR(255) REFERENCES mms_messages(message_sid),
    status VARCHAR(50) NOT NULL,
    timestamp TIMESTAMP NOT NULL,
    error_code VARCHAR(50),
    error_message TEXT
);

CREATE INDEX idx_message_sid ON mms_messages(message_sid);
CREATE INDEX idx_recipient ON mms_messages(recipient_number);
CREATE INDEX idx_status ON mms_messages(status);

npm install joi

const Joi = require('joi');

// Define validation schema
const mmsSchema = Joi.object({
    to: Joi.string()
        .pattern(/^\+?[1-9]\d{1,14}$/)
        .required()
        .messages({
            'string.pattern.base': 'Invalid phone number format. Use E.164 format (e.g., +14155552671)',
            'any.required': 'Recipient number is required'
        }),
    imageUrl: Joi.string()
        .uri()
        .required()
        .messages({
            'string.uri': 'Invalid image URL',
            'any.required': 'Image URL is required'
        }),
    caption: Joi.string()
        .max(1000)
        .allow('')
        .optional()
});

// In your route handler
const { error, value } = mmsSchema.validate(req.body);
if (error) {
    return res.status(400).json({
        success: false,
        error: error.details[0].message
    });
}

npm install express-rate-limit

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // Limit each IP to 100 requests per windowMs
    standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
    legacyHeaders: false, // Disable the `X-RateLimit-*` headers
    message: 'Too many requests from this IP, please try again after 15 minutes',
    handler: (req, res) => {
        res.status(429).json({
            success: false,
            error: 'Too many requests, please try again later'
        });
    }
});

// Apply rate limiting to specific endpoints
app.use('/send-mms', limiter);

npm install rate-limit-redis redis

const RedisStore = require('rate-limit-redis');
const redis = require('redis');

const redisClient = redis.createClient({
    host: process.env.REDIS_HOST,
    port: process.env.REDIS_PORT
});

const limiter = rateLimit({
    store: new RedisStore({
        client: redisClient,
        prefix: 'rate-limit:'
    }),
    windowMs: 15 * 60 * 1000,
    max: 100
});

// Simple API key authentication
const authenticateApiKey = (req, res, next) => {
    const apiKey = req.headers['x-api-key'];

    if (!apiKey || apiKey !== process.env.API_KEY) {
        return res.status(401).json({
            success: false,
            error: 'Unauthorized: Invalid or missing API key'
        });
    }

    next();
};

// Apply to protected routes
app.post('/send-mms', authenticateApiKey, async (req, res) => {
    // ... route handler code
});

npm install cors

const cors = require('cors');

// Allow specific origins
app.use(cors({
    origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
    methods: ['GET', 'POST'],
    allowedHeaders: ['Content-Type', 'Authorization', 'x-api-key']
}));

const http = require('http');
const https = require('https');

// Increase connection pool size for high-volume scenarios
http.globalAgent.maxSockets = 100;
https.globalAgent.maxSockets = 100;

# Install k6
brew install k6  # macOS
# or download from https://k6.io/

# Create a test script (load-test.js)

// load-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
    stages: [
        { duration: '30s', target: 10 },  // Ramp up to 10 users
        { duration: '1m', target: 10 },   // Stay at 10 users
        { duration: '30s', target: 0 },   // Ramp down
    ],
};

export default function () {
    const payload = JSON.stringify({
        to: '+14155552672',
        imageUrl: 'https://demo.twilio.com/owl.png',
        caption: 'Load test'
    });

    const params = {
        headers: {
            'Content-Type': 'application/json',
            'x-api-key': 'YOUR_API_KEY'
        },
    };

    const res = http.post('http://localhost:3000/send-mms', payload, params);

    check(res, {
        'status is 200': (r) => r.status === 200,
        'response time < 3000ms': (r) => r.timings.duration < 3000,
    });

    sleep(1);
}

# Run the test
k6 run load-test.js

# Node.js built-in profiler
node --prof index.js
# After stopping, process the log
node --prof-process isolate-*.log > processed.txt

# Or use Clinic.js for better visualization
npm install -g clinic
clinic doctor -- node index.js

app.get('/health', async (req, res) => {
    const health = {
        status: 'UP',
        timestamp: new Date().toISOString(),
        uptime: process.uptime(),
        checks: {}
    };

    // Check Twilio connectivity (basic)
    try {
        // Simple check – verify SDK is initialized
        if (client) {
            health.checks.twilio = { status: 'UP', message: 'SDK initialized' };
        } else {
            health.checks.twilio = { status: 'DOWN', message: 'SDK not initialized' };
            health.status = 'DOWN';
        }
    } catch (error) {
        health.checks.twilio = { status: 'DOWN', message: error.message };
        health.status = 'DOWN';
    }

    // Check environment variables
    const requiredEnvVars = ['TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN', 'TWILIO_PHONE_NUMBER'];
    const missingVars = requiredEnvVars.filter(v => !process.env[v]);

    if (missingVars.length > 0) {
        health.checks.config = {
            status: 'DOWN',
            message: `Missing env vars: ${missingVars.join(', ')}`
        };
        health.status = 'DOWN';
    } else {
        health.checks.config = { status: 'UP', message: 'All required env vars present' };
    }

    const statusCode = health.status === 'UP' ? 200 : 503;
    res.status(statusCode).json(health);
});

npm install prom-client

const promClient = require('prom-client');

// Create a Registry
const register = new promClient.Registry();

// Add default metrics (CPU, memory, event loop lag)
promClient.collectDefaultMetrics({ register });

// Custom metrics
const httpRequestDuration = new promClient.Histogram({
    name: 'http_request_duration_seconds',
    help: 'Duration of HTTP requests in seconds',
    labelNames: ['method', 'route', 'status_code'],
    buckets: [0.1, 0.5, 1, 2, 5]
});

const mmsMessagesSent = new promClient.Counter({
    name: 'mms_messages_sent_total',
    help: 'Total number of MMS messages sent',
    labelNames: ['status']
});

register.registerMetric(httpRequestDuration);
register.registerMetric(mmsMessagesSent);

// Middleware to track request duration
app.use((req, res, next) => {
    const start = Date.now();

    res.on('finish', () => {
        const duration = (Date.now() - start) / 1000;
        httpRequestDuration
            .labels(req.method, req.route?.path || req.path, res.statusCode)
            .observe(duration);
    });

    next();
});

// Update your /send-mms route to track success/failure
// In the success case:
mmsMessagesSent.labels('success').inc();

// In the error case:
mmsMessagesSent.labels('error').inc();

// Metrics endpoint
app.get('/metrics', async (req, res) => {
    res.set('Content-Type', register.contentType);
    res.end(await register.metrics());
});

npm install @sentry/node @sentry/tracing

// In index.js, initialize early
const Sentry = require('@sentry/node');
const Tracing = require('@sentry/tracing');

Sentry.init({
  dsn: "YOUR_SENTRY_DSN", // Get from Sentry project settings
  integrations: [
    new Sentry.Integrations.Http({ tracing: true }),
    new Tracing.Integrations.Express({ app }),
  ],
  tracesSampleRate: 0.1, // 10% of transactions for performance monitoring
  environment: process.env.NODE_ENV || 'development',
  release: 'twilio-mms-sender@' + process.env.npm_package_version,
});

// RequestHandler creates a separate execution context
app.use(Sentry.Handlers.requestHandler());
// TracingHandler creates a trace for every incoming request
app.use(Sentry.Handlers.tracingHandler());

// --- Your routes go here ---

// Error handler must be before any other error middleware and after all controllers
app.use(Sentry.Handlers.errorHandler());

// Optional fallthrough error handler
app.use(function onError(err, req, res, next) {
  res.statusCode = 500;
  res.json({ success: false, error: 'Internal Server Error' });
});

npm install winston

const winston = require('winston');

const logger = winston.createLogger({
    level: process.env.LOG_LEVEL || 'info',
    format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.errors({ stack: true }),
        winston.format.json()
    ),
    defaultMeta: { service: 'twilio-mms-sender' },
    transports: [
        new winston.transports.File({ filename: 'error.log', level: 'error' }),
        new winston.transports.File({ filename: 'combined.log' }),
    ],
});

// Add console transport in non-production
if (process.env.NODE_ENV !== 'production') {
    logger.add(new winston.transports.Console({
        format: winston.format.simple(),
    }));
}

// Replace console.log/error with logger
logger.info('Server starting up');
logger.error('Error occurred', { error: error.message, stack: error.stack });

┌─────────────────────────┐
│   MMS Send Failed?      │
└────────┬────────────────┘
         │
         ├─→ Check HTTP status code
         │
         ├─→ 400 Bad Request → Validate input format
         │
         ├─→ 401 Unauthorized → Check API credentials
         │
         ├─→ 403 Forbidden → Check account status & A2P registration
         │
         ├─→ 21614 Invalid Number → Check phone number format
         │
         ├─→ 63016 Media Error → Check image URL & size
         │
         ├─→ 429 Rate Limit → Implement backoff/wait
         │
         ├─→ 500 Server Error → Check Twilio status page
         │
         └─→ No response → Check network connectivity

heroku config:set TWILIO_ACCOUNT_SID=ACxxxxx
heroku config:set TWILIO_AUTH_TOKEN=your_token
heroku config:set TWILIO_PHONE_NUMBER=+14155552671

aws ssm put-parameter --name /twilio-mms/ACCOUNT_SID --value "ACxxxxx" --type SecureString

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application files
COPY . .

# Expose port
EXPOSE 3000

# Start application
CMD ["node", "index.js"]

node_modules
npm-debug.log
.env
.git
.gitignore
*.md

# Build image
docker build -t twilio-mms-sender .

# Run container (pass env vars)
docker run -p 3000:3000 \
  -e TWILIO_ACCOUNT_SID=your_sid \
  -e TWILIO_AUTH_TOKEN=your_token \
  -e TWILIO_PHONE_NUMBER=your_number \
  twilio-mms-sender

name: Deploy to Production

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'

    - name: Install dependencies
      run: npm ci

    - name: Run tests
      run: npm test

    - name: Run linter
      run: npm run lint

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
    - uses: actions/checkout@v3

    - name: Deploy to Render
      env:
        RENDER_DEPLOY_HOOK: ${{ secrets.RENDER_DEPLOY_HOOK }}
      run: |
        curl -X POST $RENDER_DEPLOY_HOOK

npm install --save-dev jest supertest

// __tests__/send-mms.test.js
const request = require('supertest');
const app = require('../index'); // Export your app from index.js

describe('POST /send-mms', () => {
    it('returns 400 if missing required fields', async () => {
        const res = await request(app)
            .post('/send-mms')
            .send({ to: '+14155552671' }); // Missing imageUrl

        expect(res.statusCode).toBe(400);
        expect(res.body.success).toBe(false);
    });

    it('returns 400 if phone number format is invalid', async () => {
        const res = await request(app)
            .post('/send-mms')
            .send({
                to: '415-555-2671', // Invalid format
                imageUrl: 'https://example.com/image.jpg'
            });

        expect(res.statusCode).toBe(400);
        expect(res.body.error).toContain('E.164 format');
    });
});

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest --coverage",
    "lint": "eslint ."
  }
}

web: node index.js