Send MMS messages with Node.js, Express, and Sinch

This guide provides a step-by-step walkthrough for building a Node.js application using the Express framework to send Multimedia Messaging Service (MMS) messages via the Sinch API. We'll cover everything from project setup and core implementation to error handling, security, and deployment considerations.

By the end of this guide, you will have a functional Express API endpoint capable of accepting requests and sending MMS messages, including text and media (like images), to specified recipients using your Sinch account.

Project overview and goals

Goal: To create a simple but robust backend service that exposes an API endpoint for sending MMS messages.

Problem Solved: Provides a programmatic way to integrate MMS capabilities into applications, enabling automated notifications, user engagement campaigns, or multimedia content delivery via standard mobile messaging channels.

Technologies:

• Node.js: A JavaScript runtime environment for building server-side applications. Chosen for its large ecosystem (npm), asynchronous nature, and suitability for I/O-bound tasks like API interactions.
• Express: A minimal and flexible Node.js web application framework. Chosen for its simplicity, routing capabilities, and middleware architecture, making it ideal for building APIs.
• Sinch MMS API: A service providing programmatic access to send and manage MMS messages. Chosen as the designated third-party provider for this guide.
• Axios: A promise-based HTTP client for Node.js. Chosen for making requests to the Sinch API easily.
• dotenv: A module to load environment variables from a .env file. Chosen for securely managing API credentials outside the codebase.

System Architecture:

Here is a simplified text-based representation of the system architecture:

+-------------+       +---------------------+       +-----------------+       +-------------+
|             |------>|                     |------>|                 |------>|             |
| User/Client | HTTP  | Express API Server  | HTTP  |    Sinch API    |  MMS  |  Recipient  |
| (e.g. CURL) | POST  |   (Node.js)         | POST  | (MMS Endpoint)  |       | (Mobile)    |
|             |<------|                     |<------|                 |<------|             |
+-------------+ 200 OK+---------------------+ 200 OK+-----------------+ Status+-------------+
     w/ msg ID                               w/ tracking ID

1. A client (like curl_ Postman_ or another application) sends an HTTP POST request to the /send-mms endpoint on the Express server.
2. The Express server validates the request_ retrieves necessary credentials_ constructs the payload for the Sinch MMS API.
3. The Express server sends an HTTP POST request to the Sinch MMS API endpoint using Axios.
4. Sinch processes the request_ fetches any media from the provided URLs_ and queues the MMS for delivery to the recipient's mobile device via carrier networks.
5. Sinch returns a response (e.g._ a tracking ID) to the Express server.
6. The Express server returns a success response (or error) to the original client.

Prerequisites:

• Node.js and npm (or yarn): Installed on your development machine. (Download Node.js)
• Sinch Account: A registered account with Sinch.
• Sinch API Credentials:
  • SERVICE_PLAN_ID (Used in the API endpoint URL).
  • API_TOKEN (Used for authentication).
  • MMS_CAMPAIGN_ID (or similar_ used in the MMS payload_ potentially the same as SERVICE_PLAN_ID).
  • A provisioned Sinch phone number (Short Code_ Toll-Free_ or 10DLC) capable of sending MMS.
• Publicly Accessible Media URL: A URL hosting the media file (e.g._ image_ video) you want to send. Crucially_ this server must provide Content-Length and valid Content-Type headers for the media file.

1. Setting up the project

Let's initialize our Node.js project and install the necessary dependencies.

1. Create Project Directory: Open your terminal and create a new directory for the project_ then navigate into it.

   bash

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

2. Initialize npm Project: This creates a package.json file to manage project dependencies and metadata.

   bash

   npm init -y
   

   The -y flag accepts the default settings.

3. Install Dependencies: We need Express for the server_ Axios for HTTP requests_ and dotenv for environment variables.

   bash

   npm install express axios dotenv
   

4. Create Project Structure: Create the basic files and directories.

   bash

   touch server.js .env .gitignore
   
   • server.js: Our main application file containing the Express server logic.
   • .env: Stores sensitive credentials like API keys. Never commit this file to version control.
   • .gitignore: Specifies files and folders that Git should ignore.

5. Configure .gitignore: Add node_modules and .env to your .gitignore file to prevent them from being tracked by Git.

   # .gitignore
   
   node_modules/
   .env
   *.log
   

6. Set Up Environment Variables (.env): Open the .env file and add your Sinch credentials and server configuration. Use the standard KEY=VALUE format. Quotes are generally only needed if the value contains spaces or special characters.

   • SINCH_SERVICE_PLAN_ID: Found on your Sinch Customer Dashboard under SMS > APIs. This ID is often used in the API endpoint URL structure.
   • SINCH_API_TOKEN: Also found on the SMS > APIs page in the Sinch Dashboard. Click ""Show"" to reveal your token. This is used for Bearer authentication.
   • SINCH_MMS_CAMPAIGN_ID: This is the identifier for the specific MMS service or campaign you are using. The exact name and location in the Sinch dashboard might vary (e.g., it could be labeled as ""Campaign ID"", ""Service ID"" under MMS settings). Crucially, determine if this is the same as your SINCH_SERVICE_PLAN_ID or a separate ID specific to MMS. Check your MMS service configuration within the Sinch dashboard. If unsure, start by trying your SINCH_SERVICE_PLAN_ID here, but verify with Sinch documentation or support.
   • SINCH_NUMBER: A virtual number (Short Code, TFN, 10DLC) associated with your Sinch account/Service Plan, capable of sending MMS. Found on your Service Plan details page in the dashboard. Ensure it includes the country code (e.g., 12065551212 for US/Canada).
   • SINCH_REGION: The region your Sinch account is hosted in (e.g., us, eu). This determines the base URL for the API.
   • PORT: The port number your Express server will listen on (e.g., 3000).
   bash

   # .env - Replace with your actual credentials
   
   # Sinch API Credentials & Config
   SINCH_SERVICE_PLAN_ID=YOUR_SERVICE_PLAN_ID
   SINCH_API_TOKEN=YOUR_API_TOKEN
   SINCH_MMS_CAMPAIGN_ID=YOUR_MMS_CAMPAIGN_OR_SERVICE_ID # Verify if this is needed and different from SERVICE_PLAN_ID
   SINCH_NUMBER=YOUR_SINCH_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., 12065551212
   SINCH_REGION=us # e.g., us, eu, etc.
   
   # Server Configuration
   PORT=3000
   

   Why .env? Storing credentials directly in code is insecure and makes managing different environments (development, production) difficult. dotenv allows us to load these sensitive values from an external file, keeping them safe and configurable.

2. Implementing core functionality: Sending MMS

Now, let's write the code in server.js to create the Express server and the logic for calling the Sinch API.

Critical Consideration: Sinch API Endpoint and Payload for MMS

Identifying the correct Sinch API endpoint and payload structure for sending MMS messages is crucial and can be challenging as documentation might focus on SMS or the Conversation API.

• Common SMS Endpoint: The Sinch SMS API often uses a /batches endpoint like https://{region}.sms.api.sinch.com/xms/v1/{SERVICE_PLAN_ID}/batches.
• MMS Needs: Sending MMS requires specifying media (URL, type) and potentially a subject, which might not be standard fields on the SMS /batches endpoint.
• Possible Approaches (Verification Required):
  1. Dedicated MMS Endpoint: Sinch might provide a completely separate endpoint specifically for MMS (e.g., https://mms.api.sinch.com/... or similar). This is common for distinct services. This is the most likely scenario for a robust MMS API.
  2. Extended SMS /batches Endpoint: The /batches endpoint might be extended to handle MMS by accepting specific fields (e.g., media_body, parameters, or a structured MMS object).

This guide will proceed using the SMS /batches endpoint structure as a starting point, attempting to add MMS details via speculative fields. HOWEVER, you MUST consult the official Sinch developer documentation specific to the MMS product you are using to confirm the correct API endpoint URL and the exact payload structure required. The example payload below is illustrative and likely needs adjustment.

// server.js

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

const app = express();
app.use(express.json()); // Middleware to parse JSON request bodies

// --- Configuration ---
const PORT = process.env.PORT || 3000;
const SINCH_SERVICE_PLAN_ID = process.env.SINCH_SERVICE_PLAN_ID;
const SINCH_API_TOKEN = process.env.SINCH_API_TOKEN;
// SINCH_MMS_CAMPAIGN_ID is loaded but its usage depends on the correct API payload structure
const SINCH_MMS_CAMPAIGN_ID = process.env.SINCH_MMS_CAMPAIGN_ID;
const SINCH_NUMBER = process.env.SINCH_NUMBER; // Your Sinch MMS-enabled number
const SINCH_REGION = process.env.SINCH_REGION || 'us'; // Default to 'us' region

// Construct the base URL based on the common SMS pattern.
// **WARNING:** This base URL and endpoint path might NOT be correct for sending MMS.
// You MUST verify the correct endpoint from the official Sinch MMS API documentation.
// A dedicated MMS endpoint (e.g., mms.api.sinch.com) is more likely.
const SINCH_API_BASE_URL = `https://${SINCH_REGION}.sms.api.sinch.com/xms/v1/${SINCH_SERVICE_PLAN_ID}`;
const SINCH_MMS_ENDPOINT = `${SINCH_API_BASE_URL}/batches`; // Using the SMS batch endpoint as a *guess*

// --- Validation Middleware (Basic Example) ---
// In a real app, use a library like express-validator for robust validation (see Section 3)
const validateMmsRequest = (req, res, next) => {
  const { to, mediaUrl } = req.body;
  // Basic checks - Text might be optional if media is present
  if (!to || !mediaUrl) {
    return res.status(400).json({
      error: 'Bad Request',
      message: 'Missing required fields: ""to"" and ""mediaUrl"" are required.',
    });
  }
  // Check if mediaUrl is a plausible URL structure
  try {
    new URL(mediaUrl);
  } catch (error) {
    return res.status(400).json({
      error: 'Bad Request',
      message: 'Invalid ""mediaUrl"" format.',
    });
  }

  next(); // Proceed to the route handler if validation passes
};


// --- MMS Sending Logic ---
// Added optional clientReference for idempotency
async function sendSinchMms(recipient, messageText, mediaFileUrl, subject = 'MMS Message', clientReference = null) {
  console.log(`Attempting to send MMS to: ${recipient} with media: ${mediaFileUrl}`);

  // **WARNING: Payload Structure is Speculative**
  // This payload attempts to add MMS details (media, subject) to the SMS /batches endpoint format.
  // This structure is NOT guaranteed to work and is highly likely to be incorrect.
  // Consult the official Sinch MMS API documentation for the correct payload format.
  // You might need a completely different structure, potentially involving 'service-id', 'action: ""sendmms""', 'slide', etc.,
  // especially if using a dedicated MMS endpoint.
  const payload = {
    from: SINCH_NUMBER,
    to: [recipient], // Batch endpoint expects an array
    body: messageText || '', // Text body
    // --- Speculative MMS Fields ---
    // Attempting to add media URL and subject. These field names are guesses.
    media_body: mediaFileUrl, // Field name needs verification with Sinch Docs
    parameters: { // Using parameters is another speculative approach
        mms_subject: subject // Field name needs verification
        // Potentially add SINCH_MMS_CAMPAIGN_ID here if required by the payload, e.g., 'campaign_id': SINCH_MMS_CAMPAIGN_ID
    },
    // --- Idempotency ---
    // Include client_reference if provided (check Sinch docs for exact field name)
    ...(clientReference && { client_reference: clientReference })
  };

  // If using a dedicated MMS endpoint, the payload might look completely different, e.g.:
  // {
  //   action: ""sendmms"",
  //   ""service-id"": SINCH_MMS_CAMPAIGN_ID, // Using the dedicated MMS ID
  //   to: recipient,
  //   from: SINCH_NUMBER,
  //   ""message-subject"": subject,
  //   slide: [ { image: { url: mediaFileUrl }, ""message-text"": messageText || """" } ],
  //   ...(clientReference && { ""client-reference"": clientReference }) // Field name might differ
  //   // ... other MMS options like fallback
  // }
  // **Again, verify the correct structure with official documentation.**


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

  try {
    console.log('Sending request to Sinch Endpoint:', SINCH_MMS_ENDPOINT);
    console.log('Payload:', JSON.stringify(payload, null, 2));
    const response = await axios.post(SINCH_MMS_ENDPOINT, payload, config);
    console.log('Sinch API Response Status:', response.status);
    console.log('Sinch API Response Data:', JSON.stringify(response.data, null, 2));

    // **Response Structure Check:**
    // This check assumes the /batches endpoint returns a top-level 'id'.
    // The actual success response structure for MMS might differ significantly.
    // Verify against the response you receive from the *correct* MMS API call.
    if (response.data && response.data.id) {
       return { success: true, trackingId: response.data.id, details: response.data };
    } else {
        // Handle unexpected success response format
        console.warn(""Sinch response format might be different than expected for MMS:"", response.data);
        // Return raw data even if 'id' is missing, but flag potential issue
        return { success: true, trackingId: null, details: response.data };
    }

  } catch (error) {
    console.error('Error sending MMS via Sinch:');
    let errorDetails = { message: 'An unknown error occurred.' };
    let statusCode = 500;

    if (error.response) {
      // Request made, server responded with non-2xx status
      console.error('Status:', error.response.status);
      console.error('Headers:', error.response.headers);
      console.error('Data:', JSON.stringify(error.response.data, null, 2));
      errorDetails = error.response.data || { message: `Sinch API Error: ${error.response.status}` };
      statusCode = error.response.status;
    } else if (error.request) {
      // Request made, no response received
      console.error('Request Error:', error.request);
      errorDetails = { message: 'No response received from Sinch API.' };
      statusCode = 504; // Gateway Timeout
    } else {
      // Error setting up the request
      console.error('Axios Setup Error:', error.message);
      errorDetails = { message: `Request setup error: ${error.message}` };
    }
    return { success: false, error: errorDetails, statusCode: statusCode };
  }
}

// --- API Endpoint ---
app.post('/send-mms', validateMmsRequest, async (req, res) => {
  // Allow clientReference to be passed in request for idempotency
  const { to, text, mediaUrl, subject, clientReference } = req.body;

  // --- E.164 Formatting (Basic & Fragile) ---
  // WARNING: This logic is basic, error-prone, and assumes US/Canada structure.
  // It lacks robust validation for international numbers.
  // Use a dedicated library like 'libphonenumber-js' or validation within 'express-validator' (Section 3) for production.
  let formattedTo = String(to).trim();
  if (!formattedTo.startsWith('+')) {
      if (formattedTo.length === 11 && formattedTo.startsWith('1')) {
          formattedTo = `+${formattedTo}`; // Assume US/Canada +1 prefix needed
      } else if (formattedTo.length === 10 && SINCH_REGION === 'us') { // Very basic US check
          formattedTo = `+1${formattedTo}`; // Attempt to prefix +1
          console.warn(`Assuming US country code (+1) for number: ${to}. Result: ${formattedTo}. Use E.164 format for reliability.`);
      } else {
           // Cannot reliably determine country code, just add '+'
           formattedTo = `+${formattedTo}`;
           console.warn(`Number format unknown, adding '+' prefix: ${formattedTo}. Please provide numbers in E.164 format (e.g., +1xxxxxxxxxx).`);
      }
  }
  // --- End Basic Formatting ---

  // Pass clientReference to the sending function
  const result = await sendSinchMms(formattedTo, text, mediaUrl, subject, clientReference);

  if (result.success) {
    res.status(200).json({
      message: 'MMS request potentially accepted by Sinch (verify response details).',
      trackingId: result.trackingId, // May be null if response format differs
      details: result.details
    });
  } else {
    // Use the status code from Sinch if available (4xx, 5xx), otherwise default to 500
    const responseStatusCode = (result.statusCode && result.statusCode >= 400 && result.statusCode < 600) ? result.statusCode : 500;
    res.status(responseStatusCode).json({
      error: 'Failed to send MMS'_
      details: result.error_
    });
  }
});

// --- Basic Health Check Endpoint ---
app.get('/health'_ (req_ res) => {
    res.status(200).json({ status: 'UP', timestamp: new Date().toISOString() });
});


// --- Start Server ---
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  // Log essential config on startup (excluding sensitive token)
  console.log(`Sinch Number: ${SINCH_NUMBER}`);
  console.log(`Sinch Region: ${SINCH_REGION}`);
  console.log(`Sinch Service Plan ID: ${SINCH_SERVICE_PLAN_ID}`);
  console.log(`Sinch MMS Campaign ID: ${SINCH_MMS_CAMPAIGN_ID} (Verify usage based on actual API requirements)`);
  console.log(`Target Sinch Endpoint: ${SINCH_MMS_ENDPOINT} (**VERIFY THIS IS CORRECT FOR MMS**)`);
});

Explanation:

1. Dependencies & Config: Standard setup, loading environment variables. Crucially notes the uncertainty of SINCH_MMS_ENDPOINT.
2. Middleware: Includes basic validation (validateMmsRequest). More robust validation is covered in Section 3.
3. sendSinchMms Function:
   • Takes recipient, text, media URL, subject, and an optional clientReference.
   • Payload Construction: Creates a payload based on the speculative use of the /batches endpoint. Strong warnings are added here and in comments, emphasizing that this structure (media_body, parameters) is likely incorrect and official Sinch MMS documentation must be consulted. An example of a more likely dedicated MMS payload structure is commented out for illustration.
   • Includes client_reference in the payload if provided.
   • Uses axios.post within try...catch.
   • Response Handling: Checks for response.data.id (common for /batches) but adds a warning that the actual MMS success response might differ and the trackingId could be null if the structure is different.
   • Returns success/failure status and details.
4. /send-mms Endpoint:
   • Uses validation middleware.
   • Extracts data, including the optional clientReference.
   • Includes the basic, fragile E.164 formatting logic with added warnings recommending a proper library for production.
   • Calls sendSinchMms with the extracted data.
   • Responds to the client based on the result.
5. /health Endpoint: Simple health check.
6. Server Start: Starts the server and logs configuration, including a reminder to verify the target endpoint.

3. Building a complete API layer

Our current setup provides a single endpoint. A more complete API layer would involve:

• Robust Request Validation: Use a dedicated library like express-validator for comprehensive validation. This is highly recommended over the basic checks and formatting in Section 2.
  bash

  npm install express-validator libphonenumber-js # Add phone number library
  
  javascript

  // Example using express-validator (install dependencies first)
  const { body, validationResult } = require('express-validator');
  const { parsePhoneNumberFromString } = require('libphonenumber-js');
  
  app.post('/send-mms',
    // Validate 'to' number using libphonenumber-js within a custom validator
    body('to').custom(value => {
        const phoneNumber = parsePhoneNumberFromString(String(value));
        if (!phoneNumber || !phoneNumber.isValid()) {
            throw new Error('Invalid phone number format. Use E.164 format (e.g., +1xxxxxxxxxx).');
        }
        return true; // Indicates validation passed
    }).bail(), // Stop validation if phone number is invalid
    // Sanitize 'to' number to E.164 format AFTER validation
    body('to').customSanitizer(value => {
        const phoneNumber = parsePhoneNumberFromString(String(value));
        return phoneNumber.format('E.164'); // Convert to +1xxxxxxxxxx
    }),
    body('mediaUrl').isURL().withMessage('Invalid URL format for mediaUrl.'),
    body('text').optional().isString().isLength({ max: 5000 }).withMessage('Text exceeds maximum length.'),
    body('subject').optional().isString().isLength({ max: 80 }).withMessage('Subject exceeds maximum length.'),
    body('clientReference').optional().isString().isLength({ min: 1, max: 64 }).withMessage('clientReference must be between 1 and 64 characters.'), // Example validation
    (req, res, next) => {
      const errors = validationResult(req);
      if (!errors.isEmpty()) {
        return res.status(400).json({ errors: errors.array() });
      }
      // Validation passed, sanitized data is available in req.body
      next();
    },
    async (req, res) => {
      // Access validated and sanitized data from req.body
      const { to, text, mediaUrl, subject, clientReference } = req.body;
      // The basic formatting logic from Section 2 is no longer needed here
      const result = await sendSinchMms(to, text, mediaUrl, subject, clientReference);
      // ... rest of the handler logic ...
    }
  );
  
• Authentication/Authorization: Secure your API endpoint (API Keys, JWT, etc.).
• API Documentation: Use tools like Swagger/OpenAPI (swagger-ui-express, swagger-jsdoc).

Testing the Endpoint:

Use curl or Postman.

Using curl:

curl -X POST http://localhost:3000/send-mms \
-H ""Content-Type: application/json"" \
-d '{
    ""to"": ""+12065551212"",
    ""text"": ""Check out this cool image!"",
    ""mediaUrl"": ""https://www.example.com/path/to/your/public/image.jpg"",
    ""subject"": ""My MMS Subject"",
    ""clientReference"": ""my-unique-id-12345""
}'

Example Responses (Illustrative - Actual Responses Will Vary):

Disclaimer: The following success/error responses are examples based on the speculative API call structure used in this guide (Sinch /batches endpoint). The actual responses you receive from Sinch will depend on the correct MMS endpoint and payload structure you identify and use from the official documentation. They may look significantly different.

Potential Success Response (Example, based on /batches structure):

{
  ""message"": ""MMS request potentially accepted by Sinch (verify response details)."",
  ""trackingId"": ""01J3Z4Y5X6W7V8T9S0R1Q2P3N4"",
  ""details"": {
    ""id"": ""01J3Z4Y5X6W7V8T9S0R1Q2P3N4"",
    ""to"": [ ""+12065551212"" ],
    ""from"": ""+1YOURSINCHNUMBER"",
    ""canceled"": false,
    ""body"": ""Check out this cool image!"",
    ""media_body"": ""https://www.example.com/path/to/your/public/image.jpg"",
    ""parameters"": { ""mms_subject"": ""My MMS Subject"" },
    ""type"": ""mt_media"",
    ""created_at"": ""2025-04-20T10:00:00.000Z"",
    ""modified_at"": ""2025-04-20T10:00:00.000Z""
  }
}

Potential Error Response (Example - Invalid Request to /batches):

{
  ""error"": ""Failed to send MMS"",
  ""details"": {
    ""requestError"": {
        ""serviceException"": {
            ""messageId"": ""4000x"",
            ""text"": ""Parameter validation error: Unknown field 'media_body'"",
            ""variables"": []
        }
    }
  }
}

4. Integrating with Sinch (Credentials & Configuration)

We've set up integration using environment variables.

• Obtaining Credentials:
  1. Log in to your Sinch Customer Dashboard.
  2. Navigate to SMS -> APIs for SINCH_SERVICE_PLAN_ID and SINCH_API_TOKEN. Copy these to .env.
  3. Click your Service Plan ID link, find Phone numbers, and copy an MMS-enabled number to SINCH_NUMBER (use E.164 format ideally, e.g., +1...).
  4. Locating SINCH_MMS_CAMPAIGN_ID: This is critical. Look specifically within the MMS sections of the dashboard or your specific MMS product configuration. It might be called ""Campaign ID"", ""Service ID"", or similar. Verify if it's required and if it differs from SINCH_SERVICE_PLAN_ID. If you cannot find a separate MMS ID, you might initially try using the SINCH_SERVICE_PLAN_ID value, but confirm this requirement based on the correct API payload structure found in the official MMS docs. Contact Sinch support if needed.
  5. Note the Region (e.g., US, EU) from the API page for SINCH_REGION.
• Secure Handling: Use .env locally, but use secure environment variable management in production (AWS Secrets Manager, Heroku Config Vars, etc.). Never commit .env.
• Fallback Mechanisms: The actual Sinch MMS API likely supports SMS fallback (e.g., via payload fields like fallback_info). Consult the official MMS API docs to see how to configure this if needed.

5. Error handling, logging, and retry mechanisms

Enhance the basic try...catch and logging.

• Consistent Error Strategy: Standardize API error responses.
• Logging: Use Winston or Pino for structured logging.
  bash

  npm install winston
  
  javascript

  // Example Winston setup (place near the top of server.js)
  const winston = require('winston');
  const logger = winston.createLogger({ /* ... configuration ... */ });
  // Replace console.log/error with logger.info/warn/error
  
• Retry Mechanisms: Use axios-retry for transient errors (5xx, network).
  bash

  npm install axios-retry
  
  javascript

  // Example using axios-retry
  const axiosRetry = require('axios-retry').default; // .default often needed for require with ESM/TS interop
  // (Users can verify if .default is needed for their specific library versions)
  
  const axiosInstance = axios.create(); // Create an Axios instance
  axiosRetry(axiosInstance, {
      retries: 3,
      retryDelay: (retryCount) => {
          logger.warn(`Retrying Sinch API request attempt ${retryCount}`);
          return Math.pow(2, retryCount) * 1000; // Exponential backoff (2s, 4s, 8s)
      },
      retryCondition: (error) => {
          // Retry on network errors or 5xx server errors
          return (
              axiosRetry.isNetworkOrIdempotentRequestError(error) ||
              (error.response && error.response.status >= 500 && error.response.status <= 599)
          );
      },
  });
  
  // In sendSinchMms, use axiosInstance instead of the global axios:
  // const response = await axiosInstance.post(SINCH_MMS_ENDPOINT, payload, config);
  

6. Database schema and data layer (Optional for this scope)

For tracking sent messages, consider a database (mms_log table) with fields like id, recipient, sinch_number, media_url, message_text, subject, sinch_tracking_id, status (updated via webhooks), submitted_at, last_updated_at, error_message. Use an ORM (Prisma, Sequelize) for interaction and migrations.

7. Adding security features

• Input Validation: Use express-validator (Section 3) as the primary defense.
• Rate Limiting: Use express-rate-limit to prevent abuse.
  bash

  npm install express-rate-limit
  
  javascript

  const rateLimit = require('express-rate-limit');
  const apiLimiter = rateLimit({ /* ... configuration ... */ });
  app.use('/send-mms', apiLimiter);
  
• Helmet: Set security-related HTTP headers.
  bash

  npm install helmet
  
  javascript

  const helmet = require('helmet');
  app.use(helmet());
  
• Secure Credential Management: Reinforce using secure environment variables in production.
• HTTPS: Essential in production (usually handled by load balancers/reverse proxies like Nginx).

8. Handling special cases relevant to MMS

• Media URL Requirements:
  • Must be publicly accessible (no auth).
  • Hosting server must provide Content-Length and correct Content-Type (e.g., image/jpeg, video/mp4). Invalid headers or chunked encoding without Content-Length will likely cause failures.
• Character/Size Limits: Check Sinch docs and carrier guidelines for subject (~40-80 chars), text (~1000-5000 chars), and media file size (often ~1MB, varies).
• Number Formatting: Use E.164 consistently (+CountryCodeNumber). Validate rigorously.
• Fallback SMS: Consult official Sinch MMS docs for how to configure SMS fallback in the payload if MMS fails or is unsupported.
• Idempotency: The code now supports sending a clientReference (see Section 2). To prevent duplicates on retries, generate a unique ID (e.g., UUID) on the client or server, pass it as clientReference, and ensure your logic (potentially checking a database before calling sendSinchMms) or Sinch handles this reference to avoid resending the same logical message. The exact field name (client_reference, client-reference) needs verification from Sinch docs.

9. Implementing performance optimizations

• Asynchronous Operations: Node.js/Axios handle this well.
• Caching: Ensure media hosting server uses HTTP caching. Sinch might offer caching options (check docs).
• Load Testing: Use k6, Artillery, etc., to find bottlenecks.
• Profiling: Use node --prof or Clinic.js if performance issues arise.

10. Adding monitoring, observability, and analytics

• Health Checks: /health endpoint provided. Enhance as needed.
• Structured Logging: Use Winston/Pino, send to a central platform (Datadog, Splunk, ELK).
• Metrics: Track request rate/latency, error rates, Sinch API latency/errors using prom-client (for Prometheus).
• Error Tracking: Use Sentry, Bugsnag.
• Dashboards: Visualize metrics (Grafana, Datadog).
• Sinch Webhooks (Crucial for Status): Configure webhooks in your Sinch dashboard to point to an endpoint in your app (e.g., /webhooks/sinch/dlr). Handle incoming delivery receipts (DELIVERED, FAILED, etc.) to update message status in your database (if used). This is essential for knowing the final outcome.

11. Troubleshooting and Caveats

• Authentication Errors (401): Check SINCH_API_TOKEN, Authorization: Bearer header.
• Invalid Request Errors (400): Check Sinch error details (error.response.data). Common causes:
  • Incorrect API Endpoint/Payload: The most likely issue given the uncertainty. Verify with official MMS docs.
  • Invalid to number format (use E.164).
  • Missing required fields in the payload.
  • Incorrect field names in the payload (e.g., media_body vs. the actual required field).
  • Media URL issues (not public, missing headers).
• Media Fetch Failures: Check media server logs, Content-Type/Content-Length headers. Ensure the URL is accessible from Sinch's servers.
• Delivery Failures (FAILED Webhook): Check Sinch error codes in the webhook payload. Could be carrier blocks, invalid number, unsupported content type, etc.
• Rate Limits: Check Sinch API rate limits and implement client-side throttling or use express-rate-limit.
• Endpoint/Payload Uncertainty: Reiterate that the provided code uses a speculative endpoint and payload. Finding and using the correct Sinch MMS API endpoint and payload structure from official documentation is the most critical step for success.