Complete Guide: Sending Bulk SMS Marketing Campaigns with Plivo (Node.js, Express)

This guide walks you through building a production-ready SMS marketing campaign system using Plivo's SMS API, Node.js, and Express. You'll learn everything from initial project setup to deployment, monitoring, and handling real-world complexities like bulk messaging, TCPA compliance, and rate limiting.

Note: This guide uses the Express framework. You can adapt these concepts and Plivo integration patterns for Next.js API routes and Supabase for data persistence (covered in Section 6).

By the end of this tutorial, you'll have a functional marketing automation application that sends targeted SMS messages, handles replies, and manages campaign data – built with scalability, security, and reliability in mind.

Project Overview and Goals

What You'll Build:

A Node.js application using Express that enables you to define and execute SMS marketing campaigns via Plivo's API. Your system will:

1. Accept campaign details (message content, recipient list).
2. Send SMS messages reliably via Plivo.
3. Handle incoming replies using Plivo webhooks (optional).
4. Store campaign and recipient status data (initially in memory, with guidance for database integration in production).
5. Provide a basic API structure for frontend integration.

Problem This Solves:

Automating bulk SMS messages for marketing or notifications provides a more scalable and manageable solution than manual sending. It establishes a foundation for tracking campaign effectiveness and handling customer responses.

Compliance Is Critical:

SMS marketing is heavily regulated. Your application must comply with:

• TCPA (Telephone Consumer Protection Act): Obtain express written consent from recipients for promotional messages. Consent must be specific to your business (FCC December 2023 ruling).
• CTIA Guidelines: Follow industry best practices enforced by carriers. Never send SHAFT content (Sex, Hate, Alcohol, Firearms, Tobacco) – violations result in immediate bans.
• Opt-out mechanism: Let recipients opt out via "STOP" keyword, processed within seconds.
• Time restrictions: Send messages between 8 AM and 9 PM local time only (messages outside these hours are intrusive).
• Disclosure requirements: Identify your business, explain message frequency, and include "Msg&Data rates may apply."

Technologies You'll Use:

• Node.js: JavaScript runtime with asynchronous, event-driven architecture – ideal for I/O-heavy tasks like API interactions and webhook handling.
• Express.js: Minimal, flexible Node.js web framework that simplifies API and webhook creation.
• Plivo Node.js SDK (v4.74.0+): Simplifies interaction with Plivo REST API for sending SMS and handling responses. Actively maintained on npm and GitHub.
• Plivo: Cloud communications platform providing SMS API services, phone numbers, and webhook capabilities.
• dotenv: Manages environment variables securely.
• ngrok (development): Exposes your local development server to the internet for testing Plivo webhooks.

System Architecture:

Your system follows this flow:

• A user or client sends an API request with campaign details to your Node.js/Express API.
• Your Node.js/Express API sends an SMS request to the Plivo API.
• Plivo sends the SMS to the recipient's phone.
• If the recipient replies via SMS, Plivo receives the reply.
• Plivo sends an incoming SMS webhook notification to your Node.js/Express webhook endpoint.
• Both your main API and webhook endpoint interact with a data store (initially in-memory, ideally a database) to store and retrieve campaign and message status information.

Prerequisites for Building Plivo SMS Marketing Campaigns

Before you start building your SMS marketing system, ensure you have:

• Node.js and npm (or yarn) installed.
• A Plivo account (Sign up for free).
• A Plivo phone number with SMS capability (purchase via the Plivo console). Trial accounts have limitations (e.g., sending only to verified numbers).
• Basic understanding of JavaScript, Node.js, and REST APIs.
• ngrok installed for local webhook testing (Download ngrok).

Step 1: Initialize Your Node.js SMS Marketing Project

Initialize your Node.js project and install the necessary dependencies.

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

   bash

   mkdir plivo-marketing-campaign
   cd plivo-marketing-campaign
   

2. Initialize Node.js Project: Create a package.json file to manage dependencies and project metadata.

   bash

   npm init -y
   

3. Install Dependencies: Install Express for the web server, the Plivo SDK, dotenv for environment variables, and body-parser for parsing request bodies. Add nodemon for development – it automatically restarts the server on file changes.

   bash

   npm install express plivo dotenv body-parser
   npm install --save-dev nodemon
   

4. Configure nodemon (Optional but Recommended): Add a script to your package.json for easy development server startup. Open package.json and add/modify the scripts section:

   json

   // package.json
   {
     // ... other properties
     ""scripts"": {
       ""start"": ""node index.js"", // For production
       ""dev"": ""nodemon index.js""   // For development
     },
     // ... other properties
   }
   

   You can now run npm run dev to start the server with automatic restarts.

5. Set up Environment Variables: Create a file named .env in the project root. This file will store sensitive credentials and configurations. Never commit this file to version control.

   bash

   # .env
   
   # Plivo Credentials (Get from Plivo Console > API > Keys & Tokens)
   PLIVO_AUTH_ID=YOUR_PLIVO_AUTH_ID
   PLIVO_AUTH_TOKEN=YOUR_PLIVO_AUTH_TOKEN
   
   # Plivo Number (Must be SMS enabled and in E.164 format, e.g., +14155551212)
   PLIVO_SENDER_ID=YOUR_PLIVO_PHONE_NUMBER
   
   # Server Configuration
   PORT=3000
   
   # Base URL for Webhooks (Use ngrok URL during development)
   BASE_URL=YOUR_NGROK_OR_DEPLOYMENT_URL
   
   • PLIVO_AUTH_ID / PLIVO_AUTH_TOKEN: Find these on your Plivo Console dashboard under ""API -> Keys & Tokens"".
   • PLIVO_SENDER_ID: The Plivo phone number you purchased or will use for sending messages, in E.164 format (e.g., +12025551234). For countries outside the US/Canada, you might use an Alphanumeric Sender ID if registered and approved by Plivo.
   • PORT: The port your Express server will listen on.
   • BASE_URL: The publicly accessible URL where your application will be hosted. During development, this will be your ngrok forwarding URL.

6. Create Basic Project Structure: Organize your code for better maintainability.

   plivo-marketing-campaign/
   ├── .env
   ├── .gitignore
   ├── index.js
   ├── package.json
   ├── config/
   │   └── plivo.js
   ├── routes/
   │   ├── campaign.js
   │   └── webhooks.js
   └── services/
       └── campaignService.js
   

7. Configure .gitignore: Create a .gitignore file in the root directory to prevent sensitive files and unnecessary directories from being committed to Git.

   # .gitignore
   
   # Dependencies
   node_modules/
   
   # Environment variables
   .env
   
   # Logs
   logs/
   *.log
   npm-debug.log*
   yarn-debug.log*
   yarn-error.log*
   
   # OS generated files
   .DS_Store
   Thumbs.db
   

8. Initialize Plivo Client: Create a file to encapsulate the Plivo client initialization using the environment variables.

   javascript

   // config/plivo.js
   require('dotenv').config();
   const plivo = require('plivo');
   
   const client = new plivo.Client(
       process.env.PLIVO_AUTH_ID,
       process.env.PLIVO_AUTH_TOKEN
   );
   
   module.exports = client;
   

   > Why: Centralizing the client creation makes it easy to manage and reuse throughout the application. Using dotenv.config() loads the variables from .env.

9. Create Main Application File (index.js): Set up the basic Express server.

   javascript

   // index.js
   require('dotenv').config(); // Load environment variables first
   const express = require('express');
   const bodyParser = require('body-parser');
   
   const campaignRoutes = require('./routes/campaign');
   const webhookRoutes = require('./routes/webhooks');
   
   const app = express();
   const PORT = process.env.PORT || 3000;
   
   // Middleware
   app.use(bodyParser.json()); // Parse JSON bodies
   app.use(bodyParser.urlencoded({ extended: true })); // Parse URL-encoded bodies
   
   // Basic Health Check Route
   app.get('/health', (req, res) => {
       res.status(200).send('OK');
   });
   
   // Mount Routers
   app.use('/api/campaigns', campaignRoutes); // Routes for campaigns
   app.use('/webhooks', webhookRoutes);       // Routes for incoming webhooks
   
   // Global Error Handler (Basic) - More robust handling in Section 5
   app.use((err, req, res, next) => {
       console.error(err.stack);
       res.status(500).send('Something broke!');
   });
   
   // Start Server
   app.listen(PORT, () => {
       console.log(`Server running on port ${PORT}`);
       console.log(`Make sure BASE_URL in .env is set correctly for webhooks.`);
       if (!process.env.BASE_URL && process.env.NODE_ENV !== 'production') {
           console.warn('WARN: BASE_URL environment variable is not set. Webhooks may not function correctly.');
       } else {
           console.log(`Webhook base URL: ${process.env.BASE_URL}`);
       }
   });
   
   // Export app for potential testing
   module.exports = app;
   

   > Why: This sets up the core Express application, includes necessary middleware for parsing request bodies, defines a basic health check, mounts routers for different functionalities, includes a simple error handler, and starts the server listening on the configured port.

You now have a structured project ready for implementing the core campaign logic.

2. Install Plivo SMS API SDK and Dependencies

We'll focus on the service layer responsible for sending the campaign messages.

1. Define Campaign Service Logic: Create the services/campaignService.js file. This service will take campaign details and send messages via Plivo. For now, we'll use an in-memory store for simplicity, but structure it for potential database integration later.

   > Note: The in-memory store used here is not suitable for production; Section 6 outlines database integration.

   javascript

   // services/campaignService.js
   const plivoClient = require('../config/plivo');
   
   // In-memory store for campaign status (Replace with DB in production - see Section 6)
   const campaignStore = {}; // { campaignId: { status: 'processing' | 'completed' | 'failed', results: [] } }
   
   /**
    * Sends SMS messages for a campaign.
    * @param {string} campaignId - A unique identifier for the campaign.
    * @param {string[]} recipients - Array of phone numbers in E.164 format.
    * @param {string} message - The text message content.
    * @returns {Promise<object&gt;} - Promise resolving to campaign results.
    */
   async function sendCampaign(campaignId, recipients, message) {
       const senderId = process.env.PLIVO_SENDER_ID;
       if (!senderId) {
           throw new Error('PLIVO_SENDER_ID environment variable is not set.');
       }
   
       console.log(`Starting campaign ${campaignId} to ${recipients.length} recipients.`);
       campaignStore[campaignId] = { status: 'processing', results: [] };
   
       // --- Production Consideration: Rate Limiting & Queuing ---
       // **Plivo Rate Limits (Official Documentation):**
       // - **API Concurrency**: Default limit of 100 simultaneous requests
       // - **Account-level MPS**: Messages throttled based on configured messages-per-second (MPS) rate
       // - **Error 429**: If you exceed limits, Plivo responds with HTTP 429 "Too Many Requests" - messages are NOT lost, they're queued
       // - **Smart Queue**: Messages dequeued based on source type and destination country
       // - **Number Pooling**: For higher throughput, distribute traffic across multiple Plivo numbers
       // 
       // **Implementation Options:**
       // 1. Use a message queue (RabbitMQ, Redis Queue, Bull) - recommended for production (see Section 9)
       // 2. Implement rate limiting (e.g., 1-10 messages per second depending on your account MPS)
       // 3. Add exponential backoff retry logic for 429 errors
       // 
       // This basic example sends sequentially with minimal delay for demonstration.
       // -----------------------------------------------------------
   
       for (const recipient of recipients) {
           try {
               // Basic validation (More robust validation needed)
               if (!/^\+\d{1,15}$/.test(recipient)) {
                  console.warn(`Skipping invalid recipient format: ${recipient}`);
                  campaignStore[campaignId].results.push({ recipient, status: 'invalid_format' });
                  continue;
               }
   
               console.log(`Sending message to ${recipient}...`);
               const response = await plivoClient.messages.create(
                   senderId,
                   recipient,
                   message,
                   {
                       // Optional: Configure webhook URL for delivery status reports
                       // url: `${process.env.BASE_URL}/webhooks/status`,
                       // method: 'POST'
                   }
               );
   
               console.log(`Message sent to ${recipient}, UUID: ${response.messageUuid[0]}`);
               campaignStore[campaignId].results.push({
                   recipient,
                   status: 'sent',
                   messageUuid: response.messageUuid[0],
               });
   
               // Add a small delay to avoid hitting API rate limits too quickly (adjust as needed)
               await new Promise(resolve =&gt; setTimeout(resolve, 200)); // 200ms delay
   
           } catch (error) {
               console.error(`Failed to send message to ${recipient}:`, error.message);
               campaignStore[campaignId].results.push({
                   recipient,
                   status: 'failed',
                   error: error.message,
               });
               // Decide if one failure should stop the whole campaign or just log and continue
           }
       }
   
       campaignStore[campaignId].status = 'completed'; // Or 'partial_failure' if some failed
       console.log(`Campaign ${campaignId} finished processing.`);
       return campaignStore[campaignId];
   }
   
   /**
    * Retrieves the status of a campaign.
    * @param {string} campaignId - The ID of the campaign.
    * @returns {object | null} - Campaign status or null if not found.
    */
   function getCampaignStatus(campaignId) {
       return campaignStore[campaignId] || null;
   }
   
   
   module.exports = {
       sendCampaign,
       getCampaignStatus,
   };
   

   > Why: This isolates the logic for interacting with Plivo and managing campaign state. It uses the configured Plivo client, iterates through recipients (with basic validation and delay), calls plivoClient.messages.create, and stores results in memory. It includes crucial comments about rate limiting, queuing, and the need for a database for production readiness. The getCampaignStatus function provides a way to check progress.

3. Building a Complete API Layer

Now, let's create the Express routes to expose our campaign functionality.

1. Create Campaign Routes File: Define the endpoints for creating and checking campaigns in routes/campaign.js.

   javascript

   // routes/campaign.js
   const express = require('express');
   const { sendCampaign, getCampaignStatus } = require('../services/campaignService');
   const { v4: uuidv4 } = require('uuid'); // For generating unique campaign IDs
   
   const router = express.Router();
   
   // POST /api/campaigns - Start a new campaign
   router.post('/', async (req, res, next) => {
       const { recipients, message } = req.body;
   
       // --- Input Validation (Basic) ---
       // Add more robust validation (e.g., using express-validator - see Section 7) in production
       > **Input Validation (Basic):**
       > Add more robust validation (e.g., using `express-validator` - see Section 7) in production.
       if (!Array.isArray(recipients) || recipients.length === 0) {
           return res.status(400).json({ error: 'Recipients must be a non-empty array.' });
       }
       if (typeof message !== 'string' || message.trim() === '') {
           return res.status(400).json({ error: 'Message must be a non-empty string.' });
       }
       // ---------------------------------
   
       const campaignId = uuidv4(); // Generate a unique ID for this campaign
   
       try {
           // Start sending asynchronously, don't wait for completion here
           sendCampaign(campaignId, recipients, message)
               .then(results => console.log(`Campaign ${campaignId} processing complete.`))
               .catch(error => console.error(`Error processing campaign ${campaignId}:`, error));
   
           // Immediately respond to the client
           res.status(202).json({
               message: 'Campaign accepted for processing.',
               campaignId: campaignId,
               statusUrl: `/api/campaigns/${campaignId}/status`, // URL to check status
           });
       } catch (error) {
           next(error); // Pass error to global error handler
       }
   });
   
   // GET /api/campaigns/:campaignId/status - Check campaign status
   router.get('/:campaignId/status', (req, res) => {
       const { campaignId } = req.params;
       const status = getCampaignStatus(campaignId);
   
       if (status) {
           res.status(200).json(status);
       } else {
           res.status(404).json({ error: 'Campaign not found.' });
       }
   });
   
   module.exports = router;
   

   > Why: This sets up two endpoints: > * POST /api/campaigns: Takes a list of recipients and a message. It performs basic validation, generates a unique campaignId (using uuid), initiates the sendCampaign service asynchronously (so the API responds quickly), and returns a 202 Accepted status with the campaignId and a URL to check the status. > * GET /api/campaigns/:campaignId/status: Allows checking the progress/results using the campaignId.

   Install uuid: This code uses the uuid package to generate unique IDs. Install it:

   bash

   npm install uuid
   

2. Testing with curl: Start your server: npm run dev

   • Send a Campaign: Replace the placeholder numbers +1SANDBOXNUMBER1 and +1SANDBOXNUMBER2 with actual phone numbers verified in your Plivo Sandbox account. Remember trial accounts can only send to verified numbers.

     bash

     curl -X POST http://localhost:3000/api/campaigns \
          -H 'Content-Type: application/json' \
          -d '{
                ""recipients"": [""+1SANDBOXNUMBER1"", ""+1SANDBOXNUMBER2""],
                ""message"": ""Hello from our Node.js campaign!""
              }'
     

     You should receive a response like:

     json

     {
       ""message"": ""Campaign accepted for processing."",
       ""campaignId"": ""some-unique-uuid-string"",
       ""statusUrl"": ""/api/campaigns/some-unique-uuid-string/status""
     }
     

   • Check Status: Use the campaignId from the previous response.

     bash

     curl http://localhost:3000/api/campaigns/some-unique-uuid-string/status
     

     Initially, it might show {""status"":""processing"",""results"":[]}. After a short while, it should show {""status"":""completed"", ""results"": [...]} with details for each recipient.

4. Integrating with Third-Party Services (Plivo Webhooks)

To handle replies or delivery reports, we need to configure Plivo to send HTTP requests (webhooks) to our application.

1. Start ngrok: If your server is running locally on port 3000, expose it to the internet:

   bash

   ngrok http 3000
   

   ngrok will display a forwarding URL (e.g., https://<unique-subdomain&gt;.ngrok.io). Copy the https version.

2. Update .env: Set the BASE_URL in your .env file to your ngrok forwarding URL. Restart your Node.js server after changing .env.

   bash

   # .env
   # ... other variables
   BASE_URL=https://<your-unique-subdomain&gt;.ngrok.io
   

3. Configure Plivo Application:

   • Go to your Plivo Console: https://console.plivo.com/
   • Navigate to Messaging -> Applications -> XML.
   • Click Add New Application.
   • Give it a name (e.g., ""Node Marketing Campaign App"").
   • Message URL: Enter your webhook endpoint URL: ${BASE_URL}/webhooks/inbound-sms. For example: https://<your-unique-subdomain&gt;.ngrok.io/webhooks/inbound-sms.
   • Method: Set to POST.
   • Optional Delivery Report URL: You can set a similar URL (e.g., ${BASE_URL}/webhooks/status) if you want delivery status updates. Set method to POST.
   • Click Create Application.
   • Alternatively, if you only plan to use the Message URL and Delivery Report URL and won't be sending back dynamic XML responses from your webhook, Plivo's generic ""Messaging Application"" type might also suffice, depending on current Plivo UI options.

4. Assign Application to Plivo Number:

   • Navigate to Phone Numbers -> Your Numbers.
   • Click on the Plivo number you are using as PLIVO_SENDER_ID.
   • In the ""Application Type"" section, select XML Application (or Messaging Application if you chose that type).
   • From the ""Plivo Application"" dropdown, choose the application you just created (""Node Marketing Campaign App"").
   • Click Update Number.

5. Create Webhook Routes File: Define the endpoint to handle incoming SMS messages in routes/webhooks.js.

   javascript

   // routes/webhooks.js
   const express = require('express');
   const plivo = require('plivo');
   const plivoClient = require('../config/plivo'); // Only if you need to send a reply via API
   
   const router = express.Router();
   
   // POST /webhooks/inbound-sms - Handles incoming SMS from Plivo
   router.post('/inbound-sms', (req, res) => {
       const fromNumber = req.body.From;
       const toNumber = req.body.To; // Your Plivo number
       const text = req.body.Text;
       const messageUuid = req.body.MessageUUID;
   
       console.log(`\n--- Incoming SMS ---`);
       console.log(`From: ${fromNumber}`);
       console.log(`To:   ${toNumber}`);
       console.log(`Text: ${text}`);
       console.log(`UUID: ${messageUuid}`);
       console.log(`--------------------\n`);
   
       // --- Business Logic for Replies ---
       > **Business Logic for Replies:**
       > 1. Check for keywords like STOP, UNSUBSCRIBE, HELP (See Section 6 & 8).
       > 2. Store the reply associated with the original campaign/recipient (requires DB - see Section 6).
       > 3. Trigger alerts or forward messages if needed.
   
       // --- Option 1: Acknowledge Receipt (No Reply Sent Back) ---
       > **Option 1: Acknowledge Receipt (No Reply Sent Back)**
       > Plivo expects a 200 OK response to acknowledge receipt. If you don't send specific XML, Plivo does nothing further.
       res.status(200).send('Webhook received.');
   
       /* --- Option 2: Send an Auto-Reply using Plivo XML ---
          > **Option 2: Send an Auto-Reply using Plivo XML**
          > If you want to send an immediate reply, Plivo expects specific XML. Uncomment the code below to enable auto-reply.
   
          const response = plivo.Response();
          const replyText = 'Thanks for your message! We received it.';
          const params = {
              src: toNumber, // Reply FROM your Plivo number
              dst: fromNumber // Reply TO the sender
          };
          response.addMessage(replyText, params);
   
          res.set('Content-Type', 'text/xml');
          res.send(response.toXML());
          console.log('Sent auto-reply XML.');
       */
   
       /* --- Option 3: Send a Reply Later using the API (Requires More Logic) ---
          > **Option 3: Send a Reply Later using the API (Requires More Logic)**
          > You might process the message and decide to send a reply later using `plivoClient.messages.create(...)` similar to the outbound campaign. In this case, just send the 200 OK now (Option 1).
       */
   });
   
   // Optional: Endpoint for Delivery Status Reports
   router.post('/status', (req, res) => {
       const status = req.body.Status;
       const messageUuid = req.body.MessageUUID;
       const recipient = req.body.To; // The end recipient number
   
       console.log(`\n--- Delivery Status ---`);
       console.log(`UUID:   ${messageUuid}`);
       console.log(`To:     ${recipient}`);
       console.log(`Status: ${status}`); // e.g., 'sent', 'delivered', 'failed', 'undelivered'
       console.log(`---------------------\n`);
   
       // --- Business Logic for Status ---
       > **Business Logic for Status:**
       > Update the status of the specific message in your database using the `messageUuid` (See Section 6).
   
       res.status(200).send('Status webhook received.');
   });
   
   
   module.exports = router;
   

   > Why: This file defines the /webhooks/inbound-sms endpoint. When Plivo receives an SMS to your configured number, it POSTs data (like sender number, message text) to this URL. The code logs the incoming message details. It shows different options for responding: simply acknowledging receipt (required), sending an immediate XML-based auto-reply, or handling it for a later API-based reply. An optional /status endpoint demonstrates handling delivery reports.

6. Testing Webhooks:

   • Ensure ngrok is running and BASE_URL is set correctly in .env.
   • Restart your Node server (npm run dev).
   • Send an SMS message from a mobile phone to your Plivo number.
   • Check your Node.js console logs. You should see the ""Incoming SMS"" details printed. If you uncommented the auto-reply XML, your mobile phone should receive the reply.

5. Implementing Proper Error Handling, Logging, and Retry Mechanisms

Production systems need robust error handling and logging.

1. Consistent Error Handling Strategy:

   • Use try...catch blocks for asynchronous operations (API calls, DB interactions).
   • In route handlers, pass errors to the next function (next(error);).
   • Create a more informative global error handler in index.js.
   javascript

   // index.js (replace the basic error handler)
   
   // Global Error Handler (Improved)
   app.use((err, req, res, next) => {
       // Use the logger if configured (see below), otherwise console.error
       const logger = require('./config/logger'); // Assuming Winston setup from step 2
       logger ? logger.error('Unhandled Error:', { error: err.message, stack: err.stack }) : console.error('Unhandled Error:', err);
   
       // Respond with a generic error message in production
       // In development, you might want to send more details
       const statusCode = err.statusCode || 500; // Use specific status code if available
       const message = process.env.NODE_ENV === 'production' ? 'Internal Server Error' : err.message;
   
       // Log specific Plivo API errors if possible
       if (err.message && err.message.includes('Plivo API error')) {
           // Log potentially useful Plivo details
           logger ? logger.error('Plivo Specific Error Details:', { error: err }) : console.error('Plivo Specific Error Details:', err);
       }
   
       res.status(statusCode).json({
           status: 'error',
           message: message,
           // Optionally include stack trace in development
           ...(process.env.NODE_ENV !== 'production' && { stack: err.stack })
       });
   });
   

2. Logging:

   • For simple applications, console.log, console.warn, console.error might suffice initially.
   • For production, use a dedicated logging library like winston or pino for structured logging (JSON format), log levels (info, warn, error, debug), and outputting to files or log management services.

   Install winston:

   bash

   npm install winston
   

   Example using winston:

   javascript

   // config/logger.js (New file)
   const winston = require('winston');
   
   const logger = winston.createLogger({
     level: process.env.LOG_LEVEL || 'info', // Control log level via env var
     format: winston.format.combine(
       winston.format.timestamp(),
       winston.format.errors({ stack: true }), // Log stack traces
       winston.format.json() // Log in JSON format
     ),
     defaultMeta: { service: 'plivo-campaign-service' }, // Add service name to logs
     transports: [
       // Log to console (adjust format for development readability)
       new winston.transports.Console({
         format: winston.format.combine(
           winston.format.colorize(),
           winston.format.simple()
         )
       }),
       // Optionally log to a file in production
       // new winston.transports.File({ filename: 'error.log', level: 'error' }),
       // new winston.transports.File({ filename: 'combined.log' })
     ],
   });
   
   // If we're not in production then log to the `console` with the format:
   // `${info.level}: ${info.message} JSON.stringify({ ...rest }) `
   // Note: The default Console transport above already handles development logging.
   // This block might be redundant or need adjustment based on specific needs.
   // if (process.env.NODE_ENV !== 'production') {
   //   logger.add(new winston.transports.Console({
   //     format: winston.format.simple(),
   //   }));
   // }
   
   module.exports = logger;
   
   // Usage in other files (replace console.log/error):
   // const logger = require('./config/logger');
   // logger.info('Server started');
   // logger.error('Failed to send message', { error: err.message, recipient });
   

3. Retry Mechanisms: Network issues or temporary Plivo API glitches can occur. Implement retries for critical operations like sending messages. Use libraries like async-retry or implement manual exponential backoff.

   Install async-retry:

   bash

   npm install async-retry
   

   Example using async-retry:

   javascript

   // services/campaignService.js (Modify the sending loop)
   const retry = require('async-retry');
   const plivoClient = require('../config/plivo');
   const logger = require('../config/logger'); // Assuming Winston setup
   
   // ... (inside sendCampaign function) ...
   
   for (const recipient of recipients) {
       try {
           // Basic validation... (as before)
           if (!/^\+\d{1,15}$/.test(recipient)) {
              logger.warn(`Skipping invalid recipient format: ${recipient}`, { recipient, campaignId });
              campaignStore[campaignId].results.push({ recipient, status: 'invalid_format' });
              continue;
           }
   
           await retry(async (bail, attempt) => {
               // bail(new Error('Dont retry')) is used to stop retrying for certain errors
               logger.debug(`Attempt ${attempt}: Sending message to ${recipient}...`, { recipient, campaignId });
   
               const response = await plivoClient.messages.create(
                   senderId,
                   recipient,
                   message
                   // ... options like delivery report URL
               );
   
               logger.info(`Message sent to ${recipient}, UUID: ${response.messageUuid[0]}`, { recipient, campaignId, messageUuid: response.messageUuid[0] });
               // Update campaignStore or DB here upon successful send within retry block
               campaignStore[campaignId].results.push({ recipient, status: 'sent', messageUuid: response.messageUuid[0] });
   
           }, {
               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 (${attempt}) sending to ${recipient} due to error: ${error.message}`, { recipient, campaignId, attempt, error: error.message });
                   // Potentially check for non-retryable Plivo errors here and call bail(error)
                   // Example: Plivo often uses statusCode for errors
                   if (error.statusCode === 400 || error.statusCode === 404) { // Bad Request or Not Found (e.g., invalid number)
                        logger.error(`Non-retryable error sending to ${recipient}. Bailing.`, { recipient, campaignId, statusCode: error.statusCode });
                        bail(new Error(`Non-retryable Plivo error (Status ${error.statusCode}): ${error.message}`));
                        return; // Explicitly return after bailing
                   }
                   // Add other non-retryable status codes as needed
               }
           });
   
           // No need for manual delay here if using async-retry timeouts
   
       } catch (error) {
           logger.error(`Failed to send message to ${recipient} after retries: ${error.message}`, { recipient, campaignId, error: error.message, stack: error.stack });
           // Update campaignStore or DB for failure state AFTER retries exhausted
            if (!error.message.startsWith('Non-retryable')) { // Avoid double-logging if bailed
                campaignStore[campaignId].results.push({ recipient, status: 'failed', error: error.message });
            } else {
                // Handle the bailed error specifically if needed (e.g., mark as invalid_number)
                // Ensure the error object passed to bail is used or logged appropriately here.
                const originalErrorMsg = error.message.replace('Non-retryable Plivo error ', ''); // Clean up message
                campaignStore[campaignId].results.push({ recipient, status: 'failed_non_retryable', error: originalErrorMsg });
            }
       }
   }
   // ... (rest of sendCampaign function) ...
   

Frequently Asked Questions About Plivo SMS Marketing

How much does Plivo SMS marketing cost?

Plivo SMS pricing varies by destination country. US/Canada SMS costs approximately $0.0075-$0.01 per segment. International rates vary significantly. Volume discounts are available for high-volume senders. Check Plivo's pricing page for current rates by country.

What is TCPA compliance for SMS marketing?

TCPA (Telephone Consumer Protection Act) requires express written consent before sending promotional SMS messages. Under the FCC's December 2023 ruling, consent must be specific to your business – you cannot share consent across multiple companies. You must provide opt-out mechanisms (STOP keyword) and honor requests within seconds.

What are Plivo's SMS rate limits?

Plivo enforces a default limit of 100 simultaneous API requests. Additionally, your account has a configured messages-per-second (MPS) rate. If you exceed limits, Plivo returns HTTP 429 "Too Many Requests" – messages are queued, not lost. For higher throughput, implement message queuing (RabbitMQ, Redis Queue) or use number pooling.

Can I send SMS with Plivo using Next.js?

Yes. While this guide uses Express, Plivo works seamlessly with Next.js API routes. Replace Express endpoints with Next.js API route handlers in the /pages/api or /app/api directory. The Plivo SDK code remains identical. See Section 6 for Supabase integration patterns.

What is SHAFT content and why is it prohibited?

SHAFT stands for Sex, Hate, Alcohol, Firearms, Tobacco – content categories prohibited by CTIA Guidelines. Mobile carriers automatically block messages containing SHAFT content, and violations can result in immediate account suspension or permanent bans. Always review message content for compliance.

How do I test Plivo webhooks locally?

Use ngrok to expose your local development server to the internet. Run ngrok http 3000, copy the HTTPS URL (e.g., https://abc123.ngrok.io), and configure it as your webhook URL in the Plivo dashboard. Ngrok tunnels incoming webhook requests to your local Express server.

What happens if a Plivo SMS fails to deliver?

Plivo provides detailed delivery reports via webhooks. Failed messages return error codes indicating the failure reason (invalid number, carrier rejection, blocked content, etc.). Implement retry logic with exponential backoff for transient failures. Monitor delivery rates to identify systematic issues.

How do I implement opt-out management with Plivo?

Handle incoming SMS webhooks, check for keywords (STOP, CANCEL, END, QUIT, UNSUBSCRIBE), and remove numbers from your campaign database. Confirm opt-out with a final message: "You've been unsubscribed. Reply START to opt back in." Process opt-outs in real-time to maintain TCPA compliance.

Conclusion

You've built a production-ready SMS marketing campaign system with Plivo, Node.js, and Express. Your application now handles bulk messaging, webhook callbacks, error handling, and retry logic – all while maintaining TCPA and CTIA compliance.

Key Takeaways:

• Compliance First: Always obtain express written consent, honor opt-outs immediately, and avoid SHAFT content to prevent carrier bans.
• Rate Limiting: Plivo enforces 100 concurrent requests and account-level MPS limits. Implement message queuing (RabbitMQ, Redis Queue) for production scale.
• Error Handling: Use exponential backoff for transient failures, monitor delivery reports via webhooks, and log all API interactions for troubleshooting.
• Security: Store credentials in environment variables, validate webhook signatures, sanitize user inputs, and implement rate limiting on your API endpoints.

Next Steps:

1. Database Integration: Replace in-memory storage with PostgreSQL or MongoDB to persist campaigns, messages, and opt-out lists.
2. Supabase Migration: Follow Section 6 guidance to migrate from Express to Next.js API routes with Supabase for authentication and data persistence.
3. Advanced Features: Add scheduled campaigns, A/B testing, segmentation, delivery analytics, and automated opt-out processing.
4. Production Deployment: Deploy to AWS, Google Cloud, or Vercel with environment-specific configurations, monitoring (Datadog, New Relic), and CI/CD pipelines.

For questions about Plivo integration, consult the official Plivo Node.js SDK documentation and CTIA messaging guidelines.