Sinch Bulk SMS with Node.js & Express: Complete Implementation Guide 2025

graph LR
    A[User/Client Application] -- HTTP POST Request --> B(Node.js/Express API Server);
    B -- Send Batch Request (recipients, message) --> C(Sinch SMS API);
    C -- Sends SMS --> D{Recipient Phones};
    C -- Returns Batch ID/Status --> B;
    B -- Returns API Response (success/failure) --> A;

mkdir sinch-bulk-sms-app
cd sinch-bulk-sms-app

npm init -y

{
  "name": "sinch-bulk-sms-app",
  "version": "1.0.0",
  "description": "",
  "main": "server.mjs",
  "type": "module",
  "scripts": {
    "start": "node server.mjs",
    "dev": "nodemon server.mjs"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

npm install express dotenv node-fetch winston

npm install --save-dev nodemon

# .gitignore

# Dependencies
node_modules/

# Environment variables
.env

# Logs
logs/
*.log

# OS generated files
.DS_Store
Thumbs.db

# .env

# Sinch API Credentials
SINCH_SERVICE_PLAN_ID=YOUR_SERVICE_PLAN_ID
SINCH_API_TOKEN=YOUR_API_TOKEN
SINCH_NUMBER=+1XXXXXXXXXX # Your provisioned Sinch number or Alphanumeric Sender ID

# Sinch API Region Endpoint Base URL (Choose the correct one for your account)
# US: https://us.sms.api.sinch.com
# EU: https://eu.sms.api.sinch.com
# More regions available, see Sinch documentation
SINCH_REGION_URL=https://us.sms.api.sinch.com

# Application Port
PORT=3000

# Logging Level (error, warn, info, http, verbose, debug, silly)
LOG_LEVEL=info

// services/sinchService.mjs
import fetch from 'node-fetch';
import logger from '../config/logger.mjs'; // We will create this logger soon

const SERVICE_PLAN_ID = process.env.SINCH_SERVICE_PLAN_ID;
const API_TOKEN = process.env.SINCH_API_TOKEN;
const SINCH_REGION_URL = process.env.SINCH_REGION_URL;

/**
 * Sends a bulk SMS message using the Sinch Batches API.
 * The Batches endpoint sends sets of SMS messages queued and delivered in first-in-first-out order.
 * Batches are stored in Sinch's system for 14 days after creation.
 *
 * @param {string[]} recipients - An array of recipient phone numbers in E.164 format (+ followed by country code and number, max 15 digits per ITU-T E.164).
 * @param {string} messageBody - The text content of the SMS message.
 * @param {string} sender - The sender ID (Sinch Number or Alphanumeric Sender ID).
 * @param {boolean} feedbackEnabled - Whether Sinch should attempt to provide delivery feedback via webhooks (requires webhook setup).
 * @returns {Promise<object>} - A promise that resolves with the Sinch API response containing batch_id and other metadata.
 * @throws {Error} - Throws an error if the API call fails.
 */
export const sendBulkSms = async (recipients, messageBody, sender, feedbackEnabled = false) => {
    const endpoint = `${SINCH_REGION_URL}/xms/v1/${SERVICE_PLAN_ID}/batches`;

    // Validate essential configuration
    if (!SERVICE_PLAN_ID || !API_TOKEN || !SINCH_REGION_URL || !sender) {
        logger.error('Sinch configuration missing in environment variables.');
        throw new Error('Sinch service configuration is incomplete.');
    }
    if (!recipients || recipients.length === 0) {
        logger.error('No recipients provided for bulk SMS.');
        throw new Error('Recipient list cannot be empty.');
    }
    if (!messageBody) {
        logger.error('No message body provided for bulk SMS.');
        throw new Error('Message body cannot be empty.');
    }

    // Construct the payload for the Sinch Batches API
    const payload = {
        to: recipients,             // Array of phone numbers
        from: sender,               // Your Sinch number or Sender ID
        body: messageBody,          // The message content
        feedback_enabled: feedbackEnabled // Optional: Set true if you plan to handle delivery feedback
        // You can add other parameters like 'delivery_report', 'expire_at', etc.
        // Refer to Sinch API documentation for more options:
        // https://developers.sinch.com/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/SendSMSBatchMessage
    };

    logger.info(`Sending bulk SMS to ${recipients.length} recipients via Sinch`);
    logger.debug(`Sinch API Endpoint: ${endpoint}`);
    // logger.debug(`Sinch API Payload: ${JSON.stringify(payload)}`); // Be careful logging payload with phone numbers

    try {
        const response = await fetch(endpoint, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${API_TOKEN}` // Use Bearer token authentication
            },
            body: JSON.stringify(payload)
        });

        const responseData = await response.json();

        if (!response.ok) {
            // Log detailed error information from Sinch
            logger.error(`Sinch API Error (${response.status}): ${JSON.stringify(responseData)}`);
            throw new Error(`Sinch API request failed with status ${response.status}: ${responseData.code || ''} ${responseData.text || ''}`);
        }

        logger.info(`Sinch batch submitted successfully. Batch ID: ${responseData.id}`);
        // logger.debug(`Sinch API Response: ${JSON.stringify(responseData)}`);
        return responseData; // Contains batch_id, etc.

    } catch (error) {
        logger.error(`Error calling Sinch API: ${error.message}`, { stack: error.stack });
        // Re-throw the error to be handled by the calling route
        throw error;
    }
};

// Why this approach?
// 1. Encapsulation: Keeps Sinch-specific logic separate from the API routes.
// 2. Async/Await: Handles the asynchronous nature of network requests cleanly.
// 3. node-fetch: Standard way to make HTTP requests in modern Node.js.
// 4. Bearer Token Auth: Standard and secure way to authenticate with the Sinch API.
// 5. Error Handling: Includes checks for configuration and handles API response errors, logging useful details.
// 6. Parameterization: Makes the function reusable by accepting recipients, message, and sender dynamically.
// 7. Feedback Enabled Flag: Includes the option to request delivery feedback, although handling the callback is not implemented in this guide.

// routes/smsRoutes.mjs
import express from 'express';
import { sendBulkSms } from '../services/sinchService.mjs';
import logger from '../config/logger.mjs';

const router = express.Router();
const SINCH_NUMBER = process.env.SINCH_NUMBER;

// POST /api/broadcast
// Endpoint to send a bulk SMS broadcast
router.post('/broadcast', async (req, res) => {
    // Basic Input Validation
    const { recipients, message } = req.body;

    if (!Array.isArray(recipients) || recipients.length === 0) {
        logger.warn('Broadcast request received with invalid or empty recipients list.');
        return res.status(400).json({ error: 'Invalid request: recipients must be a non-empty array of phone numbers.' });
    }
    if (typeof message !== 'string' || message.trim() === '') {
        logger.warn('Broadcast request received with invalid or empty message.');
        return res.status(400).json({ error: 'Invalid request: message must be a non-empty string.' });
    }
    if (!SINCH_NUMBER) {
        logger.error('Sinch sender number/ID is not configured in environment variables.');
        return res.status(500).json({ error: 'Server configuration error: Sender ID not set.' });
    }

    // Basic phone number format validation (E.164: + followed by 1-15 digits, per ITU-T E.164 specification)
    // E.164 format: + [country code 1-3 digits] [subscriber number, total max 15 digits]
    const invalidNumbers = recipients.filter(num => !/^\+[1-9]\d{1,14}$/.test(num));
    if (invalidNumbers.length > 0) {
        logger.warn(`Broadcast request received with invalid phone numbers: ${invalidNumbers.join(', ')}`);
        return res.status(400).json({
            error: 'Invalid request: One or more recipient phone numbers are not in valid E.164 format (+ followed by country code and subscriber number, max 15 digits total per ITU-T E.164).',
            invalid_numbers: invalidNumbers
         });
    }

    logger.info(`Received broadcast request for ${recipients.length} recipients.`);

    try {
        // Call the Sinch service function
        const sinchResponse = await sendBulkSms(recipients, message, SINCH_NUMBER);

        // Respond to the client
        res.status(202).json({ // 202 Accepted: Request received, processing started
            message: 'SMS batch submitted successfully to Sinch.',
            batch_id: sinchResponse.id,
            // Include other relevant info from sinchResponse if needed
        });

    } catch (error) {
        // Log the error (already logged in sinchService, but good to log context here too)
        logger.error(`Failed to process broadcast request: ${error.message}`);

        // Determine appropriate status code based on error if possible
        // For now, return a generic 500 for internal errors
        res.status(500).json({
            error: 'Failed to send SMS batch.',
            details: error.message // Provide some detail back, but be cautious in production
        });
    }
});

export default router;

// Design Decisions:
// 1. POST Method: Appropriate for actions that create a resource (in this case, an SMS batch submission).
// 2. Input Validation: Crucial first step to reject invalid requests early. Checks for presence, type, and basic format.
// 3. Separation of Concerns: Route handler focuses on request/response and validation, delegating the core SMS sending logic to `sinchService`.
// 4. Error Handling: Uses try/catch to handle errors from the service layer and respond appropriately to the client.
// 5. Status Codes: Uses meaningful HTTP status codes (202 Accepted for successful submission, 400 Bad Request for validation errors, 500 Internal Server Error for processing failures).
// 6. Configuration Use: Pulls the sender number directly from environment variables.

curl -X POST http://localhost:3000/api/broadcast \
 -H "Content-Type: application/json" \
 -d '{
       "recipients": ["+15551234567", "+15559876543"],
       "message": "Hello from our Node.js broadcast app!"
     }'

{
  "message": "SMS batch submitted successfully to Sinch.",
  "batch_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}

{
  "error": "Invalid request: message must be a non-empty string."
}

{
  "error": "Failed to send SMS batch.",
  "details": "Sinch API request failed with status 401: 40100 Invalid credentials ..."
}

// config/logger.mjs
import winston from 'winston';

const { combine, timestamp, printf, colorize, align, json } = winston.format;

// Determine log level from environment variable, default to 'info'
const logLevel = process.env.LOG_LEVEL || 'info';

// Custom log format
const logFormat = printf(({ level, message, timestamp, stack, ...metadata }) => {
  let msg = `${timestamp} [${level}]: ${message}`;
  // Add stack trace for errors
  if (stack) {
    msg += `\n${stack}`;
  }
  // Add any additional metadata, ensuring space is only added if metadata exists
  const metadataString = Object.keys(metadata).length ? ` ${JSON.stringify(metadata)}` : '';
  msg += metadataString;
  return msg;
});

const logger = winston.createLogger({
  level: logLevel,
  format: combine(
    timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
    json() // Log as JSON potentially for log aggregators
  ),
  transports: [
    // Default console transport with colorization and readable format
    new winston.transports.Console({
      format: combine(
        colorize(),
        align(),
        timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
        logFormat
      ),
    }),
    // Optionally, add file transports for persistence
    // new winston.transports.File({
    //   filename: 'logs/error.log',
    //   level: 'error',
    //   format: combine(timestamp(), json()), // Keep file logs structured
    // }),
    // new winston.transports.File({
    //   filename: 'logs/combined.log',
    //    format: combine(timestamp(), json()),
    // }),
  ],
  exceptionHandlers: [
    // Catch unhandled exceptions
    new winston.transports.Console({
        format: combine(colorize(), logFormat)
    }),
    // new winston.transports.File({ filename: 'logs/exceptions.log' })
  ],
  rejectionHandlers: [
     // Catch unhandled promise rejections
     new winston.transports.Console({
         format: combine(colorize(), logFormat)
     }),
     // new winston.transports.File({ filename: 'logs/rejections.log' })
  ]
});

logger.info(`Logger initialized with level: ${logLevel}`);

export default logger;

// Why Winston?
// 1. Flexibility: Supports multiple transports (console, file, HTTP, etc.).
// 2. Formatting: Customizable log formats (text, JSON).
// 3. Levels: Standard logging levels (error, warn, info, debug, etc.).
// 4. Unhandled Exceptions/Rejections: Can catch and log critical application crashes.

// Example within sinchService.mjs (conceptual)
import retry from 'async-retry';

// ... inside sendBulkSms, replace the direct fetch call ...

try {
    const sinchResponse = await retry(
        async (bail, attempt) => {
            logger.info(`Attempt ${attempt} to call Sinch API...`);
            const response = await fetch(endpoint, { /* ... fetch options ... */ });
            const responseData = await response.json(); // Need to handle non-JSON responses too

            if (!response.ok) {
                 logger.error(`Sinch API Error on attempt ${attempt} (${response.status}): ${JSON.stringify(responseData)}`);
                 // Don't retry on client errors (4xx) except maybe rate limiting (429)
                 if (response.status >= 400 && response.status < 500 && response.status !== 429) {
                     bail(new Error(`Non-retriable Sinch API error: ${response.status}`)); // Stop retrying
                     return; // Important: exit async function after bail
                 }
                 // Throw error to trigger retry for 5xx or 429
                 throw new Error(`Sinch API request failed with status ${response.status}`);
            }
            return responseData; // Success
        },
        {
            retries: 3, // Number of retries
            factor: 2, // Exponential backoff factor
            minTimeout: 1000, // Initial delay 1 second
            maxTimeout: 5000, // Max delay 5 seconds
            onRetry: (error, attempt) => {
                logger.warn(`Retrying Sinch API call (attempt ${attempt}) due to error: ${error.message}`);
            },
        }
    );

     logger.info(`Sinch batch submitted successfully after retries. Batch ID: ${sinchResponse.id}`);
     return sinchResponse;

} catch (error) {
     logger.error(`Failed to call Sinch API after multiple retries: ${error.message}`, { stack: error.stack });
     throw error; // Re-throw final error
}

// schema.prisma

datasource db {
  provider = "postgresql" // or "mysql", "sqlite", "mongodb"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Subscriber {
  id          String    @id @default(cuid())
  phoneNumber String    @unique // E.164 format recommended
  firstName   String?
  lastName    String?
  isActive    Boolean   @default(true) // For opt-out management
  subscribedAt DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
  tags        String[]  // For segmenting users
  // Add other relevant fields
}

model Broadcast {
  id          String    @id @default(cuid())
  message     String
  status      String    // e.g., PENDING, SENT, FAILED
  sinchBatchId String?   @unique // Link to Sinch batch
  sentAt      DateTime?
  createdAt   DateTime  @default(now())
  // Maybe link to subscribers targeted if needed (e.g., via tags)
}

// Add models for tracking message delivery status via webhooks if implemented

erDiagram
    SUBSCRIBER ||--o{ TAGS : "has" // Assuming tags are strings for simplicity
    BROADCAST {
        String id PK
        String message
        String status
        String sinchBatchId UK
        DateTime sentAt
        DateTime createdAt
    }
    SUBSCRIBER {
        String id PK
        String phoneNumber UK
        String firstName
        String lastName
        Boolean isActive
        DateTime subscribedAt
        DateTime updatedAt
    }
    // Relationship depends on how targeting is done
    // Option 1: Log targeted tags in Broadcast
    // Option 2: Many-to-many if tracking individual sends per broadcast

// services/subscriberService.mjs (Conceptual Example)
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();

export const getActiveSubscribersByTag = async (tag) => {
  return prisma.subscriber.findMany({
    where: {
      isActive: true,
      tags: {
        has: tag, // Prisma specific array query
      },
    },
    select: {
      phoneNumber: true, // Only select the needed field
    },
  });
};

export const optOutSubscriber = async (phoneNumber) => {
 return prisma.subscriber.update({
    where: { phoneNumber: phoneNumber },
    data: { isActive: false },
 });
};

// Add functions to create, update, delete subscribers

// smsRoutes.mjs (Conceptual Change)
import { getActiveSubscribersByTag } from '../services/subscriberService.mjs'; // Conceptual

router.post('/broadcast/tag/:tagName', async (req, res) => {
    const { tagName } = req.params;
    const { message } = req.body;
    // ... validation for message ...

    try {
        const subscribers = await getActiveSubscribersByTag(tagName);
        const recipients = subscribers.map(sub => sub.phoneNumber);

        if (recipients.length === 0) {
            return res.status(404).json({ error: `No active subscribers found for tag: ${tagName}` });
        }

        // Ensure SINCH_NUMBER is checked/available here too
        if (!SINCH_NUMBER) {
             logger.error('Sinch sender number/ID is not configured.');
             return res.status(500).json({ error: 'Server configuration error: Sender ID not set.' });
        }

        const sinchResponse = await sendBulkSms(recipients, message, SINCH_NUMBER);
        // ... response handling ...
    } catch (error) {
        // ... error handling ...
        logger.error(`Failed to process broadcast request for tag ${tagName}: ${error.message}`);
        res.status(500).json({
            error: 'Failed to send SMS batch.',
            details: error.message
        });
    }
});

// middleware/auth.mjs
import logger from '../config/logger.mjs';

const API_KEYS = process.env.API_KEYS ? process.env.API_KEYS.split(',') : [];

export const authenticateApiKey = (req, res, next) => {
    const apiKey = req.headers['x-api-key'];

    if (!apiKey) {
        logger.warn('Request received without API key');
        return res.status(401).json({ error: 'API key required' });
    }

    if (!API_KEYS.includes(apiKey)) {
        logger.warn(`Invalid API key attempted: ${apiKey.substring(0, 8)}...`);
        return res.status(403).json({ error: 'Invalid API key' });
    }

    next();
};

// routes/smsRoutes.mjs
import { authenticateApiKey } from '../middleware/auth.mjs';

router.post('/broadcast', authenticateApiKey, async (req, res) => {
    // ... existing code ...
});

npm install express-rate-limit

// server.mjs
import rateLimit from 'express-rate-limit';

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

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

npm audit
npm audit fix

logger.info(`Using API token: ${API_TOKEN.substring(0, 4)}...${API_TOKEN.substring(API_TOKEN.length - 4)}`);

// Production error handling
if (process.env.NODE_ENV === 'production') {
    res.status(500).json({ error: 'An error occurred processing your request.' });
} else {
    res.status(500).json({ error: 'Failed to send SMS batch.', details: error.message });
}

// server.mjs
import 'dotenv/config'; // Load environment variables at the very start
import express from 'express';
import logger from './config/logger.mjs';
import smsRoutes from './routes/smsRoutes.mjs';

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

// Middleware
app.use(express.json()); // Parse JSON request bodies
app.use(express.urlencoded({ extended: true })); // Parse URL-encoded bodies

// Routes
app.use('/api', smsRoutes);

// Health check endpoint
app.get('/health', (req, res) => {
    res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
});

// 404 handler
app.use((req, res) => {
    res.status(404).json({ error: 'Route not found' });
});

// Global error handler
app.use((err, req, res, next) => {
    logger.error(`Unhandled error: ${err.message}`, { stack: err.stack });
    res.status(500).json({ error: 'Internal server error' });
});

// Start server
app.listen(PORT, () => {
    logger.info(`Server started successfully on port ${PORT}`);
    logger.info(`Environment: ${process.env.NODE_ENV || 'development'}`);
    logger.info(`Health check available at http://localhost:${PORT}/health`);
});

// Graceful shutdown
process.on('SIGTERM', () => {
    logger.info('SIGTERM signal received: closing HTTP server');
    server.close(() => {
        logger.info('HTTP server closed');
    });
});

npm start
# or for development with auto-reload
npm run dev

curl http://localhost:3000/health

curl -X POST http://localhost:3000/api/broadcast \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+15551234567", "+15559876543"],
    "message": "Test message from Sinch bulk SMS app"
  }'

// tests/sinchService.test.mjs
import { jest } from '@jest/globals';
import { sendBulkSms } from '../services/sinchService.mjs';

describe('sinchService', () => {
    it('should send bulk SMS successfully', async () => {
        // Mock fetch
        global.fetch = jest.fn(() =>
            Promise.resolve({
                ok: true,
                json: () => Promise.resolve({ id: 'test-batch-id' }),
            })
        );

        const result = await sendBulkSms(['+15551234567'], 'Test', '+15559999999');
        expect(result.id).toBe('test-batch-id');
        expect(fetch).toHaveBeenCalledTimes(1);
    });
});