Sending MMS Messages with Node.js, Express, and MessageBird - code-examples -

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 MessageBird API. We'll cover everything from project setup to deployment considerations, enabling you to integrate MMS capabilities into your applications effectively.

By the end of this tutorial, you will have a functional Express API endpoint capable of accepting requests to send MMS messages, including text and media content, to specified recipients using your MessageBird account. This solves the need for programmatic MMS communication, useful for notifications, alerts, marketing, or integrating messaging into custom workflows.

Prerequisites

Before starting, ensure you have the following:

  1. Node.js and npm (or yarn): Installed on your development machine. You can download them from nodejs.org.
  2. MessageBird Account: A registered account on MessageBird.
  3. MessageBird API Key: A live API key obtained from your MessageBird Dashboard (Developers -> API access).
  4. Registered Sender ID or Virtual Number: A valid originator (phone number or approved alphanumeric sender ID) configured in your MessageBird account. Note that alphanumeric sender IDs are not supported in all countries (e.g., the US) and cannot receive replies. For testing, you might need to verify your own phone number first.
  5. Publicly Accessible Media URL: A URL pointing to the image or media file you want to send via MMS. MessageBird needs to be able to access this URL to fetch the media. Services like AWS S3, Google Cloud Storage, or even a public web server can host this.
  6. Basic Understanding: Familiarity with JavaScript, Node.js, and REST APIs.
  7. Awareness of Messaging Costs: Understand that MMS messages generally incur higher costs than standard SMS messages. Check MessageBird's pricing.

1. Setting up the project

Let's start by creating our Node.js project structure and installing the necessary dependencies.

  1. Create Project Directory: Open your terminal or command prompt and create a new directory for your project, then navigate into it.

    mkdir node-messagebird-mms
cd node-messagebird-mms

  2. Initialize Node.js Project: Initialize the project using npm (or yarn). The -y flag accepts the default settings.

    npm init -y

    This creates a package.json file.

  3. Install Dependencies: We need express for the web server framework, messagebird for the official Node.js SDK, and dotenv to manage environment variables securely.

    npm install express messagebird dotenv
    • express: Fast, unopinionated, minimalist web framework for Node.js. We use it to create our API endpoint.
    • messagebird: The official MessageBird SDK simplifies interactions with the MessageBird REST API.
    • dotenv: Loads environment variables from a .env file into process.env, keeping sensitive data like API keys out of source code.

  4. Create Core Files: Create the main application file and environment configuration files.

    touch index.js .env .gitignore
    • index.js: This will contain our Express application and MessageBird integration logic.
    • .env: This file will store our sensitive MessageBird API key and sender ID. Never commit this file to version control.
    • .gitignore: Specifies intentionally untracked files that Git should ignore.

  5. Configure .gitignore: Open .gitignore and add the following lines to prevent committing sensitive information and unnecessary files:

    # Environment variables
.env

# Node dependencies
node_modules/

# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*

  6. Configure .env: Open the .env file and add your MessageBird API key and your registered sender ID (originator). Replace the placeholder values with your actual credentials.

    # .env
MESSAGEBIRD_API_KEY=YOUR_LIVE_API_KEY
MESSAGEBIRD_ORIGINATOR=YOUR_SENDER_ID_OR_NUMBER
    • MESSAGEBIRD_API_KEY: Your live API key from the MessageBird dashboard.
    • MESSAGEBIRD_ORIGINATOR: Your purchased virtual number (e.g., +12025550181) or approved alphanumeric sender ID (e.g., MyCompany).

This completes the basic project setup. We have our dependencies installed and configuration files ready.

2. Implementing core functionality: Sending MMS

Now, let's write the core logic to send an MMS message using the MessageBird SDK. We'll encapsulate this in a reusable function.

  1. Initialize SDK and Environment Variables: Open index.js and start by requiring the necessary modules and loading the environment variables using dotenv.

    // index.js
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const messagebird = require('messagebird').initClient(process.env.MESSAGEBIRD_API_KEY); // Initialize MessageBird client

const app = express();
const PORT = process.env.PORT || 3000; // Use port from env or default to 3000

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

console.log('MessageBird SDK Initialized.');
// --- Rest of the code will go here ---
    • require('dotenv').config() loads the variables from .env. Crucially, this line must come before accessing process.env variables.
    • require('messagebird').initClient(...) initializes the MessageBird SDK using the API key loaded from the environment. This initialization method aligns with the MessageBird documentation and addresses common integration patterns.

  2. Create the MMS Sending Function: Let's define an asynchronous function sendMmsMessage that takes the recipient number, message body, and media URL as arguments.

    // index.js (continued)

/**
 * Sends an MMS message using the MessageBird API.
 * @param {string} recipient - The recipient's phone number in E.164 format (e.g., +12025550181).
 * @param {string} body - The text content of the message.
 * @param {string} mediaUrl - The publicly accessible URL of the media file to include.
 * @returns {Promise<object&gt;} - A promise that resolves with the MessageBird API response on success.
 * @throws {Error} - Throws an error if the API call fails.
 */
async function sendMmsMessage(recipient, body, mediaUrl) {
  console.log(`Attempting to send MMS to ${recipient} with media: ${mediaUrl}`);

  const params = {
    originator: process.env.MESSAGEBIRD_ORIGINATOR,
    recipients: [recipient], // Must be an array
    body: body,
    // MMS specific parameter: mediaUrls
    // NOTE: Confirm the exact parameter name in the official MessageBird API documentation
    // as API specifications can evolve. Common patterns include `mediaUrls` or `mmsOptions`.
    // We will use `mediaUrls` based on common API patterns.
    mediaUrls: [mediaUrl] // Must be an array of public URLs
  };

  return new Promise((resolve, reject) =&gt; {
    messagebird.messages.create(params, function (err, response) {
      if (err) {
        console.error(""MessageBird API Error:"", err); // Corrected syntax
        // Enhance error message for common issues
        if (err.errors && err.errors.length &gt; 0) {
            const firstError = err.errors[0];
            if (firstError.code === 9) { // Specific error code for recipient issues
                reject(new Error(`Failed to send message: ${firstError.description} (Code: ${firstError.code}). Ensure recipient number is valid and verified if using a trial account.`));
            } else {
                reject(new Error(`Failed to send message: ${firstError.description} (Code: ${firstError.code})`));
            }
        } else {
            reject(new Error(`Failed to send message: ${err.message || 'Unknown API error'}`));
        }
      } else {
        console.log(""MessageBird API Success:"", response); // Corrected syntax
        resolve(response); // Resolve the promise with the successful response
      }
    });
  });
}

// --- API endpoint will be defined below ---
    • Parameters: The function takes recipient, body, and mediaUrl.
    • params Object: We construct the payload for the messagebird.messages.create method.
      • originator: Loaded from .env.
      • recipients: An array containing the single recipient number. MessageBird expects an array even for one recipient.
      • body: The text part of the MMS.
      • mediaUrls: This is the crucial part for MMS. We use mediaUrls as the likely parameter name (based on general API conventions). It's an array containing the public URL(s) of the media file(s). Crucially, always verify the exact parameter name in the latest MessageBird API documentation.
    • Promise Wrapper: We wrap the messagebird.messages.create call in a Promise. This allows us to use async/await syntax in our API endpoint later, making the code cleaner. The SDK uses a callback pattern, so the Promise resolves on success (response) and rejects on error (err).
    • Error Handling: The reject path includes logging and creates a more informative error message, especially handling the specific code: 9 error related to recipients found in the research.

3. Building the API layer (Express endpoint)

Now, let's create an Express route that accepts POST requests to trigger our sendMmsMessage function.

  1. Define the API Endpoint: Add the following code in index.js after the sendMmsMessage function definition.

    // index.js (continued)

// --- MMS Sending Function defined above ---

// API Endpoint to send MMS
app.post('/send-mms', async (req, res) =&gt; {
  console.log('Received request on /send-mms');
  const { recipient, body, mediaUrl } = req.body; // Extract data from request body

  // Basic Input Validation
  if (!recipient || !body || !mediaUrl) {
    console.warn('Validation failed: Missing recipient, body, or mediaUrl');
    return res.status(400).json({
      success: false,
      message: 'Missing required fields: recipient, body, mediaUrl',
    });
  }

  // Basic validation for recipient format (starts with '+', followed by digits)
  if (!/^\+[1-9]\d{1,14}$/.test(recipient)) {
     console.warn(`Validation failed: Invalid recipient format for ${recipient}`);
     return res.status(400).json({
        success: false,
        message: 'Invalid recipient format. Use E.164 format (e.g., +12025550181).',
     });
  }

  // Basic validation for media URL format
  try {
    new URL(mediaUrl); // Check if it's a valid URL structure
  } catch (_) {
    console.warn(`Validation failed: Invalid mediaUrl format for ${mediaUrl}`);
    return res.status(400).json({
        success: false,
        message: 'Invalid mediaUrl format.',
    });
  }


  try {
    // Call the MMS sending function
    const messageBirdResponse = await sendMmsMessage(recipient, body, mediaUrl);

    console.log(`Successfully sent message to ${recipient}. MessageBird ID: ${messageBirdResponse.id}`);
    // Respond with success
    res.status(200).json({
      success: true,
      message: 'MMS sent successfully initiated.',
      details: {
        messageId: messageBirdResponse.id,
        recipientsTotalCount: messageBirdResponse.recipients.totalCount,
        recipientsSentCount: messageBirdResponse.recipients.totalSentCount,
      }
    });
  } catch (error) {
    console.error(`Error sending MMS via API endpoint: ${error.message}`);
    // Respond with an error
    res.status(500).json({
      success: false,
      message: 'Failed to send MMS.',
      error: error.message // Provide the specific error from the sending function
    });
  }
});

// Start the Express server
app.listen(PORT, () =&gt; {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`API endpoint available at POST /send-mms`);
  console.log(`Using Originator: ${process.env.MESSAGEBIRD_ORIGINATOR || 'Not Set'}`);
  if (!process.env.MESSAGEBIRD_API_KEY) {
    console.error('FATAL: MESSAGEBIRD_API_KEY is not set in the environment variables!');
  }
   if (!process.env.MESSAGEBIRD_ORIGINATOR) {
    console.error('WARNING: MESSAGEBIRD_ORIGINATOR is not set in the environment variables!');
  }
});
    • Route Definition: app.post('/send-mms', ...) defines a route that listens for POST requests at the /send-mms path.
    • Data Extraction: const { recipient, body, mediaUrl } = req.body; extracts the necessary data from the JSON payload of the incoming request.
    • Input Validation: Basic checks ensure that recipient, body, and mediaUrl are present. Added basic E.164 format check for recipient and URL format check for mediaUrl. For production, use robust validation libraries like joi or express-validator.
    • Function Call: await sendMmsMessage(...) calls our core logic function. Using await requires the route handler to be async.
    • Response Handling:
      • On success, it sends a 200 OK response with relevant details from the MessageBird API response.
      • On failure (caught by the catch block), it sends a 500 Internal Server Error response including the error message.
    • Server Start: app.listen(...) starts the Express server and logs confirmation messages, including checks for the essential environment variables.

4. Integrating with MessageBird

This section summarizes the key integration points already covered:

  1. Installation: The MessageBird SDK was installed via npm install messagebird.
  2. Initialization: The SDK is initialized in index.js using require('messagebird').initClient(process.env.MESSAGEBIRD_API_KEY).
  3. API Key: The API key is securely stored in the .env file and accessed via process.env.MESSAGEBIRD_API_KEY.
    • How to Obtain:
      1. Log in to your MessageBird Dashboard.
      2. Navigate to the Developers section in the left-hand menu.
      3. Click on the API access tab.
      4. If you don't have a key, click Add access key. Ensure you are creating or using a Live key for actual sending (not a Test key, unless specifically testing API connectivity).
      5. Copy the generated key and paste it as the value for MESSAGEBIRD_API_KEY in your .env file.
  4. Originator: The sender ID or number is stored in .env and accessed via process.env.MESSAGEBIRD_ORIGINATOR.
    • How to Obtain/Configure:
      1. In the MessageBird Dashboard, navigate to Numbers to purchase a virtual number capable of SMS/MMS, or navigate to Channels -> SMS -> Sender IDs to request an alphanumeric sender ID (subject to approval and country restrictions).
      2. Copy the purchased number (in E.164 format, e.g., +12025550181) or the approved alphanumeric ID and paste it as the value for MESSAGEBIRD_ORIGINATOR in your .env file.
  5. API Call: The messagebird.messages.create(params, callback) function is used to interact with the MessageBird API for sending messages.

5. Error handling and logging

We've implemented basic error handling and logging:

  1. API Error Handling: The sendMmsMessage function's Promise catches errors from the messagebird.messages.create callback. It logs the error and rejects the promise with a descriptive error message, including specific handling for code: 9 (recipient errors).
  2. Endpoint Error Handling: The /send-mms route uses a try...catch block to handle errors during the process (including validation errors and errors from sendMmsMessage). It returns appropriate HTTP status codes (400 for validation, 500 for server/API errors) and JSON error messages.
  3. Logging: console.log, console.warn, and console.error are used to log information about requests, successful operations, validation failures, and errors. For production environments, consider using more structured logging libraries like Pino or Winston, which enable different log levels, formatting, and routing logs to files or external services.

Testing Error Scenarios:

  • Send a request without a recipient, body, or mediaUrl to test the 400 validation error.
  • Send a request with an invalid MESSAGEBIRD_API_KEY in .env to test API authentication errors (likely caught by the err in the callback).
  • If using a trial account, send to a non-verified number to test the code: 9 error.
  • Provide an invalid or inaccessible mediaUrl.

6. Adding security features

Security is paramount, especially when dealing with APIs and external services.

  1. API Key Security:
    • Environment Variables: Storing the MESSAGEBIRD_API_KEY in .env and loading it via dotenv is crucial.
    • .gitignore: Ensure .env is listed in .gitignore to prevent accidental commits of credentials.
    • Access Control: In a production environment, restrict file system permissions for the .env file. Use platform-specific secret management tools (like AWS Secrets Manager, Google Secret Manager, HashiCorp Vault) for enhanced security.
  2. Input Validation:
    • The /send-mms endpoint includes basic checks for required fields and format validation for the recipient number and media URL.
    • Recommendation: Use dedicated libraries like joi or express-validator for more complex and robust validation rules in production applications (e.g., checking URL schemes, phone number validity more strictly, message length).
  3. Rate Limiting:
    • To prevent abuse of your API endpoint, implement rate limiting. Middleware like express-rate-limit can restrict the number of requests from a single IP address within a given time frame.
    • Example using express-rate-limit: 
      npm install express-rate-limit

      // index.js (near the top, after app initialization)
const rateLimit = require('express-rate-limit');

const apiLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per windowMs
  standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
  legacyHeaders: false, // Disable the `X-RateLimit-*` headers
  message: 'Too many requests from this IP, please try again after 15 minutes'
});

// Apply the rate limiting middleware to API routes
// Apply specifically to this route or globally
app.use('/send-mms', apiLimiter);
// Or app.use(apiLimiter); // To apply to all routes
  4. HTTPS: Always deploy your application behind HTTPS to encrypt communication between the client and your server. Deployment platforms like Heroku, Vercel, or cloud load balancers typically handle SSL termination.

7. Troubleshooting and Caveats

Here are common issues and considerations when working with MessageBird MMS sending:

  1. Initialization Error:

    • Error: TypeError: require(...) is not a function
    • Cause: Incorrectly initializing the MessageBird client.
    • Solution: Ensure you use require('messagebird').initClient('YOUR_API_KEY'); as shown in the guide. This is the correct initialization method.

  2. Recipient Error (Error Code 9):

    • Error: statusCode: 422, errors: [ { code: 9, description: 'no (correct) recipients found...' } ]
    • Cause:
      • Using a trial MessageBird account: You can only send messages to numbers you have verified in your MessageBird dashboard during the trial period.
      • Invalid recipient number format: Ensure numbers are in E.164 format (e.g., +12025550181).
      • Sending to a country/carrier that doesn't support your originator type (e.g., using an alphanumeric sender where it's restricted).
    • Solution: Verify your recipient number in the MessageBird dashboard if on a trial. Ensure correct E.164 formatting. Use a purchased virtual number as the originator for broader compatibility, especially in the US. Check MessageBird's country restrictions documentation.

  3. Invalid API Key:

    • Error: Authentication errors (often a 401 Unauthorized status code in the err object).
    • Cause: Incorrect API key in .env, using a Test key instead of a Live key, or the key has been revoked.
    • Solution: Double-check the MESSAGEBIRD_API_KEY in your .env file matches a valid Live API key from your dashboard.

  4. Insufficient Balance:

    • Error: Errors related to billing or insufficient funds (check err object details).
    • Cause: Your MessageBird account doesn't have enough credit to send the message. Note that MMS messages typically cost significantly more than standard SMS.
    • Solution: Add credits to your MessageBird account balance.

  5. Media URL Issues:

    • Error: Message sent as SMS only, or errors related to media fetching (check MessageBird logs).
    • Cause: The mediaUrl provided is not publicly accessible, points to an invalid/unsupported media type, or the URL is malformed. MessageBird's servers timed out trying to fetch the media.
    • Solution: Ensure the URL is public, directly links to the media file (not an HTML page), uses supported media types (check MessageBird docs for supported formats like JPEG, PNG, GIF), and is accessible from the internet. Test the URL in an incognito browser window.

  6. MMS Parameter Name:

    • Caveat: The parameter for including media might change (e.g., mediaUrls, mms.mediaUrls, attachments).
    • Solution: Always refer to the current official MessageBird REST API documentation for the messages endpoint to confirm the correct parameter name and structure for sending MMS content. Our guide uses mediaUrls as a common convention.

  7. MMS Support: Not all carriers or destination countries fully support MMS, or may have limitations on file size or type. Delivery issues might occur due to downstream carrier limitations.

8. Deployment and CI/CD

Deploying this application involves running the Node.js server in a hosting environment.

  1. Environment Configuration:

    • Crucial: Do not deploy your .env file directly. Production environments (like Heroku, AWS Elastic Beanstalk, Vercel, Google Cloud Run) provide mechanisms to set environment variables securely through their dashboards or configuration files.
    • Set MESSAGEBIRD_API_KEY and MESSAGEBIRD_ORIGINATOR in your chosen hosting provider's environment variable settings.
    • Optionally set PORT if your provider requires binding to a specific port.

  2. Deployment Procedures (Conceptual):

    • Platforms like Heroku/Vercel:
      1. Push your code to a Git repository (ensure .env and node_modules are in .gitignore).
      2. Connect your hosting platform account to your Git provider (GitHub, GitLab, Bitbucket).
      3. Create a new app/project on the hosting platform, linking it to your repository.
      4. Configure the required environment variables (MESSAGEBIRD_API_KEY, MESSAGEBIRD_ORIGINATOR) in the platform's settings dashboard.
      5. Trigger a deployment (often automatic on push to the main branch).
    • Virtual Machines / Containers (AWS EC2, Docker):
      1. Package your application (e.g., using Docker).
      2. Set up a process manager (like pm2) to keep your Node.js app running and manage restarts.
      3. Configure environment variables securely (e.g., through instance metadata, system environment variables, or secret management services).
      4. Deploy the container or application code to the server.
      5. Configure a reverse proxy (like Nginx or Apache) to handle incoming traffic, SSL termination, and forward requests to your Node.js app.

  3. CI/CD Pipeline (Conceptual):

    • Use tools like GitHub Actions, GitLab CI, Jenkins, or CircleCI.
    • Build Stage: Install dependencies (npm install), run linters/formatters.
    • Test Stage: Run automated tests (unit, integration). Consider using a Test API key and mocking MessageBird responses for tests.
    • Deploy Stage: If tests pass on the main branch, automatically deploy to your hosting environment (e.g., using platform CLIs or deployment integrations). Securely inject production environment variables during this stage.

  4. Rollback Procedures: Familiarize yourself with your hosting platform's rollback mechanism (e.g., deploying a previous Git commit or Docker image tag) in case a deployment introduces issues.

9. Verification and Testing

After deployment or during development, verify the functionality:

  1. Start the Server:

    node index.js

    Check the console for successful startup messages and any warnings about missing environment variables.

  2. Manual API Testing (using curl): Open a new terminal window and send a POST request to your running server. Replace placeholders with valid data.

    curl -X POST http://localhost:3000/send-mms \
     -H ""Content-Type: application/json"" \
     -d '{
           ""recipient"": ""+12025550181"",
           ""body"": ""Hello from Node.js! Check out this image."",
           ""mediaUrl"": ""https://www.messagebird.com/assets/images/og/messagebird.png""
         }'
    • Replace +12025550181 with a valid recipient number (your verified number if testing on a trial account).
    • Replace the mediaUrl with a valid, publicly accessible image URL.
    • If deployed, replace http://localhost:3000 with your production URL.

  3. Check Server Logs: Look for the request log (Received request on /send-mms), attempt log (Attempting to send MMS...), and either the success log (MessageBird API Success: ...) or error log (MessageBird API Error: ...).

  4. Check Recipient Phone: Verify that the MMS message (including text and media) arrives on the recipient's device. Delivery times can vary.

  5. Check MessageBird Dashboard:

    • Log in to the MessageBird Dashboard.
    • Navigate to SMS -> Message Logs.
    • Find the message you sent. Check its status (e.g., sent, delivered, failed). Click on the log entry for more details, including any potential error codes if it failed. This is crucial for debugging delivery issues.

  6. Verification Checklist:

    • Server starts without critical errors.
    • /send-mms endpoint is reachable.
    • Requests with valid data receive a 200 OK response containing a MessageBird message ID.
    • Requests with missing/invalid data receive appropriate 400 Bad Request errors.
    • Server logs show successful API calls or detailed error messages.
    • MMS message (text + media) is received on the target device.
    • Message status in the MessageBird Dashboard logs is sent or delivered.

Conclusion

You have successfully built a Node.js Express application capable of sending MMS messages using the MessageBird API. We covered project setup, core sending logic using the MessageBird SDK, creating an API endpoint, handling configuration and API keys securely, basic error handling, security considerations, troubleshooting common issues, and deployment concepts.

This foundation enables you to integrate MMS capabilities reliably into your applications. For production systems, remember to implement more robust validation, comprehensive logging, sophisticated error handling (including retries where appropriate), and thorough automated testing.

Next Steps:

  • Implement status webhooks from MessageBird to track message delivery asynchronously.
  • Add a database to store message history and status.
  • Build a user interface for sending messages.
  • Explore other MessageBird features like receiving messages or voice capabilities.