Build a High-Throughput SMS Broadcaster with Node.js, Express, and MessageBird

Sending SMS messages one by one is simple, but broadcasting messages to thousands or even millions of users requires a more robust approach. Trying to send numerous messages sequentially or naively in parallel can quickly overwhelm your server resources, lead to significant delays, and potentially get your application rate-limited by the SMS provider.

This guide provides a complete, step-by-step tutorial for building a production-ready bulk SMS sending service using Node.js, Express, and the MessageBird API. We'll focus on creating a scalable solution that efficiently handles large volumes of messages while minimizing server load and respecting API rate limits. By the end, you'll have a functional Express API endpoint capable of initiating bulk SMS campaigns.

Project Goal: To create a Node.js/Express application with an API endpoint that accepts a list of recipient phone numbers and a message body, then efficiently sends the message to all recipients using the MessageBird API via controlled batching and concurrency.

Technologies Used:

Node.js: A JavaScript runtime built on Chrome's V8 engine, ideal for building efficient, scalable network applications.
Express: A minimal and flexible Node.js web application framework providing a robust set of features for web and mobile applications.
MessageBird: A communication Platform as a Service (CPaaS) offering a reliable SMS API with global reach. We'll use their Node.js SDK.
dotenv: A zero-dependency module that loads environment variables from a .env file into process.env.
express-validator: Middleware for Express providing validation and sanitization functions.
express-rate-limit: Middleware for Express to limit repeated requests to public APIs and/or endpoints.

System Architecture:

graph LR
    Client[Client Application] -- POST /api/v1/bulk-sms --> ExpressAPI[Node.js/Express API]
    ExpressAPI -- Validate & Sanitize --> ExpressAPI
    ExpressAPI -- Batch Recipients & Prepare --> BulkSendService[Bulk Sending Service]
    BulkSendService -- Send Batch via SDK --> MessageBird[MessageBird API]
    MessageBird -- SMS --> UserA[Recipient 1]
    MessageBird -- SMS --> UserB[Recipient 2]
    MessageBird -- SMS --> UserN[Recipient N]
    MessageBird -- Response/Status --> BulkSendService
    BulkSendService -- Log Results --> Logging[Logging System]
    BulkSendService -- Overall Status --> ExpressAPI
    ExpressAPI -- JSON Response --> Client

Prerequisites:

Node.js and npm (or yarn) installed.
A MessageBird account (Sign up here).
Your MessageBird Live API Access Key.
Basic understanding of JavaScript, Node.js, and REST APIs.

1. Setting up the Project

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

Create Project Directory: Open your terminal and create a new directory for the project, then navigate into it.
```
mkdir node-messagebird-bulk-sms
cd node-messagebird-bulk-sms
```
Initialize Node.js Project: Initialize the project using npm. The -y flag accepts the default settings.
```
npm init -y
```
Install Dependencies: Install Express for the web server, the MessageBird SDK, dotenv for environment variables, express-validator for input validation, and express-rate-limit for basic security.
```
npm install express messagebird dotenv express-validator express-rate-limit
```
Install Development Dependencies (Optional but Recommended): Install nodemon to automatically restart the server during development.
```
npm install -D nodemon
```

Configure package.json Scripts: Open your package.json file and add a start and dev script to the scripts section. Note: Dependency versions below are examples; use npm install <package> to get the latest stable versions or manage versions according to your project's needs.

{
  "name": "node-messagebird-bulk-sms",
  "version": "1.0.0",
  "description": "",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "dotenv": "^16.0.0",
    "express": "^4.0.0",
    "express-rate-limit": "^7.0.0",
    "express-validator": "^7.0.0",
    "messagebird": "^4.0.0"
  },
  "devDependencies": {
    "nodemon": "^3.0.0"
  }
}

Create Project Structure: Set up a basic structure to organize our code:
```
mkdir src
mkdir src/routes
mkdir src/services
mkdir src/middleware
touch src/index.js
touch src/routes/messagingRoutes.js
touch src/services/messagingService.js
touch src/middleware/validationRules.js
touch .env
touch .gitignore
```
- src/index.js: Main application entry point.
- src/routes/: Contains route definitions.
- src/services/: Contains business logic (like sending SMS).
- src/middleware/: Contains Express middleware (like validation).
- .env: Stores environment variables (like API keys). Never commit this file.
- .gitignore: Specifies files/directories Git should ignore.
Configure .gitignore: Add node_modules and .env to your .gitignore file to prevent committing them:
```
# .gitignore
node_modules
.env
*.log
```
Set up Environment Variables (.env): Open the .env file and add your MessageBird API key.

How to get your MessageBird API Key:
1. Log in to your MessageBird Dashboard.
2. Navigate to the "Developers" section in the left-hand sidebar.
3. Click on "API access".
4. If you haven't created a key yet, click "Add access key". Choose "Live key".
5. Copy the generated Live access key. Treat this key like a password – keep it secret!
```
# .env

# MessageBird Credentials
MESSAGEBIRD_ACCESS_KEY=YOUR_LIVE_ACCESS_KEY_HERE

# Application Settings
PORT=3000
MESSAGEBIRD_ORIGINATOR=YourSenderID # Important: You *must* replace YourSenderID with your registered phone number (E.164 format) or alphanumeric sender ID
```
- MESSAGEBIRD_ACCESS_KEY: Your secret live API key from the MessageBird dashboard.
- PORT: The port your Express application will listen on.
- MESSAGEBIRD_ORIGINATOR: Important: The sender ID recipients will see. This must be replaced with a purchased MessageBird number (in E.164 format, e.g., +12025550187) or a registered alphanumeric sender ID (max 11 chars, limited country support). Using an unregistered number or invalid ID will cause errors. Check MessageBird's documentation for originator requirements in your target countries.

Basic Express Server Setup (src/index.js): Set up a minimal Express server that loads environment variables.

// src/index.js
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const messagingRoutes = require('./routes/messagingRoutes');

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(express.json()); // Enable parsing JSON request bodies

// Routes
app.use('/api/v1/messaging', messagingRoutes); // Mount messaging routes

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

// Basic Error Handling Middleware (Example)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ message: 'Something went wrong!', error: err.message });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  if (!process.env.MESSAGEBIRD_ACCESS_KEY) {
    console.warn('WARNING: MESSAGEBIRD_ACCESS_KEY environment variable is not set.');
  }
  if (!process.env.MESSAGEBIRD_ORIGINATOR || process.env.MESSAGEBIRD_ORIGINATOR === 'YourSenderID') {
    console.warn('WARNING: MESSAGEBIRD_ORIGINATOR environment variable is not set or is still the default placeholder.');
  }
});

We load dotenv first.
We initialize Express and set up JSON middleware.
We define a placeholder for our messaging routes.
A simple /health endpoint is included for monitoring.
Basic error handling and startup logs (including warnings if essential env vars are missing or defaults) are added.

2. Implementing Core Functionality: The Bulk Sending Service

This service will contain the logic for initializing the MessageBird client and handling the batch sending process.

// src/services/messagingService.js
const { initClient } = require('messagebird');

// Initialize MessageBird client (only once)
let messagebird;
try {
  if (!process.env.MESSAGEBIRD_ACCESS_KEY) {
    throw new Error('MESSAGEBIRD_ACCESS_KEY environment variable is missing.');
  }
  messagebird = initClient(process.env.MESSAGEBIRD_ACCESS_KEY);
  console.log('MessageBird client initialized successfully.');
} catch (error) {
  console.error('Failed to initialize MessageBird client:', error);
  // You might want to prevent the application from starting or gracefully degrade
  // For this example, we'll let it proceed but log the error.
  messagebird = null; // Ensure it's null if initialization fails
}

// --- Tuning Parameters ---
// These values are starting points. You MUST tune them based on:
// 1. Testing and observed performance.
// 2. Your server's available resources (CPU, memory, network bandwidth).
// 3. Your specific MessageBird account's rate limits (these can vary).
// Start lower and gradually increase BATCH_SIZE while monitoring for errors.
const BATCH_SIZE = 50; // Number of messages to send concurrently in one batch
const DELAY_BETWEEN_BATCHES = 1000; // Delay in milliseconds (1 second) between batches
// --- End Tuning Parameters ---

/**
 * Sends SMS messages in batches to avoid overloading and hitting rate limits.
 * @param {string[]} recipients - Array of phone numbers in E.164 format.
 * @param {string} messageBody - The text message content.
 * @returns {Promise<{success: Array, errors: Array}>} - Object containing arrays of successful and failed sends.
 */
async function sendBulkSms(recipients, messageBody) {
  if (!messagebird) {
     throw new Error('MessageBird client is not initialized. Check API Key.');
  }
  if (!recipients || recipients.length === 0) {
    throw new Error('Recipient list cannot be empty.');
  }
  if (!messageBody) {
    throw new Error('Message body cannot be empty.');
  }
  const originator = process.env.MESSAGEBIRD_ORIGINATOR;
  if (!originator || originator === 'YourSenderID') {
      throw new Error('MESSAGEBIRD_ORIGINATOR environment variable is not set correctly.');
  }

  console.log(`Starting bulk SMS send to ${recipients.length} recipients.`);

  const results = { success: [], errors: [] };

  for (let i = 0; i < recipients.length; i += BATCH_SIZE) {
    const batchRecipients = recipients.slice(i, i + BATCH_SIZE);
    console.log(`Processing batch ${Math.floor(i / BATCH_SIZE) + 1}/${Math.ceil(recipients.length / BATCH_SIZE)}: ${batchRecipients.length} recipients.`);

    const promises = batchRecipients.map(recipient => {
      const params = {
        originator: originator,
        recipients: [recipient], // Send to one recipient per API call for granular tracking
        body: messageBody,
        // reference: `my_campaign_${Date.now()}_${recipient}` // Optional: Add a reference for tracking
      };

      return new Promise((resolve) => {
        messagebird.messages.create(params, (err, response) => {
          if (err) {
            // Log detailed error including recipient
            console.error(`Error sending to ${recipient}:`, err.errors || err.message || err);
            resolve({ recipient, status: 'error', details: err.errors || err });
          } else {
            // Log basic success info
            // console.log(`Successfully sent message request for ${recipient}. ID: ${response.id}`);
            resolve({ recipient, status: 'success', messageId: response.id, response });
          }
        });
      });
    });

    // Execute the batch concurrently
    const batchResults = await Promise.all(promises);

    // Process results for this batch
    batchResults.forEach(result => {
      if (result.status === 'success') {
        results.success.push(result);
      } else {
        results.errors.push(result);
      }
    });

    // Optional delay between batches to respect rate limits
    if (i + BATCH_SIZE < recipients.length) {
      console.log(`Waiting ${DELAY_BETWEEN_BATCHES}ms before next batch...`);
      await new Promise(resolve => setTimeout(resolve, DELAY_BETWEEN_BATCHES));
    }
  }

  console.log(`Bulk SMS process finished. Success: ${results.success.length}, Errors: ${results.errors.length}`);
  return results;
}

module.exports = {
  sendBulkSms,
};

Explanation:

Initialization: We initialize the messagebird client using the API key from .env. Error handling is included in case the key is missing.
Tuning Parameters: BATCH_SIZE defines how many API calls we make concurrently via Promise.all. DELAY_BETWEEN_BATCHES adds a pause to prevent hitting potential rate limits. Crucially, these are starting points and must be tuned based on testing, server resources, and your specific MessageBird account limits.
sendBulkSms Function:
- Takes an array of recipients and the messageBody.
- Performs basic input validation, including checking if the originator is set correctly.
- Iterates through the recipients in chunks defined by BATCH_SIZE.
- Crucially: Inside the loop, it maps each recipient in the current batch to a Promise that calls messagebird.messages.create. We send one recipient per API call here. While messages.create can accept multiple recipients in its recipients array, sending individually gives more granular error feedback and status tracking per recipient directly from the API response.
- Promise.all executes all API calls for the current batch concurrently, significantly speeding up the process compared to sending sequentially.
- The results (success or error) for each recipient are collected.
- An optional setTimeout introduces a delay before processing the next batch.
- Returns an object summarizing successful and failed attempts.

3. Building the API Layer

Now, let's create the Express route handler that will receive requests and trigger the bulk sending service.

Define Validation Rules (src/middleware/validationRules.js): Use express-validator to ensure incoming requests have the correct format.

// src/middleware/validationRules.js
const { body, validationResult } = require('express-validator');

const validateBulkSmsRequest = [
  // Validate recipients: must be an array, not empty, and contain strings (basic check)
  body('recipients')
    .isArray({ min: 1 }).withMessage('Recipients must be a non-empty array.')
    .custom((recipients) => recipients.every(item => typeof item === 'string' && item.length > 5)) // Basic format check
    .withMessage('Recipients array must contain valid phone number strings (E.164 format recommended).'),

  // Validate message: must be a non-empty string
  body('message')
    .isString().withMessage('Message must be a string.')
    .notEmpty().withMessage('Message cannot be empty.')
    .isLength({ max: 1600 }).withMessage('Message exceeds maximum length (consider SMS limits).'), // Generous limit, real SMS limits apply per segment

  // Middleware to handle validation results
  (req, res, next) => {
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }
    next();
  },
];

module.exports = {
  validateBulkSmsRequest,
};

We define rules for recipients (must be a non-empty array of strings) and message (must be a non-empty string). A basic check for phone number format is included, but robust E.164 validation might require a dedicated library if strictness is needed.
A final middleware function checks for validation errors and returns a 400 response if any exist.

Create Messaging Routes (src/routes/messagingRoutes.js): Define the POST /bulk-sms endpoint.

// src/routes/messagingRoutes.js
const express = require('express');
const rateLimit = require('express-rate-limit');
const { sendBulkSms } = require('../services/messagingService');
const { validateBulkSmsRequest } = require('../middleware/validationRules');

const router = express.Router();

// Apply rate limiting to the bulk endpoint
const bulkSmsLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 5, // Limit each IP to 5 bulk send requests per windowMs (adjust as needed)
    message: 'Too many bulk SMS requests created from this IP, please try again after 15 minutes',
    standardHeaders: true, // Return rate limit info in the `RateLimit-*` headers
    legacyHeaders: false, // Disable the `X-RateLimit-*` headers
});

// POST /api/v1/messaging/bulk-sms
router.post('/bulk-sms', bulkSmsLimiter, validateBulkSmsRequest, async (req, res, next) => {
  try {
    const { recipients, message } = req.body;

    // Basic Sanitization (Example: Trim whitespace)
    const cleanRecipients = recipients.map(r => r.trim()).filter(r => r); // Remove empty strings after trimming
    const cleanMessage = message.trim();

    if (cleanRecipients.length === 0) {
         return res.status(400).json({ message: 'Recipient list cannot be empty after cleaning.' });
    }

    console.log(`Received bulk SMS request for ${cleanRecipients.length} recipients.`);

    // --- Background Processing Approach ---
    // The following 'fire-and-forget' approach acknowledges the request quickly
    // but lacks robustness. If the server crashes mid-process, the job is lost.
    // **For production systems, especially with large volumes, replace this
    // with a persistent background job queue (e.g., BullMQ, Kue).**
    // A job queue provides retries, persistence, and better scalability.
    sendBulkSms(cleanRecipients, cleanMessage)
      .then(results => {
        // Log final results when done (could also be sent via webhook, websocket, database update, etc.)
        console.log('Background Bulk SMS Job Completed:', {
          totalRequested: cleanRecipients.length,
          successCount: results.success.length,
          errorCount: results.errors.length,
          // errors: results.errors // Optionally include detailed errors in logs for debugging
        });
      })
      .catch(error => {
        // Log errors occurring during the bulk send process itself (e.g., service unavailable)
        console.error('Error during background bulk SMS processing:', error);
        // Consider adding more robust error reporting here (e.g., to an error tracking service)
      });

    // Respond immediately that the job has been accepted for processing
    res.status(202).json({
      message: `Bulk SMS request accepted for ${cleanRecipients.length} recipients. Processing initiated in background.`,
      // In a job queue system, you would return a job ID here for status tracking.
    });

  } catch (error) {
    // Catch synchronous errors (e.g., validation, service initialization errors before async call)
    console.error('Error processing bulk SMS request:', error);
    // Pass to the generic error handler in index.js
    next(error);
  }
});

module.exports = router;

Rate Limiting: We apply express-rate-limit to prevent abuse. Adjust windowMs and max based on expected usage and security needs.
Validation: The validateBulkSmsRequest middleware ensures data format correctness.
Asynchronous Execution & Background Processing: The handler validates, sanitizes, and then calls sendBulkSms without await. It immediately returns 202 Accepted. This prevents client timeouts. The actual sending happens asynchronously.
Production Caveat: The current fire-and-forget method is simple but not robust. A persistent job queue (like BullMQ) is strongly recommended for production to handle failures, retries, and ensure jobs aren't lost if the server restarts.
Error Handling: Synchronous errors are caught and passed to the central handler. Asynchronous errors within sendBulkSms are logged in its .catch() block.

4. Integrating with MessageBird (Recap & Details)

Integration primarily involves:

API Key Setup: Securely storing your MESSAGEBIRD_ACCESS_KEY in the .env file and loading it using dotenv. Ensure .env is in your .gitignore.
SDK Initialization: Using require('messagebird').initClient(process.env.MESSAGEBIRD_ACCESS_KEY) in messagingService.js to create the client instance. Handle potential initialization errors.
Originator Configuration: Setting MESSAGEBIRD_ORIGINATOR in .env to a valid, purchased MessageBird number or registered alphanumeric sender ID. Using an invalid originator is a common source of errors.
- Where to find/buy numbers: MessageBird Dashboard -> Numbers -> Buy a number.
- Where to register Alphanumeric Sender IDs: MessageBird Dashboard -> SMS -> Alphanumeric Sender IDs (availability varies by country).

Dashboard Navigation for API Key:

Log in: dashboard.messagebird.com
Sidebar: Click ""Developers""
Sub-menu: Click ""API access""
Copy your ""Live access key"".

Environment Variables Summary:

MESSAGEBIRD_ACCESS_KEY:
- Purpose: Authenticates your application with the MessageBird API.
- Format: A long alphanumeric string (e.g., live_xxxxxxxxxxxxxxxxxxxxxxxxx).
- How to Obtain: MessageBird Dashboard -> Developers -> API access.
MESSAGEBIRD_ORIGINATOR:
- Purpose: The sender ID displayed to the recipient. Must be set correctly.
- Format: E.164 phone number (e.g., +12025550187) OR registered alphanumeric string (e.g., MyCompany, max 11 chars).
- How to Obtain: Purchase a number or register an ID in the MessageBird Dashboard (Numbers or SMS sections). Must comply with country regulations.
PORT:
- Purpose: The network port the Express server listens on.
- Format: A valid port number (e.g., 3000, 8080).
- How to Obtain: Choose an available port on your server.

5. Implementing Error Handling, Logging, and Retries

Error Handling Strategy:
- Validation Errors: Handled by express-validator middleware (400 Bad Request).
- API Errors (MessageBird): Caught within the Promise in messagingService.js, logged, and collected in results.errors.
- Service/Configuration Errors: Checked during initialization or before sending (e.g., missing API key, invalid originator), throwing standard Error objects caught by route handler or global error handler.
- Unhandled/Unexpected Errors: Caught by the basic middleware in index.js (500 Internal Server Error). Use robust error tracking (e.g., Sentry) in production.
Logging:
- Currently uses console.log/console.error.
- Recommendation: Use a structured logging library (e.g., Winston, Pino) for production. Log levels, JSON format, and configurable outputs (file, console, external services) are essential.
- Key Log Points: Server start/config issues, MessageBird client init, incoming requests, batch processing details, individual send success/errors (with details!), delays, final job summary, caught exceptions.

Retry Mechanisms:

The current code doesn't automatically retry failed API calls.
Strategy: Implement retries selectively within the Promise wrapper in messagingService.js. Only retry on transient errors (e.g., network timeouts, temporary MessageBird issues like 5xx errors if documented as retryable).
Implementation: Use a library like async-retry or implement manual exponential backoff.
Caution: Do not retry non-recoverable errors (e.g., invalid recipient 21, invalid originator 10, insufficient balance 9). Check MessageBird error codes.

// Example Pseudocode for Retry Logic (using async-retry)
// In messagingService.js, inside the promises.map(...) callback:

// Note: If implementing this, install the library: npm install async-retry
// const retry = require('async-retry');

// return retry(async (bail, attemptNumber) => { // bail is a function to stop retrying
//   return new Promise((resolve, reject) => { // Use reject here for retry logic
//     messagebird.messages.create(params, (err, response) => {
//       if (err) {
//         console.error(`Attempt ${attemptNumber} failed for ${recipient}:`, err.errors || err);
//         // --- Retry Decision Logic ---
//         // Define which errors are transient/retryable based on MessageBird docs or testing
//         const isRetryable = checkIfErrorIsRetryable(err); // Implement this function
//
//         if (isRetryable) {
//           return reject(err); // Throw error to trigger retry by async-retry
//         } else {
//           // Non-retryable error, stop retrying immediately
//           bail(new Error('Non-retryable MessageBird error encountered'));
//           // Resolve with error status for the final results array (don't lose the error info)
//           resolve({ recipient, status: 'error', details: err.errors || err });
//         }
//       } else {
//         // Success
//         resolve({ recipient, status: 'success', messageId: response.id, response });
//       }
//     });
//   });
// }, {
//   retries: 3,        // Number of retry attempts (besides the initial one)
//   factor: 2,         // Exponential backoff factor (delay = minTimeout * factor^(attempt-1))
//   minTimeout: 500,   // Initial delay in ms
//   maxTimeout: 5000,  // Maximum delay in ms
//   onRetry: (error, attempt) => {
//       console.warn(`Retrying send to ${recipient} (Attempt ${attempt}/${3+1}): ${error.message}`);
//   }
// }).catch(finalError => {
//     // This catch block runs if all retries failed for a retryable error
//     console.error(`All retries failed for ${recipient}:`, finalError);
//     // Return final error state so it's included in the overall job results
//     return { recipient, status: 'error', details: finalError.errors || finalError };
// });

// function checkIfErrorIsRetryable(err) {
//   // Example: Check for specific error codes or types indicative of temporary issues
//   // Consult MessageBird documentation for error codes.
//   // e.g., if (err.statusCode >= 500) return true; // Maybe retry server errors
//   // e.g., if (err.errors && err.errors.some(e => e.code === SOME_RETRYABLE_CODE)) return true;
//   return false; // Default to not retryable
// }

6. Creating a Database Schema and Data Layer (Conceptual)

For real applications, recipients should be managed in a database, not passed in the request body.

Conceptual Schema (Example: PostgreSQL/MySQL):

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY, -- Or INT AUTO_INCREMENT for MySQL
    phone_number VARCHAR(20) NOT NULL UNIQUE, -- Store validated E.164 format
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    is_subscribed BOOLEAN DEFAULT TRUE NOT NULL, -- Crucial for opt-out management
    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP, -- Or DATETIME for MySQL
    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);

-- Index for efficient lookup by phone number
CREATE INDEX idx_users_phone_number ON users(phone_number);
-- Index for querying subscribed users
CREATE INDEX idx_users_is_subscribed ON users(is_subscribed);

-- Optional: Table to track campaigns and message status per user
CREATE TABLE sms_campaign_messages (
    id BIGSERIAL PRIMARY KEY,
    campaign_id VARCHAR(50) NOT NULL, -- Identifier for the bulk send job
    user_id BIGINT REFERENCES users(id),
    messagebird_id VARCHAR(50) UNIQUE, -- MessageBird message ID
    status VARCHAR(20) DEFAULT 'pending', -- e.g., pending, sent, delivered, failed
    status_reason TEXT, -- Store error details if failed
    sent_at TIMESTAMPTZ,
    status_updated_at TIMESTAMPTZ
);
CREATE INDEX idx_sms_campaign_messages_campaign_id ON sms_campaign_messages(campaign_id);
CREATE INDEX idx_sms_campaign_messages_user_id ON sms_campaign_messages(user_id);
CREATE INDEX idx_sms_campaign_messages_status ON sms_campaign_messages(status);

Data Access:
- Use an ORM (Sequelize, Prisma, TypeORM) or query builder (Knex.js) to interact with the database.
- Modify the API endpoint: Instead of recipients, accept criteria (e.g., {""target"": ""all_subscribed""} or {""targetGroup"": ""group_id""}).
- The messagingService (or a dedicated data service) would query the users table based on criteria (e.g., WHERE is_subscribed = TRUE) to get the list of phone_numbers.
- Important: Fetch recipients in manageable chunks from the database for very large lists to avoid high memory usage. Process these chunks sequentially or feed them into the batch sender.
Migrations: Use tools like npx prisma migrate dev or npx sequelize-cli db:migrate to manage schema evolution safely.
Performance: Ensure proper indexing on queried columns (phone_number, is_subscribed).

7. Adding Security Features

API Key Security: Handled via .env and .gitignore. Emphasize: Never commit API keys or expose them client-side. Use secret management tools in production (AWS Secrets Manager, HashiCorp Vault, etc.).
Input Validation: Implemented via express-validator. This mitigates risks like NoSQL injection (if applicable) and malformed data causing errors. Always sanitize inputs (trimming, potentially stricter rules).
Rate Limiting: Basic IP-based limiting via express-rate-limit is implemented. For robust protection:
- Consider user/API key-based rate limiting if authenticated.
- Implement more sophisticated limits (e.g., tiered limits based on user plan).
Authentication/Authorization: The current endpoint is public. In production, this is usually unacceptable.
- Protect the endpoint. Common methods:
  - Require a static API key in a header (X-API-Key: your-secret-key). Validate it server-side.
  - Use standard authentication like OAuth 2.0 or JWT if the API is part of a larger user-facing system.
- Ensure only authorized systems or users can trigger potentially costly bulk SMS sends.
Originator Security: Ensure MESSAGEBIRD_ORIGINATOR is always read from secure configuration (process.env) and cannot be influenced by request parameters.
Denial of Service (DoS): Rate limiting helps. Also consider:
- Limiting the maximum number of recipients allowed per single request.
- Infrastructure-level protection (WAF, Cloudflare, etc.).

8. Handling Special Cases

Recipient Formatting: MessageBird strictly

10DLC Registration: SMS Campaign Approval and Compliance Guide