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

// 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;

// 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();

// 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
    }
};

// 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. Please set 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
};

// 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() });
    }

    // 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(`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('MMS request successfully processed by Sinch service.', { sinchResponse });
        res.status(202).json({
            message: 'MMS request accepted for processing by Sinch.',
            details: sinchResponse // Include Sinch's response (e.g., batch ID)
        });

    } catch (error) {
        // 5. Handle errors thrown by the Sinch service
        logger.error(`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.',
             error: error.message // Provide the specific error message from the service
        });
    }
};

// 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
);

export default router;