Build a Node.js Express App for Bulk SMS with Sinch - code-examples -

Build a Node.js Express App for Bulk SMS Broadcasts with Sinch

This guide provides a step-by-step walkthrough for building a robust Node.js application using the Express framework to send bulk SMS messages via the Sinch REST API. We'll cover everything from project setup and core logic to error handling, security, and deployment considerations.

By the end of this tutorial, you will have a functional backend service capable of accepting a list of phone numbers and a message, then broadcasting that message efficiently using Sinch's batch sending capabilities. This solves the common need for applications to send notifications, alerts, or marketing messages to multiple users simultaneously.

Project Overview and Goals

What We're Building:

A Node.js Express API endpoint that:

Accepts a POST request containing a list of recipient phone numbers and a message body.
Validates the input.
Uses the Sinch SMS REST API (/batches endpoint) to send the message to all recipients in a single API call (a bulk broadcast).
Handles potential errors gracefully.
Provides basic logging.

Problem Solved:

Manually sending SMS messages one by one is inefficient and doesn't scale. This application provides a programmatic way to broadcast messages to large groups, leveraging Sinch's infrastructure for reliable delivery.

Technologies Used:

Node.js: A JavaScript runtime environment ideal for building scalable network applications.
Express.js: A minimal and flexible Node.js web application framework providing robust features for web and mobile applications.
Sinch SMS REST API: The interface used to programmatically send SMS messages via Sinch. We'll use the /batches endpoint for efficient bulk sending.
Axios: A promise-based HTTP client for making requests to the Sinch API.
dotenv: A module to load environment variables from a .env file, keeping sensitive credentials out of the codebase.

System Architecture:

The basic flow is as follows:

A Client Application sends a POST request to /api/broadcast on the Node.js Express App.
The Express App validates the incoming request data.
The App prepares the batch payload for the Sinch API.
The App sends a POST request to the Sinch SMS API's /v1/batches endpoint.
Sinch processes the batch and sends SMS messages to the Recipients' Phones.
Sinch returns a Batch ID and status information to the Express App.
The Express App sends an API response (indicating success or error) back to the Client Application.

Prerequisites:

Node.js and npm (or yarn): Installed on your development machine. (Download Node.js)
Sinch Account: A registered account with Sinch. (Sign up for Sinch)
Sinch API Credentials:
- SERVICE_PLAN_ID: Found on your Sinch Customer Dashboard under SMS > APIs.
- API_TOKEN: Also found on the same page (click ""Show"" to reveal it).
- SINCH_NUMBER: A virtual number associated with your Service Plan ID, capable of sending SMS. Find this by clicking your Service Plan ID link on the dashboard.
Basic understanding of: JavaScript, Node.js, Express, REST APIs, and terminal commands.
Code Editor: Like VS Code, Sublime Text, etc.
Testing Tool (Optional but Recommended): Postman or curl for testing the API endpoint.

Expected Outcome:

A running Node.js service with an API endpoint (/api/broadcast) that accepts recipient lists and messages, sending them out via Sinch.

1. Setting up the Project

Let's initialize our Node.js project, install dependencies, and set up the basic structure and environment configuration.

Create Project Directory: Open your terminal or command prompt and create a new directory for the project.
```
mkdir sinch-bulk-sms-app
cd sinch-bulk-sms-app
```
Initialize Node.js Project: This creates a package.json file to manage project details and dependencies.
```
npm init -y
```
(The -y flag accepts default settings)
Install Dependencies: We need Express for the web server, Axios for API calls, and dotenv for environment variables.
```
npm install express axios dotenv
```

Create Project Structure: A good structure helps maintainability. Create the following directories and files:

sinch-bulk-sms-app/
├── src/
│   ├── controllers/
│   │   └── broadcastController.js
│   ├── routes/
│   │   └── broadcastRoutes.js
│   ├── services/
│   │   └── sinchService.js
│   └── app.js
├── .env             # For environment variables (will create soon)
├── .gitignore       # To exclude files from Git (will create soon)
└── package.json

Create .gitignore: Prevent sensitive files and unnecessary directories from being committed to version control. Create a file named .gitignore in the root directory:
```
# .gitignore

# Dependencies
node_modules/

# Environment Variables
.env

# Logs
*.log

# Build output
dist/
```
Configure Environment Variables: Create a file named .env in the root directory. This file will hold your sensitive Sinch credentials and configuration. Never commit this file to Git.
- Find Your Credentials: Log in to your Sinch Customer Dashboard. Navigate to SMS > APIs. Note your Service plan ID and API token. Also, find a virtual Sinch Number associated with this plan.
- Determine Region: Check the base URL provided in the Sinch dashboard. It will indicate your region (e.g., us.sms.api.sinch.com, eu.sms.api.sinch.com).
Populate the .env file:
```
# .env

# Sinch API Credentials
SINCH_SERVICE_PLAN_ID=YOUR_SERVICE_PLAN_ID_HERE
SINCH_API_TOKEN=YOUR_API_TOKEN_HERE
SINCH_NUMBER=YOUR_SINCH_VIRTUAL_NUMBER_HERE # e.g., +12025550147

# Sinch API Base URL (Adjust region if needed: us, eu, au, ca, br)
SINCH_BASE_URL=https://us.sms.api.sinch.com

# Application Port
PORT=3000
```
- SINCH_SERVICE_PLAN_ID: Your unique service plan identifier from the Sinch dashboard.
- SINCH_API_TOKEN: The secret token used to authenticate API requests. Treat this like a password.
- SINCH_NUMBER: The Sinch virtual phone number that messages will be sent from. Must be in E.164 format (e.g., +1xxxxxxxxxx).
- SINCH_BASE_URL: The base URL for the Sinch REST API corresponding to your account's region. Ensure this matches your dashboard.
- PORT: The port your Express application will listen on.

Set up Basic Express Server (src/app.js): This file initializes Express, loads environment variables, sets up middleware, and defines the entry point for our routes.

// src/app.js
import express from 'express';
import dotenv from 'dotenv';
import broadcastRoutes from './routes/broadcastRoutes.js';

// Load environment variables from .env file
dotenv.config();

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

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

// Basic logging middleware (optional but helpful)
app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
});

// Mount Routes
app.use('/api', broadcastRoutes); // Mount broadcast routes under /api prefix

// Basic Error Handler Middleware (simple example)
app.use((err, req, res, next) => {
    console.error('Global Error Handler:', err.stack);
    res.status(err.status || 500).json({
        error: {
            message: err.message || 'Something went wrong!',
            // Optionally include stack trace in development
            stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
        }
    });
});

// Start the server
app.listen(port, () => {
    console.log(`Server running on http://localhost:${port}`);
    // Verify essential env vars are loaded (optional startup check)
    if (!process.env.SINCH_SERVICE_PLAN_ID || !process.env.SINCH_API_TOKEN || !process.env.SINCH_NUMBER) {
         console.warn('WARN: Missing one or more required Sinch environment variables (ID, TOKEN, NUMBER). API calls may fail.');
    }
});

// Add this line to handle ES module syntax for top-level await or other features if needed later
export default app;

Module Type: Add ""type"": ""module"" to your package.json file to enable ES module syntax (import/export).

// package.json snippet
{
  ""name"": ""sinch-bulk-sms-app"",
  ""version"": ""1.0.0"",
  ""description"": """",
  ""main"": ""src/app.js"",
  ""type"": ""module"",
  ""scripts"": {
    ""start"": ""node src/app.js"",
    ""dev"": ""nodemon src/app.js""
  }
}

2. Implementing Core Functionality (Sinch Service)

Now, let's create the service responsible for interacting with the Sinch API.

Create Sinch Service (src/services/sinchService.js): This module encapsulates the logic for sending the bulk SMS batch request.

// src/services/sinchService.js
import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config(); // Ensure environment variables are loaded

const SERVICE_PLAN_ID = process.env.SINCH_SERVICE_PLAN_ID;
const API_TOKEN = process.env.SINCH_API_TOKEN;
const SINCH_NUMBER = process.env.SINCH_NUMBER;
const BASE_URL = process.env.SINCH_BASE_URL;

/**
 * Sends a bulk SMS message using the Sinch REST API /batches endpoint.
 * @param {string[]} recipients - An array of recipient phone numbers in E.164 format.
 * @param {string} messageBody - The text message content.
 * @returns {Promise<object>} - The response data from the Sinch API.
 * @throws {Error} - Throws an error if the API call fails or prerequisites are missing.
 */
const sendBulkSms = async (recipients, messageBody) => {
    if (!SERVICE_PLAN_ID || !API_TOKEN || !SINCH_NUMBER || !BASE_URL) {
        throw new Error('Missing Sinch configuration. Check .env file.');
    }

    if (!recipients || !Array.isArray(recipients) || recipients.length === 0) {
        throw new Error('Recipients array cannot be empty.');
    }
     if (!messageBody || typeof messageBody !== 'string' || messageBody.trim() === '') {
        throw new Error('Message body cannot be empty.');
    }

    const endpoint = `${BASE_URL}/xms/v1/${SERVICE_PLAN_ID}/batches`;

    const payload = {
        from: SINCH_NUMBER,
        to: recipients, // Array of phone numbers
        body: messageBody,
        // Optional parameters:
        // delivery_report: 'full', // Request detailed delivery reports (can be 'none', 'summary', 'full')
        // client_reference: 'your_internal_ref_123', // Custom reference string
        // feedback_enabled: true // If you plan to provide feedback later
    };

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

    console.log(`Sending bulk SMS via Sinch to ${recipients.length} recipients...`);
    // console.log('Payload:', JSON.stringify(payload, null, 2)); // Uncomment for debugging

    try {
        const response = await axios.post(endpoint, payload, config);
        console.log('Sinch API Success:', response.data);
        // The response contains the batch_id which can be used to track status
        return response.data;
    } catch (error) {
        console.error('Sinch API Error:', error.response ? JSON.stringify(error.response.data, null, 2) : error.message);
        // Re-throw a more specific error or handle it
        const errorMessage = error.response?.data?.requestError?.serviceException?.text ||
                           error.response?.data?.text ||
                           error.message ||
                           'Failed to send bulk SMS via Sinch.';
         const statusCode = error.response?.status || 500;
        const serviceError = new Error(errorMessage);
        serviceError.status = statusCode; // Attach status code if available
        serviceError.details = error.response?.data; // Attach full details
        throw serviceError;
    }
};

export { sendBulkSms };

Why Axios? It simplifies making HTTP requests and handling promises.
Why a Service? Encapsulates external API interaction, making the controller cleaner and the service reusable and easier to test.
/batches Endpoint: This specific Sinch API endpoint is designed for sending the same message to multiple recipients efficiently.
Payload Structure: Note the from, to (an array), and body fields. Refer to the Sinch API Documentation for more optional parameters like delivery_report.
Authentication: Uses the Bearer token scheme in the Authorization header.
Error Handling: Catches errors from Axios, logs details (especially the response data from Sinch if available), and throws a new error with potentially more context.

3. Building the API Layer (Routes & Controller)

Let's define the API endpoint that clients will call to trigger the broadcast.

Create Broadcast Controller (src/controllers/broadcastController.js): This handles incoming requests for the broadcast endpoint, validates input, calls the sinchService, and sends the response.

// src/controllers/broadcastController.js
import { sendBulkSms } from '../services/sinchService.js';

/**
 * Handles the POST request to /api/broadcast
 * Expects JSON body: { recipients: [""+1..."", ""+1...""], message: ""Hello"" }
 */
const handleBroadcastRequest = async (req, res, next) => {
    const { recipients, message } = req.body;

    // Basic Input Validation
    if (!recipients || !Array.isArray(recipients) || recipients.length === 0) {
        return res.status(400).json({ error: 'Missing or invalid \'recipients\' array in request body.' });
    }
    if (!message || typeof message !== 'string' || message.trim() === '') {
         return res.status(400).json({ error: 'Missing or invalid \'message\' string in request body.' });
    }

    // More robust validation (example - check E.164 format)
    const e164Pattern = /^\+[1-9]\d{1,14}$/;
    const invalidNumbers = recipients.filter(num => !e164Pattern.test(num));
    if (invalidNumbers.length > 0) {
         return res.status(400).json({
            error: 'One or more recipient phone numbers are not in valid E.164 format (e.g., +12223334444).',
            invalid_numbers: invalidNumbers
        });
    }

    try {
        console.log(`Received broadcast request for ${recipients.length} recipients.`);
        const sinchResponse = await sendBulkSms(recipients, message);

        // Successfully submitted batch to Sinch
        res.status(202).json({ // 202 Accepted is appropriate as processing is asynchronous
            message: 'Bulk SMS batch submitted successfully to Sinch.',
            batch_id: sinchResponse.id, // Include the batch ID from Sinch
            details: sinchResponse // Include full response for reference
        });

    } catch (error) {
         console.error('Error in handleBroadcastRequest:', error.message);
         // Pass the error to the global error handler middleware
         // Use the status code attached in the service layer, or default
         error.status = error.status || 500;
         next(error); // Forward error to Express error handler in app.js
    }
};

export { handleBroadcastRequest };

Input Validation: Performs essential checks on recipients and message. Includes a basic E.164 format check as an example of stricter validation. Consider using a dedicated validation library like express-validator or joi for production apps.
Service Call: Calls the sendBulkSms function from our service.
Response: Sends a 202 Accepted status on success, indicating the batch was submitted but processing (delivery) is asynchronous. Includes the batch_id from Sinch, which is crucial for tracking.
Error Forwarding: Uses next(error) to pass any caught errors to the centralized error handler defined in app.js.

Create Broadcast Routes (src/routes/broadcastRoutes.js): This file defines the specific API endpoint and maps it to the controller function.

// src/routes/broadcastRoutes.js
import express from 'express';
import { handleBroadcastRequest } from '../controllers/broadcastController.js';

const router = express.Router();

// Define the broadcast endpoint
// POST /api/broadcast
router.post('/broadcast', handleBroadcastRequest);

// You could add other related routes here if needed

export default router;

Router: Uses express.Router() to create a modular set of routes.
Mapping: Maps the POST method on the /broadcast path (which becomes /api/broadcast due to the prefix in app.js) to the handleBroadcastRequest controller function.

4. Integrating with Sinch (Recap)

Integration primarily happens within src/services/sinchService.js:

Configuration: Reads SINCH_SERVICE_PLAN_ID, SINCH_API_TOKEN, SINCH_NUMBER, and SINCH_BASE_URL from environment variables (.env) using dotenv.
API Call: Uses axios to make a POST request to the Sinch /batches endpoint (${BASE_URL}/xms/v1/${SERVICE_PLAN_ID}/batches).
Authentication: Sets the Authorization: Bearer ${API_TOKEN} header.
Payload: Constructs the JSON payload with from, to (array), and body.
Secure Handling: Keeping credentials in .env and using .gitignore prevents accidental exposure. Ensure your deployment environment securely manages these variables.

5. Error Handling, Logging, and Retry Mechanisms

Error Handling Strategy:
- Validation Errors (4xx): Handled directly in the controller (handleBroadcastRequest) with specific 400 Bad Request responses.
- API/Server Errors (5xx or Network): Caught in the sinchService, enriched with details and status code if possible, then re-thrown. These are caught again in the controller and passed via next(error) to the global error handler in app.js, which sends a generic 500 Internal Server Error (or the specific status from the service error).
- Why Centralized Handling? The global handler in app.js provides a consistent response format for unexpected server errors.
Logging:
- Basic: We've added console.log for request tracking (app.js), successful submissions, and errors (sinchService.js, broadcastController.js).
- Production Logging: For production, replace console.log with a more robust logging library like Winston or Pino. These enable:
  - Different log levels (info, warn, error, debug).
  - Structured logging (JSON format for easier parsing).
  - Multiple transports (writing to files, external logging services like Datadog, Sentry).
- Example Log Points:
  - Incoming request details.
  - Payload being sent to Sinch (potentially redacted/summarized).
  - Successful batch submission with batch_id.
  - Detailed error information (including Sinch API error responses).
Retry Mechanisms (Conceptual):
- When to Retry: Retries are suitable for transient errors like network issues or temporary Sinch server problems (e.g., 502, 503, 504 errors). Do not retry client errors (4xx) like invalid numbers or authentication failures, as they will consistently fail.
- Strategy: Implement exponential backoff. Wait a short period before the first retry, then double the wait time for subsequent retries, up to a maximum number of attempts. Add slight randomness (jitter) to wait times to avoid thundering herd issues.
- Implementation: While manual implementation is possible, libraries like axios-retry can simplify adding retry logic to Axios requests.
- Idempotency: Sinch API calls are generally not idempotent by default. Retrying a POST request might result in duplicate batches being sent if the initial request succeeded but the response was lost. Consider adding a unique client_reference in the payload if you implement retries, although Sinch doesn't explicitly guarantee idempotency based on it for the /batches endpoint. It's often safer to log the failure and investigate manually or use a more sophisticated queuing system for critical broadcasts that require guaranteed exactly-once processing. For this guide, we'll rely on logging failures.

6. Database Schema and Data Layer (Optional Enhancement)

While this guide focuses on accepting recipients directly via the API, a common scenario involves fetching recipients from a database.

Schema Example (Conceptual): If using a relational database (like PostgreSQL) with an ORM (like Prisma or Sequelize), you might have a Subscriber table:

CREATE TABLE subscribers (
    id SERIAL PRIMARY KEY,
    phone_number VARCHAR(20) NOT NULL UNIQUE, -- E.164 format
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Entity Relationship Diagram Description (Simple): A more advanced implementation might track broadcasts and recipient status:
- A SUBSCRIBER table (as above) stores user phone numbers.
- A BROADCAST table stores information about each bulk message sent (e.g., message body, Sinch batch ID, timestamp).
- A BROADCAST_RECIPIENT table links SUBSCRIBER and BROADCAST, potentially storing the delivery status for each recipient in a specific broadcast (updated via webhooks).
Data Access: You would modify the handleBroadcastRequest controller:
1. Instead of req.body.recipients, maybe accept a groupId or similar identifier.
2. Implement a data access function (e.g., subscribersService.getActiveSubscribers(groupId)) to query the database for active phone numbers.
3. Pass the fetched numbers to sinchService.sendBulkSms.
Implementation: Setting up a database, ORM, migrations, and data access functions is beyond the scope of this guide but is a common next step. Tools like Prisma or Sequelize are excellent choices in the Node.js ecosystem.

7. Adding Security Features

Security is paramount, especially when handling user data and API keys.

Input Validation & Sanitization:
- We implemented basic validation in the controller. Enhance this:
  - Strict E.164: Ensure phone numbers strictly adhere to the format.
  - Message Length: Check against SMS character limits (typically 160 characters for GSM-7, fewer for UCS-2) or let Sinch handle segmentation. Be aware of costs associated with multi-part messages.
  - Sanitization: While less critical for phone numbers, sanitize message content if it includes user-generated input to prevent potential injection attacks if the message content were ever rendered elsewhere (though unlikely for pure SMS). Libraries like DOMPurify (if rendering) or basic escaping might be relevant depending on context. For this API, strict validation is key.

Rate Limiting:

Protect your API from abuse and accidental overload. Use middleware like express-rate-limit.

Example Implementation (src/app.js):

npm install express-rate-limit

// src/app.js
import rateLimit from 'express-rate-limit';
// ... other imports
import express from 'express'; // Ensure express is imported if not already
import dotenv from 'dotenv';
import broadcastRoutes from './routes/broadcastRoutes.js';

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

app.use(express.json());

// Apply rate limiting BEFORE your routes
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',
});

app.use('/api', apiLimiter); // Apply the limiter to /api routes

// Basic logging middleware
app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
});

// Mount Routes AFTER limiter
app.use('/api', broadcastRoutes);

// Basic Error Handler Middleware
app.use((err, req, res, next) => {
    console.error('Global Error Handler:', err.stack);
    res.status(err.status || 500).json({
        error: {
            message: err.message || 'Something went wrong!',
            stack: process.env.NODE_ENV === 'development' ? err.stack : undefined,
        }
    });
});

app.listen(port, () => {
    console.log(`Server running on http://localhost:${port}`);
    if (!process.env.SINCH_SERVICE_PLAN_ID || !process.env.SINCH_API_TOKEN || !process.env.SINCH_NUMBER) {
         console.warn('WARN: Missing one or more required Sinch environment variables (ID, TOKEN, NUMBER). API calls may fail.');
    }
});

export default app;

API Key Security:
- Already handled using .env and .gitignore.
- In production, use your hosting provider's secret management system (e.g., AWS Secrets Manager, GCP Secret Manager, Heroku Config Vars).
HTTPS:
- Always run your production application behind a reverse proxy (like Nginx or Caddy) or use a platform (like Heroku, Vercel, AWS Elastic Beanstalk) that terminates SSL/TLS, ensuring all communication is encrypted via HTTPS. Do not run plain HTTP in production.
Authentication/Authorization (Optional):
- If this API needs to be protected, implement an authentication strategy (e.g., API Keys for machine clients, JWT for users) to ensure only authorized clients can trigger broadcasts. This is outside the scope of this basic guide but crucial for many real-world applications.

8. Handling Special Cases

Phone Number Formatting: Always normalize and validate numbers to E.164 format (+ followed by country code and number, no spaces or dashes) before sending to Sinch.
Message Encoding & Length:
- Standard SMS (GSM-7) supports 160 characters.
- Using non-standard characters (like emojis or certain accented letters) switches encoding to UCS-2, reducing the limit to 70 characters per segment.
- Long messages are automatically split (segmented) by carriers, and you are billed for each segment. Be mindful of message length. Sinch handles segmentation, but inform users or truncate if necessary.
Internationalization: The E.164 format inherently handles country codes. Ensure your SINCH_NUMBER is enabled for international sending if broadcasting globally. Message content localization would need to be handled by your application logic before calling the API.
Delivery Reports (DLRs):
- Sinch can send delivery status updates via webhooks. This requires:
  1. Setting delivery_report: 'full' (or other level) in the /batches payload.
  2. Configuring a webhook URL in your Sinch API settings.
  3. Building another endpoint in your Express app to receive these POST requests from Sinch.
- Processing DLRs allows tracking message success/failure rates but adds complexity.

9. Implementing Performance Optimizations

Batching (Already Implemented): Using the /batches endpoint is the single most significant optimization for bulk sending, reducing network latency and API call overhead compared to sending individual messages.
Asynchronous Processing (Advanced): For very large broadcasts (tens of thousands or more), the API call to Sinch might take noticeable time, potentially holding up the HTTP request. Consider:
1. Accept the request quickly (202 Accepted).
2. Push the broadcast job (recipients, message) onto a message queue (e.g., RabbitMQ, Redis BullMQ, AWS SQS).
3. Have separate worker processes that consume jobs from the queue and call the sinchService.
- This decouples the API request from the actual sending process, improving API responsiveness but requiring additional infrastructure.
Database Query Optimization: If fetching recipients from a database, ensure queries are efficient (proper indexing on phone_number, is_active, etc.). Fetch only the necessary data (phone_number).
Node.js Performance: Ensure non-blocking I/O is used (which axios and standard Node.js operations do). Avoid CPU-bound tasks on the main event loop thread for high-throughput scenarios.

10. Adding Monitoring, Observability, and Analytics

For production readiness, visibility into your application's health and performance is vital.

Health Checks: Add a simple endpoint (e.g., /healthz) that returns a 200 OK status. Monitoring systems can ping this to verify the service is running.
Metrics: Track key performance indicators (KPIs):
- Request rate and latency for the /api/broadcast endpoint.
- Error rates (overall and specifically for Sinch API calls).
- Number of recipients per broadcast request.
- Sinch API call duration.
- Tools: Use libraries like prom-client to expose metrics in Prometheus format, then visualize them in Grafana. Cloud providers often have integrated monitoring solutions.

Error Tracking: Integrate an error tracking service like Sentry or Datadog APM. These automatically capture unhandled exceptions, provide detailed stack traces, context, and alerting.

Example (app.js with Sentry - conceptual):

npm install @sentry/node @sentry/tracing

// src/app.js
import express from 'express';
import dotenv from 'dotenv';
import * as Sentry from '@sentry/node';
import * as Tracing from '@sentry/tracing';
import broadcastRoutes from './routes/broadcastRoutes.js';

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

// Initialize Sentry *before* anything else
Sentry.init({
  dsn: process.env.SENTRY_DSN, // Get DSN from Sentry project settings
  integrations: [
    new Sentry.Integrations.Http({ tracing: true }), // Enable HTTP tracing
    new Tracing.Integrations.Express({ app }),      // Enable Express tracing
  ],
  tracesSampleRate: 1.0, // Adjust sampling rate in production
  environment: process.env.NODE_ENV || 'development',
});

// Sentry Request Handler - *must* be the first middleware
app.use(Sentry.Handlers.requestHandler());
// Sentry Tracing Handler - *before* any routes
app.use(Sentry.Handlers.tracingHandler());

// Your regular middleware
app.use(express.json());

// Basic logging middleware (optional)
app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
});

// Your routes
app.use('/api', broadcastRoutes);

// Sentry Error Handler - *must* be before any other error handler
// but *after* all controllers
app.use(Sentry.Handlers.errorHandler());

// Your optional custom error handler (falls back after Sentry)
app.use((err, req, res, next) => {
   console.error('Global Error Handler:', err.stack);
   // The error id is attached to `res.sentry`
   const errorMsg = `Something went wrong! Ref: ${res.sentry || 'N/A'}`;
   res.status(err.status || 500).json({
       error: {
           message: err.message || errorMsg,
           ref: res.sentry
       }
   });
});

app.listen(port, () => {
    console.log(`Server running on http://localhost:${port}`);
    if (!process.env.SINCH_SERVICE_PLAN_ID || !process.env.SINCH_API_TOKEN || !process.env.SINCH_NUMBER) {
         console.warn('WARN: Missing one or more required Sinch environment variables (ID, TOKEN, NUMBER). API calls may fail.');
    }
});

export default app;

Logging (Revisited): Ensure production logs are collected, aggregated (e.g., ELK stack, Datadog Logs, Papertrail), and searchable for troubleshooting.

11. Troubleshooting and Caveats

Common Sinch Errors (Check error.response.data):
- 401 Unauthorized: Invalid API_TOKEN or SERVICE_PLAN_ID. Double-check credentials in .env and the Sinch dashboard.
- 400 Bad Request: Often due to invalid phone number format (ensure E.164), missing required fields (from, to, body), or issues with the SINCH_NUMBER (e.g., not provisioned correctly). Check the detailed error message from Sinch.
- 403 Forbidden: The SINCH_NUMBER might not be allowed to send messages to a specific region, or the account might have restrictions.
- 5xx Server Error: Temporary issue on Sinch's side. Consider implementing retries with backoff for these.
Rate Limits: Both your own API (if implemented) and the Sinch API have rate limits. Check Sinch documentation for their limits and handle 429 Too Many Requests errors appropriately (e.g., by slowing down requests or using backoff).
Character Encoding: Be mindful of GSM-7 vs. UCS-2 encoding and character limits per SMS segment.
Delivery Status: Remember that a successful API response (202 Accepted with a batch_id) only means Sinch accepted the batch, not that messages were delivered. Use Delivery Reports (Webhooks) for actual delivery confirmation.
Cost: Sending SMS messages incurs costs. Understand Sinch's pricing model, especially for segmented messages and international sending. Monitor your usage.
Regulations: Be aware of SMS regulations in the countries you are sending to (e.g., opt-in requirements, sending times, content restrictions). Compliance is crucial.

10DLC Registration: SMS Campaign Approval and Compliance Guide