Build a Bulk SMS API with Twilio & Fastify: Complete Node.js Guide

Send SMS messages in bulk to reach your audience effectively. Whether you're building promotional campaigns, critical alerts, or notifications, delivering messages reliably and at scale is crucial. This guide demonstrates production-scale capabilities – sending 1,000 to 100,000 messages per hour – using Twilio Messaging Services with proper sender pools and queue-based processing.

This guide walks you through building a scalable bulk messaging API using Fastify – a high-performance Node.js web framework – and Twilio's robust Programmable Messaging API. You'll use Twilio Messaging Services for scalability and deliverability, building a solid foundation for handling large message volumes efficiently. While we aim for robustness, note that certain components (like the basic authentication and asynchronous processing method) serve as starting points and require enhancement for high-volume, mission-critical production environments.

Project Overview and Goals

What You'll Build:

You'll create a Node.js application using the Fastify framework. This application exposes a single API endpoint (POST /broadcast) that accepts a message body and a list of recipient phone numbers. When you send a request, the API leverages Twilio's Programmable Messaging API via a Messaging Service to initiate sending the specified message to all unique recipients. Expected throughput: 10–100 messages per second with proper configuration, handling 36,000–360,000 messages per hour.

Problem This Solves:

You need to send the same SMS message to numerous recipients programmatically without overwhelming the Twilio API or facing deliverability issues from sending high volumes from a single phone number. This solution provides a scalable and reliable method for bulk SMS communication. The approach handles moderate volumes (1,000–10,000 messages per batch) in the demo configuration and scales to enterprise levels (100,000+ per hour) with production enhancements like job queues and expanded sender pools.

Technologies Used:

• Node.js: A JavaScript runtime environment for server-side development.
• Fastify: A fast, low-overhead web framework for Node.js, chosen for its performance and developer experience.
• Twilio Programmable Messaging API: Sends SMS messages.
• Twilio Messaging Service: Essential for managing sender phone numbers (pool), scaling message throughput, ensuring compliance, and handling opt-outs automatically.
• twilio (Node.js Helper Library): Simplifies interaction with the Twilio API.
• dotenv: Manages environment variables for secure configuration.
• pino & pino-pretty: Efficient JSON logging for Node.js, integrated with Fastify.
• fastify-env: Schema-based environment variable loading and validation for Fastify.
• @fastify/rate-limit: Adds rate limiting capabilities to the API.

Dependency Versions (January 2025):

System Architecture:

(Note: Ensure the Mermaid diagram renders correctly on your publishing platform.)

graph LR
    Client[Client Application / curl / Postman] -- HTTP POST Request --> API{Fastify API (/broadcast)};
    API -- Send Message Requests --> Twilio[Twilio Messaging Service];
    Twilio -- Delivers SMS --> User1[Recipient 1];
    Twilio -- Delivers SMS --> User2[Recipient 2];
    Twilio -- Delivers SMS --> UserN[Recipient N];
    API -- Logs Events --> Log[Logging System];
    API -- Returns 202 Accepted --> Client;

    subgraph "Node.js Application"
        API
        Log
    end

    subgraph "Twilio Cloud"
        Twilio
    end

Production Architecture Note: For production systems handling thousands of messages, replace the simple async processing with a job queue (BullMQ + Redis, RabbitMQ, or AWS SQS). This ensures reliable processing, automatic retries, and horizontal scalability.

Prerequisites:

• Node.js (LTS version recommended). As of 2025, use Node.js v22 "Jod" (Active LTS) or Node.js v20 "Iron" (Maintenance LTS). Production applications should only use Active LTS or Maintenance LTS releases. Source: Node.js Releases (2025)
• npm or yarn package manager.
• A Twilio account. Sign up for free. Note: Trial accounts can only message verified phone numbers and are limited to one Twilio phone number. Source: Twilio Trial Account Limitations (2025)
• A Twilio phone number with SMS capabilities. Learn how to get a Twilio number.
• Basic familiarity with Node.js, Fastify, and REST APIs.
• curl or a tool like Postman for testing the API endpoint.

Estimated Costs: Testing with 100–500 messages costs approximately $5–$25 USD (depending on destination countries). Production at 100,000 messages/day costs roughly $600–$800 USD per month for US domestic traffic at $0.0079 per SMS segment. Use Twilio's Pricing Calculator for your specific regions.

Final Outcome:

By the end of this guide, you'll have a functional Fastify API capable of receiving bulk messaging requests and efficiently initiating their delivery via Twilio. Your API will include basic security, validation, logging, and rate limiting – providing a strong starting point for a bulk messaging solution.

1. Setting Up the Project

Initialize your project, install dependencies, and set up the basic structure.

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

   bash

   mkdir fastify-twilio-bulk-sms
   cd fastify-twilio-bulk-sms
   

2. Initialize Node.js Project: Initialize the project using npm (or yarn).

   bash

   npm init -y
   

3. Install Dependencies: Install Fastify, the Twilio helper library, logging tools, and environment variable management.

   bash

   npm install fastify twilio dotenv pino-pretty fastify-env @fastify/rate-limit
   
   • fastify: The core web framework.
   • twilio: Official Node.js library for the Twilio API.
   • dotenv: Loads environment variables from a .env file.
   • pino-pretty: Formats Pino logs for better readability during development.
   • fastify-env: Validates and loads environment variables based on a schema.
   • @fastify/rate-limit: Plugin for request rate limiting. Source: Fastify Rate Limit (2025)

4. Create Project Structure: Organize the project files for better maintainability.

   bash

   mkdir src
   mkdir src/routes
   mkdir src/config
   touch server.js
   touch .env
   touch .gitignore
   touch src/routes/broadcast.js
   touch src/config/environment.js
   
   • server.js: The main entry point for the Fastify application.
   • .env: Stores sensitive credentials and configuration (API keys, etc.). Never commit this file to version control.
   • .gitignore: Specifies intentionally untracked files that Git should ignore (like .env and node_modules).
   • src/routes/broadcast.js: Defines the API route for sending bulk messages.
   • src/config/environment.js: Defines the schema for environment variables using fastify-env.

5. Configure .gitignore: Add node_modules and .env to your .gitignore file to prevent committing them.

   plaintext

   # .gitignore
   
   node_modules
   .env
   *.log
   

6. Set up Environment Variables (.env): You need three key pieces of information from your Twilio account: Account SID, Auth Token, and a Messaging Service SID.

   • Get Account SID and Auth Token:

     • Log in to the Twilio Console.
     • On the main dashboard, you'll find your Account SID and Auth Token. Copy these values.
     • Security Note: Your Auth Token is sensitive. Treat it like a password. Rotate tokens every 90 days or immediately if compromised. Generate a new Auth Token in Console > Account > API Keys & Tokens, then update your .env file and restart your application.

   • Create and Configure a Messaging Service:

     • Navigate to Messaging > Services in the Twilio Console.
     • Click Create Messaging Service.
     • Give it a friendly name (e.g., "Fastify Bulk Sender").
     • Select a use case – "Notifications, Outbound Only" is suitable here. Click Create Messaging Service.
     • On the service's configuration page, go to the "Sender Pool" section.
     • Click "Add Senders". Select "Phone Number" and add the Twilio phone number you acquired earlier.
     • Advanced Settings: Enable "Sticky Sender" to maintain consistent sender numbers for message threads. Enable "Geomatch" to automatically route messages from numbers in the recipient's country (improves deliverability). Configure "Fallback URL" for webhook failures in production.
     • Go back to the service's "Properties" page. Copy the Messaging Service SID (it starts with MG...).

   • Populate .env: Open the .env file and add your credentials. Replace the placeholders with your actual values. Generate a secure API key using: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" (minimum 32 bytes of entropy).

     bash

     # .env
     
     # Twilio Credentials
     TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     TWILIO_AUTH_TOKEN=your_auth_token_xxxxxxxxxxxxxx
     TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     
     # API Security (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))")
     API_SECRET_KEY=your_super_secret_api_key_here
     
     # Server Configuration
     NODE_ENV=development
     PORT=3000
     LOG_LEVEL=info
     

7. Define Environment Schema (src/config/environment.js): Using fastify-env, define a schema to validate and load environment variables.

   javascript

   // src/config/environment.js
   'use strict'
   
   const environmentSchema = {
     type: 'object',
     required: [
       'TWILIO_ACCOUNT_SID',
       'TWILIO_AUTH_TOKEN',
       'TWILIO_MESSAGING_SERVICE_SID',
       'API_SECRET_KEY',
       'PORT'
     ],
     properties: {
       TWILIO_ACCOUNT_SID: { type: 'string', minLength: 34, maxLength: 34 },
       TWILIO_AUTH_TOKEN: { type: 'string', minLength: 32 },
       TWILIO_MESSAGING_SERVICE_SID: { type: 'string', minLength: 34, maxLength: 34 },
       API_SECRET_KEY: { type: 'string', minLength: 32 },
       NODE_ENV: { type: 'string', default: 'development' },
       PORT: { type: 'string', default: '3000' },
       LOG_LEVEL: { type: 'string', default: 'info' }
     }
   }
   
   const options = {
     confKey: 'config', // Decorate Fastify instance with `config` key
     schema: environmentSchema,
     dotenv: true // Load .env file
   }
   
   module.exports = options
   module.exports.environmentSchema = environmentSchema // Export schema if needed elsewhere
   
   • Why fastify-env? It ensures required variables are present and validates their format upon application startup, preventing runtime errors due to missing or incorrect configuration. It also conveniently decorates the Fastify instance (fastify.config) with the loaded variables.

8. Basic Fastify Server Setup (server.js): Configure the main server file to load environment variables, set up logging, register plugins, and define routes.

   javascript

   // server.js
   'use strict'
   
   // Load environment variables first using dotenv directly for early access if needed
   // Note: fastify-env will also load .env, but this ensures process.env is populated early
   require('dotenv').config()
   
   const Fastify = require('fastify')
   const environmentOptions = require('./src/config/environment')
   const broadcastRoutes = require('./src/routes/broadcast')
   
   // Determine logger settings based on environment
   const isDevelopment = process.env.NODE_ENV === 'development'
   const loggerConfig = isDevelopment
     ? {
         level: process.env.LOG_LEVEL || 'info',
         transport: {
           target: 'pino-pretty',
           options: {
             translateTime: 'HH:MM:ss Z',
             ignore: 'pid,hostname'
           }
         }
       }
     : { level: process.env.LOG_LEVEL || 'info' } // Production logging (JSON)
   
   // Initialize Fastify
   const fastify = Fastify({
     logger: loggerConfig
   })
   
   // Register plugins
   fastify.register(require('@fastify/env'), environmentOptions)
   fastify.register(require('@fastify/rate-limit'), {
     max: 100, // Max requests per window
     timeWindow: '1 minute' // Time window
   })
   
   // Rate limiting set to 100 requests/minute prevents API abuse while allowing
   // reasonable batch processing. Each broadcast can handle 1,000 recipients,
   // so this supports up to 100,000 recipients per minute with proper batching.
   // Adjust based on your Twilio account limits and expected traffic patterns.
   
   // --- Simple API Key Authentication Hook ---
   // WARNING: This is a very basic example suitable for internal tools or demos.
   // For production systems exposed externally, implement more robust authentication
   // like OAuth 2.0 or JWT (JSON Web Tokens) verification.
   fastify.addHook('onRequest', async (request, reply) => {
     // Skip auth for health check or specific routes if needed
     if (request.routerPath === '/health') {
       return
     }
   
     // Check the 'x-api-key' header
     const apiKey = request.headers['x-api-key']
     if (!apiKey || apiKey !== fastify.config.API_SECRET_KEY) {
       fastify.log.warn('Unauthorized attempt blocked.')
       reply.code(401).send({ error: 'Unauthorized' })
       return // Stop processing the request further
     }
   })
   // --- End Authentication Hook ---
   
   // Register routes
   fastify.register(broadcastRoutes, { prefix: '/api/v1' })
   
   // Health check route with service status
   fastify.get('/health', async (request, reply) => {
     return {
       status: 'ok',
       timestamp: new Date().toISOString(),
       service: 'twilio-bulk-sms',
       version: '1.0.0'
     }
   })
   
   // Run the server
   const start = async () => {
     try {
       // Wait for plugins to be ready, especially fastify-env
       await fastify.ready()
       await fastify.listen({ port: fastify.config.PORT, host: '0.0.0.0' })
       fastify.log.info(`Server listening on port ${fastify.config.PORT}`)
     } catch (err) {
       fastify.log.error(err)
       process.exit(1)
     }
   }
   
   start()
   
   • Why this structure? It separates concerns: server setup, configuration, and route logic. Pino provides efficient logging, crucial for monitoring. fastify-env ensures configuration is loaded and validated before the server starts listening. The authentication hook provides basic protection but includes a warning about its limitations for production.

9. Add Start Script to package.json: Make it easy to run the server. Add scripts for development, production, and process management.

   json

   // package.json (scripts section)
   {
     "scripts": {
       "start": "node server.js",
       "dev": "node server.js | pino-pretty",
       "prod": "NODE_ENV=production node server.js",
       "pm2:start": "pm2 start server.js --name twilio-bulk-sms",
       "pm2:stop": "pm2 stop twilio-bulk-sms",
       "test": "echo \"Error: no test specified\" && exit 1"
     }
   }
   

   You can now start the server in development using npm run dev. For production, install PM2 globally (npm install -g pm2) and use npm run pm2:start for process management with automatic restarts.

2. Implementing Core Functionality & API Layer

Now, build the /broadcast endpoint that handles sending messages.

1. Define the Broadcast Route (src/routes/broadcast.js): This file contains the logic for the /api/v1/broadcast endpoint.

   javascript

   // src/routes/broadcast.js
   'use strict'
   
   const Twilio = require('twilio')
   
   // E.164 format validation with country code support
   // Matches: +1 (US/CA), +44 (UK), +91 (India), etc.
   // Does not validate country-specific digit counts (use libphonenumber-js for strict validation)
   const E164_REGEX = /^\+[1-9]\d{1,14}$/
   
   async function broadcastRoutes (fastify, options) {
     // Ensure config is loaded before initializing Twilio client
     await fastify.ready()
     const {
       TWILIO_ACCOUNT_SID,
       TWILIO_AUTH_TOKEN,
       TWILIO_MESSAGING_SERVICE_SID
     } = fastify.config
   
     // Initialize Twilio client once
     const twilioClient = Twilio(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN)
   
     const broadcastBodySchema = {
       type: 'object',
       required: ['message', 'recipients'],
       properties: {
         message: { type: 'string', minLength: 1, maxLength: 1600 }, // Max SMS length
         recipients: {
           type: 'array',
           minItems: 1,
           maxItems: 1000, // Adjust based on practical limits/performance
           items: {
             type: 'string',
             pattern: E164_REGEX.source // Validate E.164 format
           }
         }
       }
     }
   
     const schema = {
       body: broadcastBodySchema
     }
   
     fastify.post('/broadcast', { schema }, async (request, reply) => {
       const { message, recipients } = request.body
       const log = request.log // Use request-specific logger
   
       // Deduplicate recipients to avoid sending multiple times to the same number
       const uniqueRecipients = [...new Set(recipients)];
       const recipientsCount = uniqueRecipients.length;
   
       log.info(
         `Received broadcast request for ${recipients.length} recipients (${recipientsCount} unique).`
       )
   
       // --- Asynchronous Sending Strategy ---
       // Immediately return 202 Accepted and process sending in the background.
       // This prevents blocking the API response for potentially long-running tasks.
       // WARNING: `setImmediate` is used here for simplicity. It's suitable for demos
       // or very low volumes ONLY. It lacks robustness (no retries, potential memory
       // issues under high load) for true production environments handling thousands
       // of messages.
       // PRODUCTION REQUIREMENT: Replace this with a dedicated job queue system
       // (e.g., BullMQ + Redis, RabbitMQ, AWS SQS) for reliable background processing,
       // automatic retries, and horizontal scalability.
   
       reply.code(202).send({
         status: 'accepted',
         message: `Processing broadcast for ${recipientsCount} unique recipients. Check logs for status.`,
         recipientsCount: recipientsCount
       })
   
       // Process sending asynchronously using setImmediate (NOT PRODUCTION-READY for high volume)
       setImmediate(async () => {
         log.info(`Starting background processing of broadcast for ${recipientsCount} unique recipients...`)
         let successCount = 0
         let errorCount = 0
   
         // Use Promise.allSettled to handle individual message failures without stopping the loop
         const results = await Promise.allSettled(
           uniqueRecipients.map(async (recipient) => {
             try {
               const messageInstance = await twilioClient.messages.create({
                 body: message,
                 messagingServiceSid: TWILIO_MESSAGING_SERVICE_SID,
                 to: recipient
               })
               log.info(
                 `Message sending initiated to ${recipient}. SID: ${messageInstance.sid}`
               )
               return { recipient, status: 'fulfilled', sid: messageInstance.sid }
             } catch (error) {
               log.error(
                 `Failed to initiate message sending to ${recipient}: ${error.message}`
               )
               // Log Twilio error code if available, using optional chaining for safety
               log.error(`Twilio Error Code: ${error?.code ?? 'N/A'}`)
               return { recipient, status: 'rejected', error: error.message, errorCode: error?.code }
             }
           })
         )
   
         // Log summary results
         results.forEach(result => {
             if (result.status === 'fulfilled') {
                 successCount++;
             } else {
                 errorCount++;
             }
         });
   
         log.info(
           `Broadcast processing complete. Initiated: ${successCount}, Errors: ${errorCount}`
         )
       }) // End of setImmediate block
   
       // Note: The 'reply' has already been sent by this point.
     })
   }
   
   module.exports = broadcastRoutes
   
   • Request Validation: Fastify's schema validation automatically checks the request body. It ensures message is a non-empty string and recipients is an array of strings matching the E.164 format.
   • Deduplication: The code uses [...new Set(recipients)] to ensure each phone number is processed only once per request.
   • Asynchronous Processing: The key design choice here is to not block the HTTP request.
     • Send an immediate 202 Accepted response.
     • setImmediate schedules the sending logic to run asynchronously.
     • CRITICAL CAVEAT: As noted in the code comments and text, setImmediate is not suitable for production scale. It lacks error handling resilience (like retries) and can lead to memory issues under heavy load. A background job queue is essential for reliable production systems.
   • Promise.allSettled: Iterate over unique recipients and attempt to send a message to each, allowing processing to continue even if some attempts fail initially.
   • Logging: Detailed logging provides visibility. Error logging safely accesses error.code using error?.code.

3. Testing the API Layer

Use curl or Postman to test the /api/v1/broadcast endpoint.

1. Start the Server:

   bash

   npm run dev
   

2. Send a Test Request (curl): Replace <YOUR_NUMBER_1&gt; and <YOUR_NUMBER_2&gt; with valid phone numbers in E.164 format (e.g., +15551234567). Replace <YOUR_API_SECRET_KEY&gt; with the value from your .env file.

   bash

   curl -X POST http://localhost:3000/api/v1/broadcast \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR_API_SECRET_KEY&gt;" \
   -d '{
     "message": "Hello from Fastify & Twilio! This is a bulk test.",
     "recipients": ["<YOUR_NUMBER_1&gt;", "<YOUR_NUMBER_2&gt;", "<YOUR_NUMBER_1&gt;"]
   }'
   

3. Expected Response (JSON): You should receive an immediate 202 Accepted response. Notice recipientsCount reflects the unique count.

   json

   {
     "status": "accepted",
     "message": "Processing broadcast for 2 unique recipients. Check logs for status.",
     "recipientsCount": 2
   }
   

4. Check Server Logs: Observe the terminal where npm run dev is running. You should see logs indicating:

   • The request being received (mentioning original and unique counts).
   • The start of background processing for the unique count.
   • Success or failure logs for each unique recipient number.
   • The final summary log.

5. Check Twilio Logs: Log in to the Twilio Console and navigate to Monitor > Logs > Messaging. You should see the outgoing messages initiated by your application via the Messaging Service (one for each unique recipient). Message statuses progress through: queued → sent → delivered (or failed/undelivered if issues occur).

4. Integrating with Twilio (Recap)

You've already set up the core integration. Here are the crucial Twilio elements:

• Account SID & Auth Token (.env): Your main account credentials authenticate the twilio client. Obtain these from the Twilio Console dashboard.
• Messaging Service (.env):
  • Purpose: Acts as a container for sender numbers, provides scaling (distributes messages across the pool), handles opt-outs (STOP/UNSUBSCRIBE keywords), manages compliance (like A2P 10DLC in the US), and offers features like sticky sender and geomatch.
  • Configuration: Create via Messaging > Services. Add at least one Twilio phone number to its Sender Pool. The Messaging Service SID (starting with MG...) is used in the API call instead of a specific from number.
  • Obtaining: Find on the Messaging Service's properties page in the Console.
  • A2P 10DLC Registration (US Traffic): For sending to US phone numbers at scale, you must register your brand and campaign with The Campaign Registry (TCR) through Twilio. Unregistered traffic faces severe filtering and delivery failures. Complete registration via Messaging > Regulatory Compliance > A2P 10DLC in Twilio Console. Registration takes 1–2 weeks and costs $4/month per campaign + $4 one-time brand registration. Source: Twilio A2P 10DLC Guide (2025)
  • Throughput: Each standard phone number sends ~1 message/second. Messaging Services distribute load across multiple numbers. Add 5–10 numbers to your pool for 5–10 messages/second throughput (18,000–36,000 per hour). Toll-free numbers support higher throughput (~3 messages/second after verification). Source: Twilio Messaging Services (2025)
• Phone Number: At least one SMS-capable Twilio number added to the Messaging Service's sender pool.

5. Error Handling, Logging, and Retry Mechanisms

• Error Handling Strategy:

  • Request Validation: Fastify's schema validation handles malformed requests early.
  • Authentication: The onRequest hook rejects unauthorized requests.
  • Twilio API Errors: The try...catch block within the map function inside setImmediate catches errors during individual twilioClient.messages.create calls. Promise.allSettled ensures one failure doesn't stop others.
  • Logging: Log errors with log.error, including the recipient number, error message, and Twilio error code (if available, using error?.code).

• Logging:

  • Use pino for structured JSON logging (in production) or human-readable output (pino-pretty in development).
  • Capture key information: request IDs, timestamps, recipient counts, individual message SIDs, errors (with codes), and processing duration.
  • Log Analysis: In production, forward these JSON logs to a log aggregation service (e.g., Datadog, Splunk, ELK stack) for searching, alerting, and dashboarding. Sample queries:
    • Find all failed messages: error.message:* AND errorCode:*
    • Track specific recipient: recipient:"+15551234567"
    • Monitor error rate: errorCode:* | stats count by errorCode

• Retry Mechanisms:

  • Twilio Internal Retries: Twilio handles some network resilience internally when communicating with carriers.
  • Application-Level Retries (MISSING): The current implementation using setImmediate critically lacks any built-in mechanism to retry failed Twilio API calls (e.g., due to temporary network issues connecting to Twilio). Errors are logged, but attempts are not automatically retried.
  • Implementing Retries (Required for Production): For robust error handling, replace setImmediate with a dedicated job queue system. Job queues (like BullMQ, RabbitMQ) typically provide built-in, configurable retry mechanisms (e.g., exponential backoff). Example retry configuration with BullMQ:
  javascript

  // Example: BullMQ job configuration (requires separate implementation)
  const jobOptions = {
    attempts: 5,
    backoff: {
      type: 'exponential',
      delay: 2000 // Start with 2s, doubles each retry: 2s, 4s, 8s, 16s, 32s
    },
    removeOnComplete: true,
    removeOnFail: false
  };
  
  // Add to queue instead of setImmediate
  await messageQueue.add('send-sms', { recipient, message }, jobOptions);
  

  Avoid retrying non-recoverable errors like invalid phone numbers (Twilio error code 21211). This is a crucial step for production readiness.

• Common Twilio Error Codes to Handle:

  When implementing retry logic, distinguish between retryable and non-retryable errors:

  Non-Retryable Errors (log and skip):

  • 21211: Invalid 'To' phone number format
  • 14102: Invalid 'From' attribute
  • 14109: Invalid To phone number for Trial mode (number not verified)
  • 10002: Trial accounts do not support this feature
  • 20023: Phone number rejected by carrier provisioning API

  Retryable Errors (implement exponential backoff):

  • 14107: SMS send rate limit exceeded
  • 10001: Account is not active (temporary suspension)
  • 20003: Permission Denied (may be temporary)

  Account/Permission Errors (requires manual intervention):

  • 20005: Account not active
  • 20006: Access Denied
  • 14108: From phone number not SMS capable

  Source: Twilio Error Codes (2025)

6. Database Schema and Data Layer (Conceptual)

While this guide focuses on the core API, a production system often requires persistence for tracking and auditing.

• Why a Database?

  • Track the status of each broadcast job (pending, processing, completed, failed).
  • Store results for each recipient (initiated, sent, failed, Twilio SID, error message).
  • Audit trails.
  • Enable querying past broadcasts.
  • Database Selection: Use PostgreSQL or MySQL for transactional consistency and complex queries (recommended for most use cases). Use MongoDB for flexible schemas and high write throughput. For serverless deployments, consider Amazon DynamoDB or Firebase Firestore. Scale consideration: 100,000+ messages/day requires proper indexing and possibly read replicas.

• Conceptual Schema (using Prisma syntax as an example):

  sql

  // schema.prisma (Example)
  
  model BroadcastJob {
    id                String            @id @default(cuid())
    createdAt         DateTime          @default(now())
    message           String
    status            String            @default("pending") // pending, processing, completed, failed
    totalRecipients   Int // Number of unique recipients requested
    successCount      Int               @default(0) // Count of messages successfully accepted by Twilio
    errorCount        Int               @default(0) // Count of errors during API calls
    recipientStatuses RecipientStatus[] // Relation to individual recipient statuses
    deliveredCount    Int               @default(0) // Count of messages confirmed delivered (from webhooks)
    failedCount       Int               @default(0) // Count of messages confirmed failed (from webhooks)
  }
  
  model RecipientStatus {
    id             String        @id @default(cuid())
    broadcastJobId String
    broadcastJob   BroadcastJob  @relation(fields: [broadcastJobId], references: [id])
    phoneNumber    String
    // Status reflects both API call and delivery status
    status         String        @default("pending") // pending, accepted_by_twilio, delivered, failed_api_call, failed_delivery
    twilioSid      String? // SID of the message if API call successful
    errorMessage   String? // Error message if API call failed
    errorCode      Int? // Twilio error code if API call failed
    processedAt    DateTime?
    deliveredAt    DateTime? // Timestamp when delivery confirmed via webhook
  
    @@index([broadcastJobId])
    @@index([phoneNumber]) // Useful for querying status for a specific number
    @@index([twilioSid]) // Index for webhook lookups
  }
  

• Implementation:

  • Use an ORM like Prisma or Sequelize.
  • Before initiating background processing (e.g., adding to a job queue), create a BroadcastJob record in the database with status: 'processing'.
  • Inside the background processor (the setImmediate block or, preferably, a job queue worker), update the corresponding RecipientStatus record for each outcome (success/failure, SID, error).
  • After processing all recipients, update the main BroadcastJob record with status: 'completed' and the final counts.
  • Implement database migrations to manage schema changes.
  • Webhook Endpoint: Create a /webhooks/status endpoint to receive Twilio delivery status callbacks, updating RecipientStatus records with final delivery confirmation.

• This guide omits DB integration for brevity, focusing purely on the Fastify/Twilio interaction.

7. Security Features

• Input Validation: Handled by Fastify's schema validation in the route definition. Ensures message exists and recipients are correctly formatted (E.164 strings) and within size limits. Prevents basic injection risks and ensures data integrity.

• Authentication: Implemented using a simple API Key check (X-API-Key header) in the onRequest hook.

  • WARNING: This method is not recommended for sensitive applications or public-facing APIs. It's vulnerable if the key is exposed.
  • Production Improvement: Use stronger authentication mechanisms. For OAuth 2.0, implement with @fastify/oauth2 plugin. For JWT, use @fastify/jwt plugin:
  javascript

  // Example JWT setup (requires separate implementation)
  fastify.register(require('@fastify/jwt'), {
    secret: process.env.JWT_SECRET
  });
  
  fastify.addHook('onRequest', async (request, reply) => {
    try {
      await request.jwtVerify();
    } catch (err) {
      reply.send(err);
    }
  });
  

  Store secrets in AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault for production.

• Authorization: Currently, any valid API key grants full access. Implement role-based access control (RBAC) if different users/systems require varying permissions (e.g., only admins can broadcast).

• Rate Limiting: Implemented using fastify-rate-limit.

  • Purpose: Protects the API from abuse (intentional or accidental), prevents resource exhaustion, and helps manage costs.
  • Configuration: The max and timeWindow options in server.js control the limit. Adjust these based on expected usage and capacity.
  • Per-User Rate Limiting: Configure per API key limits using the plugin's keyGenerator option:
  javascript

  // Example per-user rate limiting (requires separate implementation)
  fastify.register(require('@fastify/rate-limit'), {
    max: 100,
    timeWindow: '1 minute',
    keyGenerator: (request) => request.headers['x-api-key'] || request.ip
  });
  

• Secrets Management: API keys and Twilio credentials are stored in .env and loaded securely. Ensure .env is never committed to Git. Use platform-specific secret management tools (like AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) in production environments.

• Common Vulnerabilities: Keep dependencies updated (npm audit fix) to patch known vulnerabilities. The schema validation provides a layer of defense against injection attacks targeting the expected data structure.

8. Handling Special Cases

• E.164 Phone Number Format: Enforced via regex in the schema (^\+[1-9]\d{1,14}$). This is Twilio's required format. Ensure client applications sending requests adhere to this. For robust phone number validation and normalization, use the libphonenumber-js library:

  javascript

  // Example phone number normalization (requires libphonenumber-js)
  const { parsePhoneNumber } = require('libphonenumber-js');
  
  function normalizePhoneNumber(input, defaultCountry = 'US') {
    try {
      const phoneNumber = parsePhoneNumber(input, defaultCountry);
      return phoneNumber.format('E.164'); // Returns +15551234567
    } catch (error) {
      throw new Error(`Invalid phone number: ${input}`);
    }
  }
  

• SMS Character Limits & Segmentation: A single SMS segment has specific limits based on encoding:

  • GSM-7 encoding: 160 characters for a single message, 153 characters per segment for multi-part messages.
  • UCS-2/Unicode encoding: 70 characters for a single message, 67 characters per segment for multi-part messages.
  • Toll-free SMS to US/Canada: GSM-7 uses 152 characters per segment; UCS-2 uses 66 characters per segment.

  Twilio automatically handles segmentation for longer messages, sending them as multiple parts that are reassembled on the recipient's handset. Twilio recommends keeping messages under 320 characters for best deliverability, and supports messages up to 1,600 characters across messaging channels. Be mindful that sending multi-segment messages costs more (charged per segment). The schema limits the message length to 1,600 characters (approximately 10 segments) as a practical upper bound. Use Twilio's Message Segment Calculator to understand encoding and segment impacts for frequently sent messages.

  Cost Examples:

  • 160-character message (1 segment): $0.0079 USD (US domestic)
  • 320-character message (3 segments): $0.0237 USD (US domestic)
  • 1,000-character message (7 segments): $0.0553 USD (US domestic)

  Source: Twilio SMS Character Limit (2025)

• Opt-Out Handling: Twilio Messaging Services handle standard English opt-out keywords (STOP, UNSUBSCRIBE, CANCEL, END, QUIT) automatically. When a user replies with one of these, Twilio prevents further messages from that specific Messaging Service to that user. You don't need to implement this logic yourself, but you should inform users of how to opt out. You can configure custom opt-out keywords and responses within the Messaging Service settings in the Twilio Console. Database Sync: Configure Twilio webhooks at Messaging > Services > [Your Service] > Integration to send opt-out events to your /webhooks/optout endpoint. Update your user database to mark opted-out recipients and filter them from future broadcasts.

• Duplicate Recipients: The code now handles duplicate recipients by using [...new Set(recipients)] in src/routes/broadcast.js before initiating the sending process. This ensures efficiency and avoids unnecessary costs.

• International Messaging: Twilio supports global messaging, but ensure your account has permissions enabled for the countries you intend to send to (check Console > Messaging > Settings > Geo-permissions). Be aware of country-specific regulations:

  • India: Requires DLT registration for commercial messaging
  • China: Restricted; requires special approval
  • Germany: Requires sender registration for promotional content
  • Brazil: Toll-free numbers not supported; use local long codes

  Cost differences vary significantly (e.g., US: $0.0079, UK: $0.0582, India: $0.0073 per segment). Source: Twilio International Messaging (2025)

9. Performance Optimizations

• Asynchronous Processing: Using a background job queue (instead of the demo setImmediate) is the most critical performance and reliability optimization for handling bulk sends without blocking the API. Queue Comparison:

  Solution	Best For	Throughput	Complexity	Cost
  BullMQ + Redis	High volume, robust retries	10,000+ msgs/min	Medium	$20–$50/mo (Redis)
  AWS SQS	Serverless, AWS-native	5,000+ msgs/min	Low	Pay-per-use ($0.40/million)
  RabbitMQ	Complex routing, enterprise	8,000+ msgs/min	High	Self-hosted or $100+/mo

• Twilio Messaging Service: Using a Messaging Service is crucial for scaling throughput beyond the 1 message per second limit of a single standard Twilio number. Twilio distributes the load across the numbers in the service pool. Scaling Thresholds:

  • 1–3 numbers: 3,600–10,800 messages/hour (1–3 msgs/sec)
  • 5–10 numbers: 18,000–36,000 messages/hour (5–10 msgs/sec)
  • 20+ numbers: 72,000+ messages/hour (20+ msgs/sec)
  • Toll-free verified: 10,800+ messages/hour per number (~3 msgs/sec each)

  Add more numbers to the pool as volume increases. Monitor queue depth and error rates to determine when to scale.

• Payload Size: Keep the request payload reasonable. The schema limits recipients to 1,000 per request – adjust based on testing, typical batch sizes, and memory constraints. Very large arrays increase memory usage during initial processing. Consider batching large lists on the client-side if necessary.

• Twilio Client Initialization: The twilioClient is initialized once when the route is set up, avoiding redundant object creation per request.

• Load Testing: Use tools like k6 (k6.io) or autocannon (npm install -g autocannon) to simulate concurrent requests and identify bottlenecks in your API, background processing, or infrastructure.

  bash

  # Example using autocannon (install first)
  autocannon -c 10 -d 10 -p 1 -m POST \
    -H "Content-Type=application/json" \
    -H "X-API-Key=<YOUR_API_SECRET_KEY&gt;" \
    -b '{"message": "Load test message", "recipients": ["+15551112222"]}' \
    http://localhost:3000/api/v1/broadcast
  

  Expected Baseline Performance: A well-configured Fastify API on 2 CPU cores should handle 500–1,000 requests/second for the /broadcast endpoint. Actual message throughput depends on Twilio account limits and sender pool size.

• Node.js Performance: Ensure you are using an LTS version of Node.js. Profile your application using Node's built-in profiler (node --prof) or tools like Clinic.js (npm install -g clinic) if you suspect CPU or memory bottlenecks, especially within the background processing logic.

10. Monitoring, Observability, and Analytics

• Health Checks: The /health endpoint provides a basic check that the server is running and responsive. Monitoring tools should poll this endpoint regularly.

• Logging (Recap): Structured JSON logs are essential. Ensure they capture key information: request IDs, timestamps, recipient counts, individual message SIDs, errors (with codes), and processing duration. Forward logs to a centralized system.

• Metrics: Track key performance indicators (KPIs):

  • API request rate and latency (especially for /broadcast).
  • Error rates (API errors, Twilio API errors).
  • Background job queue depth and processing time (if using a queue).
  • Number of messages initiated vs. failed.
  • Use tools like Prometheus/Grafana or Datadog APM. Fastify plugins like fastify-metrics can help expose Prometheus metrics. Example Metrics to Track:
    • http_requests_total{method="POST", route="/broadcast", status="202"} – total broadcasts accepted
    • twilio_messages_sent_total{status="success"} – successful Twilio API calls
    • twilio_messages_sent_total{status="error"} – failed Twilio API calls
    • broadcast_processing_duration_seconds – time to process each batch

• Twilio Console Monitoring: Regularly check the Twilio Console (Monitor > Logs > Messaging) for message statuses (sent, delivered, undelivered, failed), error codes, and cost insights. Use Twilio Insights for deeper analytics on deliverability and engagement.

• Alerting: Set up alerts based on logs and metrics:

  • High API error rates (>5% of requests).
  • High Twilio error rates (>10% of messages).
  • Specific error codes indicating configuration issues (e.g., 14108, 20005).
  • Job queue depth exceeding threshold (e.g., >1,000 pending jobs).
  • Health check failures.
  • Sudden spikes or drops in message volume (>50% deviation).

  Example PagerDuty Alert Configuration:

  json

  {
    "alert_name": "High Twilio Error Rate",
    "condition": "twilio_errors > 100 in 5 minutes",
    "severity": "critical",
    "notification_channels": ["pagerduty", "slack"]
  }
  

• SLA Targets: Establish service-level agreements for production:

  • API availability: 99.9% uptime (43 minutes downtime/month max)
  • API latency: p95 < 200 ms_ p99 < 500 ms
  • Message delivery success rate: >98%
  • Time to first message sent: <5 seconds after API acceptance

  Define incident response procedures: on-call rotation, escalation paths, and post-mortem templates.