How to Send MMS with Sinch API and Node.js: Complete 2025 Developer Guide

+-------------+       +---------------------+       +-----------------+
| Your Client | ----> | Node.js/Express App | ----> | Sinch MMS API |
| (e.g., Web, |       | (API Endpoint)      |       |                 |
| Mobile App) |       +---------------------+       +-----------------+
+-------------+               |
                              | (Optional)
                              v
                        +-------------+
                        | Database    |
                        | (Logging)   |
                        +-------------+

mkdir sinch-mms-sender
cd sinch-mms-sender

npm init -y

npm install express axios dotenv
npm install --save-dev nodemon

# .env

# --- Sinch Credentials ---
# Get these from your Sinch Customer Dashboard (e.g., under SMS -> APIs)
# Replace placeholders with your actual values.

# Your Service Plan ID (or Campaign ID - verify term)
SINCH_SERVICE_PLAN_ID=YOUR_SERVICE_PLAN_ID

# Your API Token for the Service Plan ID
SINCH_API_TOKEN=YOUR_API_TOKEN

# Your provisioned Sinch Number (use E.164 format, e.g., +1xxxxxxxxxx)
SINCH_NUMBER=YOUR_SINCH_PHONE_NUMBER

# --- Sinch API Configuration ---
# CRITICAL: Verify the correct API base URL and structure in the official Sinch documentation
# for your specific region (us, eu, au, etc.) and API product version.
# The structure might require the service plan ID in the path as shown, or it might be different.
# Example structure (VERIFY THIS):
SINCH_API_BASE_URL=https://us.mms.api.sinch.com/v1/services/YOUR_SERVICE_PLAN_ID

# --- Server Configuration ---
# Port your Express server will listen on
PORT=3000

# Optional: Logging level (e.g., 'info', 'debug', 'warn', 'error')
# LOG_LEVEL=info

sinch-mms-sender/
├── node_modules/
├── public/             # (Optional: for static files if needed)
├── src/
│   ├── controllers/    # Request/response handling
│   │   └── mmsController.js
│   ├── services/       # Business logic (Sinch interaction)
│   │   └── sinchService.js
│   ├── routes/         # API route definitions
│   │   └── mmsRoutes.js
│   ├── app.js          # Express app configuration
│   └── server.js       # Server entry point
├── .env                # Environment variables (DO NOT COMMIT)
├── .gitignore          # Git ignore file
├── package.json
└── package-lock.json

# .gitignore
node_modules/
.env
npm-debug.log
*.log

{
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

// src/services/sinchService.js
const axios = require('axios');

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

const SINCH_SERVICE_PLAN_ID = process.env.SINCH_SERVICE_PLAN_ID;
const SINCH_API_TOKEN = process.env.SINCH_API_TOKEN;
const SINCH_API_BASE_URL = process.env.SINCH_API_BASE_URL; // Assumes base URL includes service ID path per .env example

if (!SINCH_SERVICE_PLAN_ID || !SINCH_API_TOKEN || !SINCH_API_BASE_URL) {
    console.error("Error: Missing Sinch credentials or API base URL in .env file. Please check SINCH_SERVICE_PLAN_ID, SINCH_API_TOKEN, and SINCH_API_BASE_URL.");
    process.exit(1); // Stop the application if critical config is missing
}

// Construct the specific endpoint for the sendmms action
// **VERIFY THIS ENDPOINT STRUCTURE** against the official Sinch MMS JSON API documentation for your account/region.
// This assumes the base URL already contains '/v1/services/{service_plan_id}'
const SEND_MMS_ENDPOINT = `${SINCH_API_BASE_URL}/actions/sendmms`;

/**
 * Sends an MMS message using the Sinch MMS JSON API.
 *
 * @param {string} to The recipient's phone number in E.164 international format (e.g., +1...).
 * @param {string} from The Sinch phone number sending the message (E.164 format).
 * @param {string} subject The subject line for the MMS (max 80 chars, 40 recommended).
 * @param {Array<object>} slides An array of slide objects. Structure MUST match Sinch API docs.
 *                                Each slide can contain text and/or one media type (image, audio, video, etc.).
 * @param {string} [fallbackText] Optional text for the fallback SMS if MMS fails or is disabled. Required if fallback isn't explicitly disabled.
 * @param {object} [options] Optional parameters like clientReference, disableFallbackSms, etc. (Refer to Sinch Docs).
 * @returns {Promise<object>} The success response data from the Sinch API (contains tracking-id).
 * @throws {Error} If the API request fails or returns an error status.
 */
const sendMms = async (to, from, subject, slides, fallbackText, options = {}) => {
    console.log(`Attempting to send MMS to ${to} from ${from}`);

    // Basic validation
    if (!to || !from || !subject || !Array.isArray(slides) || slides.length === 0) {
        throw new Error('Missing required parameters: to, from, subject, or non-empty slides array.');
    }
    if (!to.startsWith('+') || !from.startsWith('+')) {
        console.warn(`Warning: Phone numbers should be in E.164 format (start with +). To: ${to}, From: ${from}`);
        // Consider throwing an error here in production for strict validation
    }
    if (slides.length > 8) {
        console.warn('Warning: Maximum of 8 slides recommended per Sinch guidelines.');
    }

     // Ensure fallbackText is provided if fallback SMS is enabled (default behavior)
     const disableFallbackSms = options.disableFallbackSms === true;

     if (!disableFallbackSms && !fallbackText) {
         // Fallback is enabled by default, so text is required unless explicitly disabled.
         throw new Error('fallbackText is required when disableFallbackSms is false (or not provided).');
     }

    // **VERIFY PAYLOAD STRUCTURE** against official Sinch MMS JSON API documentation.
    const payload = {
        action: 'sendmms',
        'service-id': SINCH_SERVICE_PLAN_ID, // May or may not be required depending on API structure/endpoint used
        to: to,
        from: from,
        'message-subject': subject,
        slide: slides, // Array of slide objects - structure is critical
        // --- Optional Parameters (Verify names and values in Sinch Docs) ---
        'fallback-sms-text': disableFallbackSms ? undefined : fallbackText, // Only include if fallback is enabled
        'disable-fallback-sms': options.disableFallbackSms || false, // Default: false (fallback enabled)
        'disable-fallback-sms-link': options.disableFallbackSmsLink || false, // Default: false
        // 'fallback-sms-link-expiration': options.fallbackLinkExpiration, // Example: ISO8601 Date String
        // 'mms-expiry-timestamp': options.mmsExpiryTimestamp, // Example: ISO8601 Date String
        'client-reference': options.clientReference, // Your internal reference ID (max 64 chars recommended)
        'cache-content': options.cacheContent === undefined ? true : options.cacheContent, // Default: true (Sinch may cache media)
    };

    // Remove undefined optional keys to keep payload clean
    Object.keys(payload).forEach(key => payload[key] === undefined && delete payload[key]);

    console.log('Constructed Sinch Payload:', JSON.stringify(payload, null, 2)); // Log payload for debugging

    try {
        // **VERIFY AUTHENTICATION METHOD** (Bearer Token is common, but check Sinch Docs)
        const response = await axios.post(SEND_MMS_ENDPOINT, payload, {
            headers: {
                'Content-Type': 'application/json; charset=utf-8',
                'Authorization': `Bearer ${SINCH_API_TOKEN}` // Standard Bearer token auth
            },
            timeout: 15000 // Set a reasonable timeout (e.g., 15 seconds) for the API call
        });

        console.log('Sinch API Response Status:', response.status);
        console.log('Sinch API Response Data:', JSON.stringify(response.data, null, 2));

        // Sinch often returns 200 OK even for queued messages, but check response body for success indicator if available
        // The exact success condition might vary based on the API version. This checks for a common pattern.
        if (response.data && response.data.status === 'success' && response.data['tracking-id']) {
             console.log(`MMS successfully queued with Sinch. Tracking ID: ${response.data['tracking-id']}`);
            return response.data; // Contains tracking-id etc.
        } else {
            // Handle cases where Sinch might return 200 but indicate failure/issue in the body, or success structure differs
            console.error('Sinch API response body indicates potential issue:', response.data);
            throw new Error(`Sinch API did not return expected success status or tracking-id in response body: ${JSON.stringify(response.data)}`);
        }

    } catch (error) {
        console.error('Error sending MMS via Sinch:', error.message);
        let errorMessage = 'Failed to send MMS via Sinch API.';

        if (error.response) {
            // The request was made and the server responded with a status code outside the 2xx range
            console.error('Sinch API Error Status:', error.response.status);
            console.error('Sinch API Error Headers:', error.response.headers);
            console.error('Sinch API Error Data:', JSON.stringify(error.response.data, null, 2));
            // Include details from Sinch error response if available
            const errorDetails = error.response.data ? `: ${JSON.stringify(error.response.data)}` : '';
            errorMessage = `Sinch API request failed with status ${error.response.status}${errorDetails}`;
        } else if (error.request) {
            // The request was made but no response was received
            console.error('Sinch API No Response Received. Request details:', error.request);
            errorMessage = 'No response received from Sinch API. Check network connectivity and endpoint URL.';
        } else {
            // Something happened in setting up the request that triggered an Error
            console.error('Axios Request Setup Error:', error.message);
            errorMessage = `Error setting up request to Sinch API: ${error.message}`;
        }
         // Re-throw a more informative error to be handled by the controller
        throw new Error(errorMessage);
    }
};

module.exports = {
    sendMms,
};

// src/routes/mmsRoutes.js
const express = require('express');
const mmsController = require('../controllers/mmsController');
// Optional: Import validation middleware if using express-validator (see Section 7)
// const { validateSendMms } = require('../middleware/validators'); // Example path

const router = express.Router();

// Define the route for sending MMS
// POST /api/mms/send
// Optional: Add validation middleware before the controller
// router.post('/send', validateSendMms, mmsController.handleSendMms);
router.post('/send', mmsController.handleSendMms);


module.exports = router;

// src/controllers/mmsController.js
const sinchService = require('../services/sinchService');

// Load environment variables to get the sender number
require('dotenv').config();
const SINCH_NUMBER = process.env.SINCH_NUMBER;

if (!SINCH_NUMBER) {
    console.error("FATAL: SINCH_NUMBER is not defined in .env file. Cannot determine sender number.");
    process.exit(1);
}

/**
 * Handles the incoming API request to send an MMS.
 * Expects request body adhering to the defined contract, e.g.:
 * {
 *   "to": "+1xxxxxxxxxx", // E.164 format
 *   "subject": "Your Media Update", // Max 80 chars
 *   "slides": [ // 1-8 slides, structure defined by Sinch API docs
 *     { "image": { "url": "https://your-cdn.com/image.jpg" }, "message-text": "Check out this picture!" },
 *     { "video": { "url": "https://your-cdn.com/video.mp4" }, "message-text": "And this video too." }
 *   ],
 *   "fallbackText": "View your media update here: [link inserted by Sinch if enabled]", // Required if fallback not disabled
 *   "clientReference": "internal-order-123", // Optional, max 64 chars
 *   "disableFallbackSms": false, // Optional, default false
 *   "disableFallbackSmsLink": false // Optional, default false
 * }
 */
const handleSendMms = async (req, res) => {
    // Extract data from request body
    const { to, subject, slides, fallbackText, clientReference,
            disableFallbackSms, disableFallbackSmsLink /* Add other options if needed */ } = req.body;
    const from = SINCH_NUMBER; // Use the number configured in .env as the sender

    // Basic Input Validation (Strongly recommend using a library like express-validator for production - see Section 7)
    if (!to || !subject || !Array.isArray(slides) || slides.length === 0) {
        console.warn(`Validation failed for incoming request: Missing required fields.`);
        return res.status(400).json({
            status: 'error',
            message: 'Bad Request: Missing required fields: `to`, `subject`, `slides` (must be a non-empty array).',
        });
    }
    // Add more specific validation here or use middleware (e.g., check 'to' format, subject length, slide content structure)

    // Prepare options object for the service layer
    const serviceOptions = {
        clientReference,
        disableFallbackSms,
        disableFallbackSmsLink,
        // Pass through other relevant options extracted from req.body
    };

    try {
        console.log(`Processing request to send MMS via Sinch: To=${to}, From=${from}, Subject=${subject}`);
        const result = await sinchService.sendMms(
            to,
            from,
            subject,
            slides,
            fallbackText,     // Pass fallbackText explicitly
            serviceOptions    // Pass the options bundle
        );

        // If sendMms resolves, it means the request was accepted by Sinch (or seemed to be)
        console.log(`Successfully queued MMS to ${to} via Sinch. Tracking ID: ${result['tracking-id']}`);
        // Respond with the success status and the data received from Sinch (including tracking ID)
        res.status(200).json({
            status: 'success',
            message: 'MMS request accepted by Sinch and queued for delivery.',
            data: result, // Send back the full Sinch success response
        });

    } catch (error) {
        // Log the detailed error caught from the service layer
        console.error(`Failed to process MMS request for ${to}:`, error.message); // error.message now contains detailed info

        // Determine appropriate status code based on error type if possible
        // If the error came from Sinch API (indicated by the service layer error message), use 400 or a more specific code if known.
        // Otherwise, use 500 for internal server errors.
        const statusCode = error.message.includes("Sinch API request failed") || error.message.includes("required parameters") || error.message.includes("fallbackText is required") ? 400 : 500;

        res.status(statusCode).json({
            status: 'error',
            message: 'Failed to send MMS.',
            // Provide the specific error message back (be cautious about leaking too much detail in production)
            error: error.message,
        });
    }
};

module.exports = {
    handleSendMms,
};

// src/app.js
const express = require('express');
const mmsRoutes = require('./routes/mmsRoutes');
// Optional: Import security middleware like rate limiter (see Section 7)
// const { apiLimiter } = require('./middleware/rateLimiter');
// Optional: Import request logger like pino-http (see Section 5)
// const { httpLogger } = require('./utils/logger');

// Load environment variables early, especially for PORT and NODE_ENV
require('dotenv').config();

const app = express();

// --- Core Middlewares ---

// Request Logging (Replace with a structured logger like pino in production - See Section 5)
// app.use(httpLogger); // Example using pino-http
app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] Incoming Request: ${req.method} ${req.originalUrl}`);
    next(); // Pass control to the next middleware/route handler
});

// JSON Body Parser: Crucial for reading req.body from JSON payloads
app.use(express.json({ limit: '1mb' })); // Set a reasonable payload size limit

// URL-encoded Body Parser (optional, if you expect form data)
app.use(express.urlencoded({ extended: true }));

// --- Security Middlewares (Examples - See Section 7) ---
// app.use('/api/', apiLimiter); // Apply rate limiting to API routes
// Add other security middleware here (helmet, cors if needed)

// --- API Routes ---
app.use('/api/mms', mmsRoutes); // Mount the MMS routes under /api/mms

// --- Health Check Endpoint ---
app.get('/health', (req, res) => {
    // Basic health check, can be expanded later
    res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
});

// --- Error Handling Middlewares (Must be defined LAST) ---

// Catch-all for 404 Not Found errors (requests falling through routes)
app.use((req, res, next) => {
    res.status(404).json({ status: 'error', message: `Resource not found: ${req.originalUrl}` });
});

// Global Error Handler: Catches errors passed via next(error) or thrown in async route handlers
// Needs 4 arguments to be recognized by Express as an error handler
app.use((err, req, res, next) => {
    // Log the error internally (use a proper logger in production)
    console.error("Unhandled Error:", err.stack || err);

    // Determine status code: Use error's status if set, otherwise default to 500
    const statusCode = typeof err.status === 'number' ? err.status : 500;

    // Send generic error response to the client
    res.status(statusCode).json({
        status: 'error',
        message: err.message || 'Internal Server Error',
        // Optionally include stack trace in development mode ONLY
        ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    });
});

module.exports = app;

// src/server.js
const app = require('./app');

// Ensure environment variables are loaded (dotenv.config() might be called in app.js already)
require('dotenv').config();

const PORT = process.env.PORT || 3000; // Use PORT from .env or default to 3000
const NODE_ENV = process.env.NODE_ENV || 'development';

const server = app.listen(PORT, () => { // Store server instance for graceful shutdown
    console.log(`Server running in ${NODE_ENV} mode on port ${PORT}`);
    console.log("--- Configuration Check ---");
    console.log(`Sinch Service Plan ID configured: ${process.env.SINCH_SERVICE_PLAN_ID ? 'Yes' : 'NO - Check .env!'}`);
    console.log(`Sinch API Token configured: ${process.env.SINCH_API_TOKEN ? 'Yes' : 'NO - Check .env!'}`);
    console.log(`Sinch Sender Number configured: ${process.env.SINCH_NUMBER || 'NO - Check .env!'}`);
    console.log(`Sinch API Base URL configured: ${process.env.SINCH_API_BASE_URL || 'NOT SET - Check .env!'}`);
    console.log("---------------------------");
    if (!process.env.SINCH_SERVICE_PLAN_ID || !process.env.SINCH_API_TOKEN || !process.env.SINCH_NUMBER || !process.env.SINCH_API_BASE_URL) {
        console.error("FATAL: One or more required Sinch environment variables are missing. Application might not function correctly.");
    }
});

// Optional: Graceful shutdown handling
process.on('SIGTERM', () => {
    console.log('SIGTERM signal received: closing HTTP server');
    // Add cleanup logic here (e.g., close database connections)
    server.close(() => {
        console.log('HTTP server closed');
        process.exit(0);
    });
});

// src/services/sinchService.js
const axios = require('axios');
// Use default import for axios-retry
const axiosRetry = require('axios-retry').default;

// ... other imports and config (SINCH_SERVICE_PLAN_ID, TOKEN, BASE_URL, SEND_MMS_ENDPOINT) ...

// Create an Axios instance specifically for Sinch requests
const sinchApiClient = axios.create({
    baseURL: SINCH_API_BASE_URL, // Set base URL here if consistent
    timeout: 15000, // Default timeout for requests
    headers: {
        'Content-Type': 'application/json; charset=utf-8',
        'Authorization': `Bearer ${SINCH_API_TOKEN}` // Set common headers
    }
});

// Configure axios-retry on the instance
axiosRetry(sinchApiClient, {
    retries: 3, // Number of retries
    retryDelay: (retryCount) => {
        console.log(`Retry attempt: ${retryCount}`);
        return retryCount * 1000; // Exponential backoff (1s, 2s, 3s)
    },
    retryCondition: (error) => {
        // Retry on network errors or specific server errors (5xx)
        return (
            axiosRetry.isNetworkOrIdempotentRequestError(error) ||
            (error.response && error.response.status >= 500 && error.response.status <= 599)
        );
    },
    onRetry: (retryCount, error, requestConfig) => {
        console.warn(`Retrying request to ${requestConfig.url} due to error: ${error.message}. Attempt ${retryCount}`);
    }
});

// ... inside sendMms function ...
try {
    // Use the configured axios instance instead of axios.post directly
    // Note: If SEND_MMS_ENDPOINT was constructed using SINCH_API_BASE_URL,
    // you might need to adjust the URL passed here (e.g., just the path part).
    // Assuming SEND_MMS_ENDPOINT is the full URL:
    // const response = await sinchApiClient.post(SEND_MMS_ENDPOINT, payload);

    // OR if SINCH_API_BASE_URL is set in the instance and SEND_MMS_ENDPOINT
    // contains the full URL, extract the path:
    const endpointPath = new URL(SEND_MMS_ENDPOINT).pathname; // Requires full URL in SEND_MMS_ENDPOINT
    const response = await sinchApiClient.post(endpointPath, payload);

    // ... rest of the success/error handling logic ...

} catch (error) {
    // Error handling remains largely the same, but logs might show retry attempts
    console.error('Error sending MMS via Sinch (after potential retries):', error.message);
    // ... rest of error handling ...
}

// ... rest of the file ...