Send MMS with Sinch in Node.js Express: Complete Implementation Guide

graph LR
    Client[Client Application / cURL] -- HTTP POST Request --> ExpressApp[Node.js/Express API]
    ExpressApp -- Validate Request --> ExpressApp
    ExpressApp -- Call Sinch Service --> SinchService[Sinch MMS Service Logic]
    SinchService -- Build JSON Payload --> SinchService
    SinchService -- POST Request (Axios w/ Retry) --> SinchAPI[Sinch XMS API (/batches)]
    SinchAPI -- Send MMS --> MobileNetwork[Mobile Network]
    MobileNetwork -- Deliver MMS --> UserDevice[User's Mobile Device]
    SinchAPI -- API Response (Success/Failure) --> SinchService
    SinchService -- Process Response --> ExpressApp
    ExpressApp -- HTTP Response (Success/Error) --> Client

// Validate required environment variables at startup
export function validateEnv() {
    const required = [
        'SINCH_SERVICE_PLAN_ID'_
        'SINCH_API_TOKEN'_
        'SINCH_MMS_NUMBER'_
        'SINCH_API_BASE_URL'_
        'INTERNAL_API_KEY'
    ];

    const missing = required.filter(key => !process.env[key]);

    if (missing.length > 0) {
        throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
    }

    // Validate E.164 format
    if (!process.env.SINCH_MMS_NUMBER.match(/^\+[1-9]\d{1,14}$/)) {
        throw new Error('SINCH_MMS_NUMBER must be in E.164 format (e.g., +12223334444)');
    }

    // Warn about default API key
    if (process.env.INTERNAL_API_KEY === 'REPLACE_WITH_A_SECURE_RANDOM_KEY') {
        console.warn('WARNING: Using default INTERNAL_API_KEY. Generate a secure key for production!');
    }
}

# .env.example - Copy to .env and replace with your actual values

# Server Configuration
PORT=3000
NODE_ENV=development

# Sinch API Credentials (Get from https://dashboard.sinch.com/sms/api/rest)
SINCH_SERVICE_PLAN_ID=YOUR_SERVICE_PLAN_ID_HERE
SINCH_API_TOKEN=YOUR_API_TOKEN_HERE
SINCH_MMS_NUMBER=+1YOURSINCHNUMBER

# Regional Endpoints: us.sms.api.sinch.com (US) or eu.sms.api.sinch.com (EU)
SINCH_API_BASE_URL=https://us.sms.api.sinch.com

# Generate secure key: openssl rand -base64 32
INTERNAL_API_KEY=REPLACE_WITH_A_SECURE_RANDOM_KEY

# Logging
LOG_LEVEL=debug

// src/config/logger.js
import winston from 'winston';
import dotenv from 'dotenv';

dotenv.config();

const { combine, timestamp, json, errors, colorize, printf } = winston.format;

// Custom format for console logging with colors
const consoleFormat = combine(
    colorize(),
    timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
    printf(({ timestamp, level, message, stack }) => {
        return `${timestamp} ${level}: ${stack || message}`;
    })
);

// Format for file logging (JSON)
const fileFormat = combine(
    timestamp(),
    errors({ stack: true }), // Log stack traces
    json()
);

const logger = winston.createLogger({
    level: process.env.LOG_LEVEL || 'info', // Default to 'info'
    format: fileFormat, // Default format (used by file transports)
    transports: [
        // Console transport – only in non-production or if explicitly enabled
        ...(process.env.NODE_ENV !== 'production' ? [
            new winston.transports.Console({
                format: consoleFormat, // Use colorful format for console
                handleExceptions: true,
            })
        ] : []),

        // File transports (optional, adjust paths and levels)
        // new winston.transports.File({ filename: 'logs/error.log', level: 'error' }),
        // new winston.transports.File({ filename: 'logs/combined.log' }),
    ],
    exitOnError: false, // Do not exit on handled exceptions
});

// If we're in production and didn't add a console transport above,
// add a basic JSON console transport for platforms that aggregate stdout/stderr.
if (process.env.NODE_ENV === 'production' && logger.transports.length === 0) {
    logger.add(new winston.transports.Console({
        format: fileFormat, // Use JSON format for production console logs
        handleExceptions: true,
    }));
     logger.info('Production environment detected, configuring JSON console logging.');
} else if (process.env.NODE_ENV !== 'production') {
     logger.info('Development environment detected, configuring colorful console logging.');
}

export default logger;

// Add to logger.js transports array
import 'winston-daily-rotate-file';

new winston.transports.DailyRotateFile({
    filename: 'logs/application-%DATE%.log',
    datePattern: 'YYYY-MM-DD',
    maxSize: '20m',
    maxFiles: '14d', // Keep logs for 14 days
    format: fileFormat
})

// Add Sentry transport
import '@sentry/node';
import winston from 'winston';

if (process.env.SENTRY_DSN) {
    logger.add(new winston.transports.Sentry({
        dsn: process.env.SENTRY_DSN,
        level: 'error'
    }));
}

// src/services/sinchService.js
import axios from 'axios';
import axiosRetry from 'axios-retry';
import dotenv from 'dotenv';
import logger from '../config/logger.js';

dotenv.config(); // Load environment variables

const SINCH_API_BASE_URL = process.env.SINCH_API_BASE_URL;
const SINCH_SERVICE_PLAN_ID = process.env.SINCH_SERVICE_PLAN_ID;
const SINCH_API_TOKEN = process.env.SINCH_API_TOKEN;
const SINCH_MMS_NUMBER = process.env.SINCH_MMS_NUMBER;

if (!SINCH_API_BASE_URL || !SINCH_SERVICE_PLAN_ID || !SINCH_API_TOKEN || !SINCH_MMS_NUMBER) {
    logger.error("FATAL ERROR: Missing required Sinch environment variables. Check .env file.");
    process.exit(1); // Exit if critical configuration is missing
}

// Construct the full API endpoint URL using the Sinch XMS (Unified Messaging) API
// Format: {region}.sms.api.sinch.com/xms/v1/{service_plan_id}/batches
const SINCH_XMS_ENDPOINT = `${SINCH_API_BASE_URL}/xms/v1/${SINCH_SERVICE_PLAN_ID}/batches`;

// Create an Axios instance for Sinch requests
const sinchAxios = axios.create({
    timeout: 30000, // 30 second timeout for API requests
});

// Configure axios-retry for the instance
axiosRetry(sinchAxios, {
    retries: 3, // Number of retry attempts
    retryDelay: (retryCount, error) => {
        logger.warn(`Retry attempt ${retryCount} for request to ${error.config.url} due to ${error.message}`);
        return retryCount * 1000; // Exponential backoff (1s, 2s, 3s)
    },
    retryCondition: (error) => {
        // Retry on network errors or 5xx server errors from Sinch
        const shouldRetry = axiosRetry.isNetworkOrIdempotentRequestError(error) ||
                           (error.response && error.response.status >= 500);
        if (shouldRetry) {
            logger.info(`Condition met for retry: ${error.message}`);
        }
        return shouldRetry;
    },
    shouldResetTimeout: true, // Reset timeout on retries
});

/**
 * Sends an MMS message using the Sinch XMS JSON API (/batches endpoint).
 * Assumes validation is handled by the controller/route layer.
 *
 * @param {string} recipientPhoneNumber - The recipient's phone number in E.164 format.
 * @param {string} mediaUrl - The publicly accessible URL of the media file (must return Content-Type and Content-Length headers).
 * @param {string} mediaType - The type of media (e.g., "image", "video"). Supported: image, audio, video, pdf, contact, calendar.
 * @param {string} [messageText=""] - Optional text message. Max 5000 chars.
 * @param {string} [subject=""] - Optional MMS subject. Max 80 chars (40 recommended).
 * @param {string} [fallbackText=""] - Optional text for SMS fallback. Max 160 chars (~110 recommended).
 * @param {boolean} [strictValidation=false] - Enable Sinch MMS channel best practices validation.
 * @returns {Promise<object&gt;} - The response data from the Sinch API (typically includes batch ID).
 * @throws {Error} - Throws an error if the API request ultimately fails after retries.
 */
export const sendMms = async (
    recipientPhoneNumber,
    mediaUrl,
    mediaType,
    messageText = '',
    subject = '',
    fallbackText = '',
    strictValidation = false
) =&gt; {
    // Construct the Sinch XMS API payload for sending MMS via the /batches endpoint
    // Type field must always be mt_media for MMS messages
    const batchPayload = {
        to: [recipientPhoneNumber], // Array of recipients
        from: SINCH_MMS_NUMBER,
        body: {
            type: "mt_media", // Indicates a mobile-terminated media message (MMS)
            url: mediaUrl, // Must be publicly accessible with Content-Type and Content-Length headers
            message: messageText || undefined, // Optional text associated with the media
            parameters: {
                // Only include parameters if they have a non-empty value
                ...(subject && { "mms_subject": { default: subject } }),
                ...(fallbackText && { "mms_fallback_text": { default: fallbackText } }),
                // Add other parameters as needed, check Sinch XMS API docs
            }
        },
        // Optional: Enable strict validation against Sinch MMS channel best practices
        ...(strictValidation && { strict_validation: true }),
        // Optional: Configure delivery report callback for status updates
        // delivery_report: "FULL", // Or "SUMMARY"
        // callback_url: "YOUR_WEBHOOK_URL_HERE"
    };

    // Remove empty parameters object if no optional params were provided
    if (Object.keys(batchPayload.body.parameters).length === 0) {
        delete batchPayload.body.parameters;
    }
     // Remove empty message field if not provided
    if (!batchPayload.body.message) {
        delete batchPayload.body.message;
    }

    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${SINCH_API_TOKEN}` // Use Bearer token authentication
    };

    logger.info(`Attempting to send MMS via Sinch XMS to ${recipientPhoneNumber} from ${SINCH_MMS_NUMBER}`);
    logger.debug(`Using Endpoint: ${SINCH_XMS_ENDPOINT}`);
    logger.debug("Request Payload:", { payload: batchPayload }); // Log payload structure

    try {
        // Use the Axios instance with retry configured
        const response = await sinchAxios.post(SINCH_XMS_ENDPOINT, batchPayload, { headers });

        logger.info('Sinch API Response Received:', { status: response.status, data: response.data });

        // Check for potential errors within a successful (2xx) HTTP response structure
        const batch = response.data?.batches?.[0];
        if (batch && (batch.error_code || batch.status === 'FAILED')) {
             logger.error('Sinch API reported an error or failure status within the batch response:', { batchData: batch });
             const errorMessage = batch.status_details || `Sinch API Error Code: ${batch.error_code || 'N/A'}, Status: ${batch.status}`;
             throw new Error(errorMessage);
        }
        // Also check for top-level errors if the structure varies
        if (response.data?.error) {
             logger.error('Sinch API top-level error:', { errorData: response.data.error });
             throw new Error(`Sinch API Error: ${response.data.error.message || JSON.stringify(response.data.error)}`);
        }

        // Assuming success if status is 2xx and no specific error structure is found.
        return response.data;

    } catch (error) {
        logger.error('Error sending MMS via Sinch service:', {
            message: error.message,
            status: error.response?.status,
            responseData: error.response?.data,
            requestConfig: error.config
        });

        // Construct a more informative error message
        let errorMessage = 'Failed to send MMS via Sinch.';
        if (error.response) {
            const errorDetails = error.response.data?.error?.message
                              || error.response.data?.batches?.[0]?.status_details
                              || JSON.stringify(error.response.data);
            errorMessage = `Sinch API request failed with status ${error.response.status}: ${errorDetails}`;
        } else if (error.request) {
            errorMessage = 'Sinch API request failed: No response received from server after retries.';
        } else {
            errorMessage = `Failed to send MMS: ${error.message}`;
        }
        throw new Error(errorMessage); // Re-throw the processed error
    }
};

/**
 * Sends bulk MMS messages to multiple recipients.
 *
 * @param {Array<string&gt;} recipients - Array of phone numbers in E.164 format
 * @param {string} mediaUrl - The publicly accessible URL of the media file
 * @param {string} mediaType - The type of media
 * @param {string} [messageText=""] - Optional text message
 * @param {string} [subject=""] - Optional MMS subject
 * @param {string} [fallbackText=""] - Optional SMS fallback text
 * @returns {Promise<object&gt;} - Batch response from Sinch API
 */
export const sendBulkMms = async (
    recipients,
    mediaUrl,
    mediaType,
    messageText = '',
    subject = '',
    fallbackText = ''
) =&gt; {
    const batchPayload = {
        to: recipients, // Send to multiple recipients in one batch
        from: SINCH_MMS_NUMBER,
        body: {
            type: "mt_media",
            url: mediaUrl,
            message: messageText || undefined,
            parameters: {
                ...(subject && { "mms_subject": { default: subject } }),
                ...(fallbackText && { "mms_fallback_text": { default: fallbackText } }),
            }
        }
    };

    if (Object.keys(batchPayload.body.parameters).length === 0) {
        delete batchPayload.body.parameters;
    }
    if (!batchPayload.body.message) {
        delete batchPayload.body.message;
    }

    const headers = {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${SINCH_API_TOKEN}`
    };

    logger.info(`Attempting to send bulk MMS to ${recipients.length} recipients`);

    try {
        const response = await sinchAxios.post(SINCH_XMS_ENDPOINT, batchPayload, { headers });
        logger.info('Bulk MMS request successful:', { batchId: response.data.id, recipientCount: recipients.length });
        return response.data;
    } catch (error) {
        logger.error('Error sending bulk MMS:', { message: error.message });
        throw new Error(`Failed to send bulk MMS: ${error.message}`);
    }
};

// Add to sinchService.js
const handleRateLimit = (error) => {
    if (error.response?.status === 429) {
        const retryAfter = error.response.headers['retry-after'] || 60;
        logger.warn(`Rate limit hit. Retry after ${retryAfter} seconds`);
        return new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    }
    throw error;
};

// src/middleware/authMiddleware.js
import dotenv from 'dotenv';
import logger from '../config/logger.js';

dotenv.config();

const INTERNAL_API_KEY = process.env.INTERNAL_API_KEY;

if (!INTERNAL_API_KEY || INTERNAL_API_KEY === 'REPLACE_WITH_A_SECURE_RANDOM_KEY') {
    logger.warn('SECURITY WARNING: INTERNAL_API_KEY is not set or is using the default placeholder. The API endpoint is effectively unprotected. Generate a strong key in .env.');
}

/**
 * Simple API Key Authentication Middleware.
 * Checks for "X-API-Key" header.
 */
export const apiKeyAuth = (req, res, next) => {
    // Allow requests if no key is configured (useful ONLY for local dev, insecure)
    if (!INTERNAL_API_KEY || INTERNAL_API_KEY === 'REPLACE_WITH_A_SECURE_RANDOM_KEY') {
        logger.warn('Proceeding without API key check because INTERNAL_API_KEY is not properly configured.');
        return next();
    }

    const providedKey = req.headers['x-api-key'];

    if (!providedKey) {
        logger.warn('Unauthorized access attempt: Missing X-API-Key header.');
        return res.status(401).json({ message: 'Unauthorized: Missing API Key' });
    }

    if (providedKey !== INTERNAL_API_KEY) {
         logger.warn(`Forbidden access attempt: Invalid API Key provided. Key: ${providedKey.substring(0, 5)}…`);
         return res.status(403).json({ message: 'Forbidden: Invalid API Key' });
    }

    logger.debug('API Key authentication successful.');
    next(); // Key is valid, proceed
};

// JWT-based authentication example
import jwt from 'jsonwebtoken';

export const jwtAuth = (req, res, next) => {
    const token = req.headers.authorization?.split(' ')[1];

    if (!token) {
        return res.status(401).json({ message: 'Missing authentication token' });
    }

    try {
        const decoded = jwt.verify(token, process.env.JWT_SECRET);
        req.user = decoded;
        next();
    } catch (error) {
        return res.status(403).json({ message: 'Invalid or expired token' });
    }
};

// Add to authMiddleware.js
import rateLimit from 'express-rate-limit';
import RedisStore from 'rate-limit-redis';

export const apiKeyRateLimit = rateLimit({
    store: new RedisStore({
        client: redisClient,
        prefix: 'rl:apikey:'
    }),
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // 100 requests per API key per window
    keyGenerator: (req) => req.headers['x-api-key'] || req.ip,
    message: 'Too many requests from this API key. Try again later.'
});

// src/controllers/mmsController.js
import { validationResult } from 'express-validator';
import { sendMms } from '../services/sinchService.js';
import logger from '../config/logger.js';

/**
 * Handles the request to send an MMS message.
 * Validates input, calls the Sinch service, and sends the response.
 */
export const handleSendMms = async (req, res) => {
    // 1. Validate Request Input using express-validator results
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
        logger.warn('Validation failed for /send MMS request:', { errors: errors.array() });
        return res.status(400).json({ errors: errors.array() });
    }

    // Generate correlation ID for request tracking
    const correlationId = `mms-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
    req.correlationId = correlationId;

    // 2. Extract validated data from request body
    const { to, mediaUrl, mediaType, messageText, subject, fallbackText } = req.body;

    try {
        // 3. Call the Sinch service function
        logger.info(`[${correlationId}] Controller received valid request to send MMS to: ${to}`);
        const sinchResponse = await sendMms(
            to,
            mediaUrl,
            mediaType,
            messageText,
            subject,
            fallbackText
        );

        // 4. Send successful response back to client (202 Accepted)
        logger.info(`[${correlationId}] MMS request successfully processed by Sinch service.`, { sinchResponse });
        res.status(202).json({
            message: 'MMS request accepted for processing by Sinch.',
            correlationId,
            details: sinchResponse // Include Sinch's response (e.g., batch ID)
        });

    } catch (error) {
        // 5. Handle errors thrown by the Sinch service
        logger.error(`[${correlationId}] Error in handleSendMms controller after calling service: ${error.message}`, { stack: error.stack });

        // Default to 500 for server/service errors.
        const statusCode = 500;

        res.status(statusCode).json({
             message: 'Failed to process MMS request.',
             correlationId,
             error: error.message // Provide the specific error message from the service
        });
    }
};

// Add to mmsController.js
import Queue from 'bull';

const mmsQueue = new Queue('mms-sending', {
    redis: { host: process.env.REDIS_HOST, port: process.env.REDIS_PORT }
});

export const handleSendMmsQueued = async (req, res) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
        return res.status(400).json({ errors: errors.array() });
    }

    const job = await mmsQueue.add({
        to: req.body.to,
        mediaUrl: req.body.mediaUrl,
        mediaType: req.body.mediaType,
        messageText: req.body.messageText,
        subject: req.body.subject,
        fallbackText: req.body.fallbackText
    }, {
        attempts: 3,
        backoff: { type: 'exponential', delay: 2000 }
    });

    res.status(202).json({
        message: 'MMS queued for processing',
        jobId: job.id
    });
};

// Process jobs
mmsQueue.process(async (job) => {
    const { to, mediaUrl, mediaType, messageText, subject, fallbackText } = job.data;
    return await sendMms(to, mediaUrl, mediaType, messageText, subject, fallbackText);
});

// src/routes/mmsRoutes.js
import express from 'express';
import { body, validationResult } from 'express-validator';
import { handleSendMms } from '../controllers/mmsController.js';
import { apiKeyAuth } from '../middleware/authMiddleware.js';
import logger from '../config/logger.js';

const router = express.Router();

// Define supported media types (align with Sinch capabilities)
// Supported: image (GIF/JPG/PNG), audio (MP3/WAV), video (3GP/MP4/MPEG/MPG/AVI/WMV), text, pdf, contact, calendar
const SUPPORTED_MEDIA_TYPES = ['image', 'audio', 'video', 'pdf', 'contact', 'calendar', 'text'];

// Input validation rules using express-validator
const sendMmsValidationRules = [
    body('to')
        .trim()
        .notEmpty().withMessage('Recipient phone number (to) is required.')
        .isString()
        .matches(/^\+[1-9]\d{1,14}$/).withMessage('Recipient phone number must be in E.164 format (e.g., +12223334444).'),
    body('mediaUrl')
        .trim()
        .notEmpty().withMessage('Media URL (mediaUrl) is required.')
        .isURL({ protocols: ['http', 'https'], require_protocol: true })
        .withMessage('Media URL must be a valid HTTP or HTTPS URL. Ensure the URL returns Content-Type and Content-Length headers.'),
    body('mediaType')
        .trim()
        .notEmpty().withMessage('Media type (mediaType) is required.')
        .toLowerCase()
        .isIn(SUPPORTED_MEDIA_TYPES)
        .withMessage(`Invalid media type. Must be one of: ${SUPPORTED_MEDIA_TYPES.join(', ')}. Supported formats: GIF/JPG/PNG (image), MP3/WAV (audio), 3GP/MP4/MPEG/MPG/AVI/WMV (video).`),
    body('messageText')
        .optional({ checkFalsy: true }) // Allow empty string or null/undefined
        .isString()
        .isLength({ max: 5000 }).withMessage('Message text cannot exceed 5000 characters.'),
    body('subject')
        .optional({ checkFalsy: true })
        .isString()
        .isLength({ max: 80 }).withMessage('Subject cannot exceed 80 characters (40 recommended).'),
    body('fallbackText')
        .optional({ checkFalsy: true })
        .isString()
        .isLength({ max: 160 }).withMessage('Fallback text cannot exceed 160 characters (approx. SMS limit).'),
    body('strictValidation')
        .optional()
        .isBoolean().withMessage('strictValidation must be a boolean value.')
];

// Middleware to log validation results (optional, for debugging)
const logValidationErrors = (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
        logger.debug('Express-validator validation errors:', { errors: errors.array() });
    }
    next();
};

// Define the POST route for sending MMS
// Chain: Authentication -> Validation -> Controller
router.post(
    '/send',
    apiKeyAuth,             // 1. Check API Key
    sendMmsValidationRules, // 2. Validate request body
    // logValidationErrors, // Uncomment for debugging validation errors
    handleSendMms           // 3. Process the request if auth/validation pass
);

// GET endpoint to check batch status by batch ID
router.get('/status/:batchId', apiKeyAuth, async (req, res) => {
    const { batchId } = req.params;

    try {
        const statusEndpoint = `${process.env.SINCH_API_BASE_URL}/xms/v1/${process.env.SINCH_SERVICE_PLAN_ID}/batches/${batchId}`;
        const response = await axios.get(statusEndpoint, {
            headers: { 'Authorization': `Bearer ${process.env.SINCH_API_TOKEN}` }
        });

        res.json({
            batchId,
            status: response.data.status,
            created: response.data.created_at,
            modified: response.data.modified_at,
            details: response.data
        });
    } catch (error) {
        logger.error(`Failed to fetch batch status for ${batchId}:`, error.message);
        res.status(500).json({ message: 'Failed to fetch batch status', error: error.message });
    }
});

export default router;

// Add to routes or create src/utils/mediaValidator.js
import axios from 'axios';

export const validateMediaUrl = async (url) => {
    try {
        const response = await axios.head(url, { timeout: 5000 });

        const contentType = response.headers['content-type'];
        const contentLength = response.headers['content-length'];

        if (!contentType) {
            throw new Error('Media URL does not return Content-Type header');
        }

        if (!contentLength) {
            throw new Error('Media URL does not return Content-Length header');
        }

        const sizeMB = parseInt(contentLength) / (1024 * 1024);
        if (sizeMB > 1) {
            throw new Error(`Media file too large: ${sizeMB.toFixed(2)} MB (max 1 MB)`);
        }

        return { valid: true, contentType, sizeMB };
    } catch (error) {
        return { valid: false, error: error.message };
    }
};

// Use in validation middleware
body('mediaUrl').custom(async (value) => {
    const validation = await validateMediaUrl(value);
    if (!validation.valid) {
        throw new Error(validation.error);
    }
    return true;
});

# Verify Content-Type and Content-Length headers
curl -I https://your-cdn.com/image.jpg

# Expected response:
# HTTP/1.1 200 OK
# Content-Type: image/jpeg
# Content-Length: 524288
# Access-Control-Allow-Origin: *

// Test fallback behavior
const testFallback = async () => {
    // Test 1: Valid MMS
    await sendMms('+12223334444', 'https://cdn.example.com/image.jpg', 'image',
        'Check out this image!', '', 'Visit example.com to view');

    // Test 2: Force fallback with invalid URL
    await sendMms('+12223334444', 'https://invalid-url-404.example.com/image.jpg', 'image',
        'Check out this image!', '', 'Visit example.com to view');
};

// Add to server.js or create src/routes/health.js
router.get('/health', async (req, res) => {
    const health = {
        uptime: process.uptime(),
        timestamp: Date.now(),
        status: 'OK',
        checks: {}
    };

    // Check Sinch API connectivity
    try {
        await axios.head(`${process.env.SINCH_API_BASE_URL}`, { timeout: 5000 });
        health.checks.sinch = 'OK';
    } catch (error) {
        health.checks.sinch = 'DEGRADED';
        health.status = 'DEGRADED';
    }

    // Check environment variables
    const requiredEnv = ['SINCH_SERVICE_PLAN_ID', 'SINCH_API_TOKEN', 'SINCH_MMS_NUMBER'];
    health.checks.config = requiredEnv.every(key => process.env[key]) ? 'OK' : 'ERROR';

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

// Add to mmsController.js
import Queue from 'bull';

const deadLetterQueue = new Queue('mms-dlq', {
    redis: { host: process.env.REDIS_HOST, port: process.env.REDIS_PORT }
});

// In error handler
catch (error) {
    logger.error(`[${correlationId}] MMS send failed after retries`);

    // Send to dead letter queue
    await deadLetterQueue.add({
        originalRequest: { to, mediaUrl, mediaType, messageText },
        error: error.message,
        timestamp: new Date(),
        correlationId
    });

    res.status(500).json({ message: 'Failed to process MMS request', correlationId });
}

// Process DLQ for manual review or retry
deadLetterQueue.process(async (job) => {
    logger.warn('Processing dead letter queue item', job.data);
    // Manual intervention, notifications, or retry logic
});