Send SMS with Node.js, Express, and MessageBird

This guide provides a step-by-step walkthrough for building a simple Node.js application using the Express framework to send SMS messages via the MessageBird API. We'll cover everything from project setup to sending your first message programmatically.

By the end of this tutorial, you will have a functional Express API endpoint that accepts a recipient phone number and a message body, and uses MessageBird to deliver the SMS. This forms a fundamental building block for applications requiring notifications, alerts, or communication features.

Project Overview and Goals

What We're Building: A minimalist Node.js Express server with a single API endpoint (/send-sms). This endpoint will receive POST requests containing a recipient's phone number and the message text, then use the MessageBird SDK to dispatch the SMS.

Problem Solved: This addresses the need for applications to programmatically send SMS messages — for example, sending order confirmations, appointment reminders, security alerts, or marketing notifications — without manual intervention.

Technologies Used:

• Node.js: A JavaScript runtime environment enabling server-side execution. Chosen for its asynchronous nature, large ecosystem (npm), and suitability for I/O-bound tasks like API interactions.
• Express: A minimal and flexible Node.js web application framework. Chosen for its simplicity in setting up routes and handling HTTP requests, making it ideal for creating APIs quickly.
• MessageBird SDK: The official Node.js library for interacting with the MessageBird API. Chosen for simplifying the process of making API calls to send SMS.
• dotenv: A module to load environment variables from a .env file into process.env. Chosen for securely managing sensitive information like API keys outside of the codebase.

System Architecture:

+-------------+       +---------------------+       +-------------------+       +-----------------+
| User / App  | ----> | Node.js/Express App | ----> | MessageBird SDK   | ----> | MessageBird API | ----> SMS Network
| (makes API  | POST  | (Listens on /send-sms)| Calls | (Handles Auth &   | HTTPS | (Processes      |
|  request)   |       | Validates input     | ----> |  API Interaction) | ----> |  Request, Sends |
+-------------+       +---------------------+       +-------------------+       +-----------------+
                      | Loads API Key from .env |
                      +-------------------------+

Expected Outcome: A running Node.js server that exposes a /send-sms POST endpoint. Sending a valid request to this endpoint triggers an SMS message delivery via MessageBird.

Prerequisites:

• Node.js and npm (or yarn): Installed on your development machine. You can download them from nodejs.org.
• MessageBird Account: A free account is sufficient to get started. Sign up at messagebird.com.
• MessageBird API Key: You'll need an API access key from your MessageBird dashboard. MessageBird provides both live and test API keys.
  • Live Keys: Used for sending actual SMS messages to real phone numbers, potentially incurring costs. Use these for production or real-world testing.
  • Test Keys: Used for development and testing purposes. API calls made with test keys are validated by MessageBird but do not send actual SMS messages and do not incur charges. This is ideal during development to simulate API interactions without sending messages or spending credits.
• MessageBird Originator: Either a purchased Virtual Mobile Number (VMN) from MessageBird or a registered Alphanumeric Sender ID (availability depends on the destination country).
• A Test Recipient Phone Number: A mobile phone number where you can receive the test SMS (when using a live API key).

1. Setting up the Project

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

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

   bash

   mkdir node-messagebird-sms
   cd node-messagebird-sms
   

2. Initialize Node.js Project: This creates a package.json file to manage project dependencies and scripts.

   bash

   npm init -y
   

   (The -y flag accepts default settings.)

3. Install Dependencies: We need Express for the web server, the MessageBird SDK, and dotenv for environment variables.

   bash

   npm install express messagebird dotenv
   

   This command downloads the packages and adds them to your node_modules directory and lists them as dependencies in package.json.

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

   • On Linux/macOS:
     bash

     touch index.js .env
     
   • On Windows (Command Prompt):
     bash

     type nul > index.js
     type nul > .env
     
   • On Windows (PowerShell):
     powershell

     New-Item index.js -ItemType File
     New-Item .env -ItemType File
     

Your basic project structure should now look like this:

node-messagebird-sms/
├── node_modules/
├── .env
├── index.js
├── package-lock.json
└── package.json

Architectural Decision: We are using a single index.js file for simplicity in this basic example. In larger applications, you would typically separate concerns into different files/modules (e.g., routes, controllers, services). Using .env ensures that sensitive credentials like API keys are not hardcoded in the source code, adhering to security best practices.

2. Configuring MessageBird Credentials

Securely storing and accessing your MessageBird API key and originator information is crucial.

1. Obtain Your MessageBird API Key:

   • Log in to your MessageBird Dashboard.
   • Navigate to the ""Developers"" section in the left-hand sidebar.
   • Click on the ""API access"" tab.
   • Here you can find both your live and test API keys.
   • If you don't have keys, click ""Add access key"". You can choose the mode (Live or Test).
   • Copy the appropriate access key (use the test key for initial development, switch to the live key for sending real messages). Treat these keys like passwords — keep them confidential.

2. Obtain Your MessageBird Originator:

   • The originator is the sender ID displayed on the recipient's phone. It can be:
     • A Virtual Mobile Number (VMN): Purchase one in the ""Numbers"" section of the MessageBird Dashboard. This is the most reliable option for two-way communication and delivery to countries like the US.
     • An Alphanumeric Sender ID: A custom name (e.g., ""My App"", max 11 characters). You might need to register this via the Dashboard (""Channels"" > ""SMS"" > ""Sender IDs""). Note that Alphanumeric IDs are not supported in all countries (e.g., the US) and cannot receive replies. Check MessageBird's country restrictions documentation for details.
   • Choose the originator you intend to use. For VMNs, use the full number in E.164 format (e.g., +12025550184).

3. Configure Environment Variables: Open the .env file you created earlier and add your API key (start with the test key) and originator:

   bash

   # .env
   # Start with your TEST key for development
   MESSAGEBIRD_ACCESS_KEY=YOUR_TEST_API_KEY_HERE
   MESSAGEBIRD_ORIGINATOR=YOUR_VMN_OR_ALPHANUMERIC_ID_HERE
   
   • Replace YOUR_TEST_API_KEY_HERE with your actual test (or live) API key.
   • Replace YOUR_VMN_OR_ALPHANUMERIC_ID_HERE with your chosen MessageBird number (e.g., +12025550184) or registered Alphanumeric ID (e.g., MyApp).

4. (Optional but Recommended) Add .env to .gitignore: If you plan to use Git for version control, create a .gitignore file and add .env to it to prevent accidentally committing your credentials.

   • Create the file:
     • Linux/macOS: touch .gitignore
     • Windows CMD: type nul > .gitignore
     • Windows PowerShell: New-Item .gitignore -ItemType File
   • Add the following lines to .gitignore:
     # .gitignore
     node_modules
     .env
     

Purpose of Configuration: Using environment variables via dotenv allows the application to access sensitive credentials without exposing them directly in the code. This enhances security and makes configuration easier across different deployment environments (development, staging, production). Using test keys initially prevents accidental charges and message sending during development.

3. Implementing the SMS Sending Logic

Now, let's write the core logic in index.js to initialize Express, load environment variables, and set up the MessageBird client.

// index.js
'use strict';

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

// 2. Import dependencies
const express = require('express');
const messagebird = require('messagebird'); // Import the main function

// 3. Initialize MessageBird client
const ACCESS_KEY = process.env.MESSAGEBIRD_ACCESS_KEY;
const ORIGINATOR = process.env.MESSAGEBIRD_ORIGINATOR;

if (!ACCESS_KEY || !ORIGINATOR) {
  console.error('Error: MESSAGEBIRD_ACCESS_KEY and MESSAGEBIRD_ORIGINATOR must be set in the .env file.');
  process.exit(1); // Exit if essential config is missing
}

// Initialize the client using the function directly with the key
const mbClient = messagebird(ACCESS_KEY);

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

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

// --- API Endpoint will be added below ---

// Basic root route for testing server is up
app.get('/', (req, res) => {
  res.send('SMS Sending Server is running!');
});

// 6. Start the server
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Using MessageBird Originator: ${ORIGINATOR}`);
  // Determine if using test or live key based on key prefix (common pattern, verify if MessageBird follows this)
  const keyType = ACCESS_KEY.startsWith('test_') ? 'TEST' : 'LIVE';
  console.log(`Using ${keyType} API Key.`);
});

Explanation:

1. require('dotenv').config();: Loads variables from the .env file into process.env. This must be called early.
2. Imports the express framework and the main initialization function from the messagebird SDK.
3. Retrieves the API key and originator from process.env. Includes a check to ensure these critical variables are set, exiting gracefully if not. Initializes the MessageBird client by calling the imported function with the API key (messagebird(ACCESS_KEY)).
4. Creates an Express application instance and defines the port it will listen on.
5. app.use(express.json());: Adds middleware to automatically parse incoming JSON request bodies, making req.body available in our route handlers.
6. Starts the Express server, logging confirmation messages to the console, including the originator and whether a test or live key is likely being used.
7. Includes a simple GET / route to easily check if the server is running via a browser or curl.

4. Building the API Endpoint

Let's create the /send-sms endpoint that will handle POST requests to send messages using modern async/await syntax.

Add the following code inside index.js, just before the app.listen call and after the app.get('/') route:

// index.js (continued)

// --- API Endpoint ---
// Use async function to allow await
app.post('/send-sms', async (req, res) => {
  // 1. Extract recipient and message body from request
  const { recipient, message } = req.body;

  // 2. Basic Input Validation
  // Note: Add more robust validation, especially for the recipient format (E.164)
  if (!recipient || !message) {
    console.warn({ timestamp: new Date().toISOString(), level: 'WARN', message: 'Validation Error: Missing recipient or message.', requestBody: req.body });
    return res.status(400).json({
      status: 'error',
      message: 'Recipient phone number (E.164 format) and message body are required.',
    });
  }

  // 3. Prepare MessageBird parameters
  const params = {
    originator: ORIGINATOR,
    recipients: [recipient], // Must be an array
    body: message,
  };

  console.log(`Attempting to send SMS to ${recipient} from ${ORIGINATOR}`);

  try {
    // 4. Send the message using MessageBird SDK with await
    const response = await mbClient.messages.create(params);

    // 5. Handle successful sending
    // Note: Verify the exact structure of 'response' against current SDK documentation
    console.info({ timestamp: new Date().toISOString(), level: 'INFO', message: 'MessageBird API Success', response: response, requestParams: params });
    res.status(200).json({
      status: 'success',
      message: 'SMS submitted successfully to MessageBird!',
      messageId: response.id, // Include the MessageBird message ID
      recipients: response.recipients.items.map(item => ({
        recipient: item.recipient,
        status: item.status,
        statusDatetime: item.statusDatetime,
      })),
    });

  } catch (err) {
    // 6. Handle MessageBird API errors
    console.error({ timestamp: new Date().toISOString(), level: 'ERROR', message: 'MessageBird API Error', error: err, requestParams: params });

    // Safely extract error description(s)
    let errorDetails = 'Unknown API error';
    if (err.errors && Array.isArray(err.errors)) {
      errorDetails = err.errors.map(e => e.description || 'Unknown error code').join(', ');
    } else if (err.message) {
        errorDetails = err.message;
    }

    // Determine appropriate status code (e.g., 4xx for client errors, 5xx for server errors)
    // MessageBird errors often have status codes, but default to 500 if unsure.
    const statusCode = err.statusCode || 500;

    return res.status(statusCode).json({
      status: 'error',
      message: `Failed to send SMS via MessageBird: ${errorDetails}`,
      // DO NOT include raw error object (`err`) in production responses for security.
      // It's logged above for debugging.
    });
  }
});

// --- End of API Endpoint ---

// 6. Start the server
// ... (app.listen call remains here) ...

Explanation:

1. Endpoint Definition: app.post('/send-sms', async (req, res) => {...}) defines an async route handler for POST requests at /send-sms.
2. Input Extraction & Validation: Extracts recipient and message. Basic validation checks for presence. A comment reminds us to add stricter validation (e.g., E.164 format check for recipient). Returns 400 Bad Request on failure.
3. Parameter Preparation: Creates the params object for the SDK.
4. Sending the Message: Uses a try...catch block for asynchronous operations. await mbClient.messages.create(params) calls the SDK function and pauses execution until the promise resolves or rejects.
5. Success Handling (try block): If the await succeeds, it logs the success and sends a 200 OK response with relevant details from the response object (like message ID and recipient status). A comment notes that the exact response structure should be confirmed in the SDK docs.
6. Error Handling (catch block): If await rejects (an error occurs), the catch(err) block executes. It logs the error details for debugging. It then attempts to parse a user-friendly error message from err.errors (checking it's an array) or falls back to err.message. It determines an appropriate HTTP status code (using err.statusCode if available, otherwise 500). Finally, it sends the formatted error response to the client, omitting the raw err object for security.

5. Error Handling and Logging

The code now includes:

• Configuration Errors: Checks for missing .env variables on startup.
• Input Validation Errors: Returns a 400 Bad Request if recipient or message are missing.
• MessageBird API Errors: Uses try...catch to handle errors from the SDK call. It logs detailed errors server-side and returns a structured, safe error message to the client with an appropriate status code.

Improvements for Production:

• More Specific Validation: Use a library like joi or express-validator for robust validation (e.g., checking E.164 format, message length limits). Add this validation right after extracting req.body.
• Structured Logging: Replace console.log/warn/info/error with a dedicated logging library (like winston or pino) for structured JSON logs, controllable log levels, and outputting to files or services.
• Error Tracking Services: Integrate services like Sentry or Bugsnag to automatically capture and report errors.
• Security Headers: Use middleware like helmet to set various HTTP headers for security.
• Rate Limiting: Implement rate limiting on the endpoint (e.g., using express-rate-limit) to prevent abuse.
• Retry Mechanisms: For transient network errors or specific MessageBird errors (like rate limits), consider implementing a retry strategy with exponential backoff. Be cautious not to cause duplicate messages.

Example of adding E.164 format validation (conceptual):

// Inside /send-sms route, after extracting recipient
const e164Regex = /^\+[1-9]\d{1,14}$/; // Basic E.164 regex
if (!recipient || !message || !e164Regex.test(recipient)) {
  console.warn('Validation Error: Invalid input.', { recipient, message });
  return res.status(400).json({
    status: 'error',
    message: 'Recipient phone number (must be valid E.164 format like +1234567890) and message body are required.',
  });
}

6. Testing the Endpoint

Now, let's run the server and test the endpoint using curl.

1. Run the Application: Open your terminal in the project directory (node-messagebird-sms/) and run:

   bash

   node index.js
   

   You should see the output:

   Server running on http://localhost:3000
   Using MessageBird Originator: YOUR_VMN_OR_ALPHANUMERIC_ID_HERE
   Using TEST API Key. // Or LIVE depending on your .env
   

2. Send a Test SMS using curl: Open another terminal window. Replace +1xxxxxxxxxx with your actual recipient phone number (in E.164 format) and modify the message text if desired.

   bash

   curl -X POST http://localhost:3000/send-sms \
        -H ""Content-Type: application/json"" \
        -d '{
              ""recipient"": ""+1xxxxxxxxxx"",
              ""message"": ""Hello from Node.js and MessageBird! Sent on Jan 10, 2024.""
            }'
   

3. Check the Results:

   • Terminal 1 (Server Logs): You should see log output indicating the attempt and the success or failure response from MessageBird.
     • Success Example (Test Key): You'll see a success log, but no SMS is actually sent.
     • Success Example (Live Key): You'll see a success log, and an SMS should arrive.
       Attempting to send SMS to +1xxxxxxxxxx from YOUR_ORIGINATOR
       {""timestamp"":""..."",""level"":""INFO"",""message"":""MessageBird API Success"", ... }
       
     • Error Example (e.g., invalid recipient):
       Attempting to send SMS to +1invalidnumber from YOUR_ORIGINATOR
       {""timestamp"":""..."",""level"":""ERROR"",""message"":""MessageBird API Error"", ... errors: [ { code: 21, description: 'Invalid recipient.', parameter: 'recipients' } ] ...}
       
   • Terminal 2 (curl Output):
     • Success:
       json

       {
         ""status"": ""success"",
         ""message"": ""SMS submitted successfully to MessageBird!"",
         ""messageId"": ""mb_message_id_string"",
         ""recipients"": [
           {
             ""recipient"": 1xxxxxxxxxx,
             ""status"": ""sent"",
             ""statusDatetime"": ""...""
           }
         ]
       }
       
     • Input Validation Error (missing field or invalid format):
       json

       {
         ""status"": ""error"",
         ""message"": ""Recipient phone number (must be valid E.164 format like +1234567890) and message body are required.""
       }
       
     • MessageBird API Error (e.g., bad key):
     json

     {
       ""status"": ""error"",
       ""message"": ""Failed to send SMS via MessageBird: Authentication failed""
     }
     
   • Recipient Phone: If using a live API key and the call was successful, you should receive the SMS on the specified recipient phone within a few seconds. If using a test key, no SMS will arrive.

7. Troubleshooting and Caveats

• Error: MESSAGEBIRD_ACCESS_KEY... must be set: Ensure your .env file exists in the project root, is correctly named (.env), and contains the MESSAGEBIRD_ACCESS_KEY and MESSAGEBIRD_ORIGINATOR variables with valid values. Restart the Node.js server after editing .env.
• 400 Bad Request Response: Check curl has -H ""Content-Type: application/json"" and the -d payload is valid JSON with recipient (in E.164 format) and message. Check server logs for validation errors.
• 401, 403, or 500 Error with ""Authentication failed"", ""Invalid Signature"", or similar:
  • Your MESSAGEBIRD_ACCESS_KEY in .env is likely incorrect. Verify it in the MessageBird Dashboard.
  • You might be using a test key for an operation that requires a live key, or vice-versa (though often test keys simulate success). Ensure you are using the correct key type for your needs. Double-check the copied key value.
• Error with ""Invalid originator"": The MESSAGEBIRD_ORIGINATOR in .env is likely incorrect, not registered, or not permitted for the destination country (especially Alphanumeric IDs). Check format (E.164 for numbers) and status in the MessageBird Dashboard. See MessageBird's Originator article.
• Error with ""Invalid recipient"" or ""Number not routable"": The recipient number is likely invalid, not in E.164 format (+ country code + number), or for a destination MessageBird cannot reach.
• Error with ""Insufficient balance"": Your MessageBird account needs credits (only applies when using a live key). Add funds via the Dashboard.
• SMS Not Received Despite Success Response (Live Key):
  • Verify the recipient number.
  • Wait a few minutes (carrier delays).
  • Check MessageBird Dashboard logs (""SMS"" > ""SMS Overview"") for detailed delivery status (e.g., carrier rejection).
  • Ensure the phone has signal and isn't blocking unknown senders.
  • Alphanumeric IDs might not be supported by the destination carrier (e.g., US/Canada often require local numbers). Try a VMN.
• Rate Limiting: High volume sending might hit MessageBird rate limits. Implement queuing and backoff strategies.
• SDK Response Structure: The exact structure of the success (response) and error (err) objects from mbClient.messages.create should always be verified against the current official MessageBird Node.js SDK documentation, as it can change over time.

8. Running the Application

To run the application, navigate to the project directory in your terminal and execute:

node index.js

The server will start and remain running until you stop it (usually with Ctrl + C).

Conclusion and Next Steps

Congratulations! You have successfully built a basic Node.js Express application capable of sending SMS messages using the MessageBird API and modern JavaScript practices. You learned how to set up a project, manage API keys (test vs. live), create an API endpoint using async/await, interact with the MessageBird SDK, and handle errors securely.

Next Steps & Potential Improvements:

• Robust Input Validation: Implement stricter validation (E.164 format, message length) using libraries like joi or express-validator.
• User Interface: Build a front-end to interact with your API.
• Asynchronous Processing: Use a message queue (e.g., RabbitMQ, Redis/BullMQ) for high-volume sending to improve responsiveness and manage retries.
• Database Integration: Store message logs or application data.
• Advanced MessageBird Features: Explore receiving messages (webhooks), delivery status checking, templates, MMS.
• Enhanced Security: Add API authentication, rate limiting (express-rate-limit), security headers (helmet).
• Deployment: Deploy to a hosting provider (Heroku, AWS, etc.) using Docker and CI/CD.
• Monitoring & Alerting: Integrate monitoring (Prometheus/Grafana, Datadog) for performance and error tracking.

Code Repository

[Actual repository link should be inserted here if available]

This foundation enables you to integrate powerful SMS capabilities into your Node.js applications. Happy coding!