Back to Resources

code examples

Sent logo
Sent TeamMay 3, 2025 / code examples / nodejs

Scheduling SMS Reminders with Node.js and Express

Complete guide to building a production-ready SMS reminder scheduling application using Node.js, Express, and Twilio Messages API with database persistence and error handling

Scheduling SMS Reminders with Node.js and Express

This guide provides a complete walkthrough for building a production-ready application using Node.js and Express to schedule and send SMS reminders via the Twilio Messages API. We'll cover everything from initial project setup and Twilio configuration to core scheduling logic, API creation, error handling, database persistence, security, and deployment.

By the end of this tutorial, you will have a functional service capable of accepting requests to send an SMS message at a specific future time, reliably dispatching those messages, and handling potential issues gracefully.

Problem Solved: Automating SMS notifications, appointment reminders, follow-ups, or any communication that needs to be sent at a predetermined future time, without manual intervention.

Technologies Used:

  • Node.js: A JavaScript runtime environment for building server-side applications.
  • Express: A minimal and flexible Node.js web application framework used to build the API layer.
  • Twilio Messages API: A powerful API for sending messages across various channels, including SMS. We'll use the twilio Node.js library.
  • node-cron: A task scheduler based on cron syntax for scheduling the SMS sending jobs.
  • dotenv: A module to load environment variables from a .env file.
  • uuid: To generate unique identifiers for scheduled jobs.
  • (Optional but Recommended for Production): A database (like PostgreSQL or MongoDB) and an ORM/ODM (like Prisma or Mongoose) for persistent job storage. This guide will initially use an in-memory store for simplicity and later detail database integration.

System Architecture:

mermaid
graph LR
    A[Client/User] -- HTTP POST /schedule --> B(Node.js/Express API);
    B -- Validate & Store Job (In-Memory/DB) --> C{Scheduling Logic};
    C -- Schedule Job (node-cron) --> D[Twilio Messages API];
    D -- Send SMS --> E[Recipient's Phone];
    B -- Job ID & Confirmation --> A;
    C -- Update Job Status (In-Memory/DB) --> C;
    F[Twilio Console] -- Configure Account & Number --> B;
    G[Developer] -- Set .env Variables --> B;

    style B fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#ccf,stroke:#333,stroke-width:2px
    style D fill:#f8d7da,stroke:#721c24,stroke-width:1px

Prerequisites:

  • Node.js and npm (or yarn): Installed on your system (Node.js v14+ recommended). Download Node.js
  • Twilio Account: Sign up for a free account at twilio.com/try-twilio. You'll get free credit to start.
  • A Twilio Phone Number: Purchase one from the Twilio Console.
  • Basic understanding of JavaScript, Node.js, and REST APIs.
  • (Optional) ngrok: If you plan to test incoming features like delivery receipts later. Download ngrok

1. Project Setup and Initialization

Let's create our project directory, initialize Node.js, and install the necessary dependencies.

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

    bash
    mkdir node-sms-scheduler
cd node-sms-scheduler

  2. Initialize Node.js Project: This command creates a package.json file to manage your project's dependencies and scripts.

    bash
    npm init -y

  3. Install Dependencies: We need Express for the web server, the Twilio SDK, node-cron for scheduling, dotenv for environment variables, and uuid for unique job IDs.

    bash
    npm install express twilio node-cron dotenv uuid

  4. Install Development Dependencies (Optional but Recommended): nodemon automatically restarts the server during development when files change.

    bash
    npm install --save-dev nodemon

  5. Create Project Structure: Set up a basic structure for better organization.

    bash
    mkdir src
mkdir src/routes
mkdir src/services
mkdir src/config
touch src/server.js
touch src/routes/schedule.js
touch src/services/smsScheduler.js
touch src/config/twilioClient.js
touch .env
touch .gitignore
    • src/: Contains all source code.
    • src/routes/: Holds API route definitions.
    • src/services/: Contains business logic, like scheduling and interacting with Twilio.
    • src/config/: For configuration files, like initializing the Twilio client.
    • src/server.js: The main entry point for the Express application.
    • .env: Stores environment variables (API keys, etc.). Never commit this file.
    • .gitignore: Specifies files/directories Git should ignore.

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

    text
    # .gitignore

node_modules/
.env
*.log

  7. Add start and dev Scripts to package.json: Modify the scripts section in your package.json:

    json
    {
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}
    • npm start: Runs the application using Node.
    • npm run dev: Runs the application using nodemon for development.

2. Twilio Account and Application Setup

Before writing code, we need to configure our Twilio account and obtain necessary credentials.

  1. Sign Up/Log In: Go to the Twilio Console and log in or sign up.
  2. Get Account SID and Auth Token: Your Account SID and Auth Token are displayed on the console dashboard. You'll need these for your .env file.
  3. Buy a Phone Number:
    • Navigate to "Phone Numbers" > "Buy a number".
    • Search for a number with SMS capabilities in your desired country.
    • Purchase the number. Note down this number (in E.164 format, e.g., +15551234567).

3. Environment Configuration

We'll use a .env file to store sensitive credentials and configuration settings securely.

  1. Populate .env File: Open the .env file in your project root and add the following variables, replacing the placeholders with your actual values:

    dotenv
    # .env

# Twilio Credentials
TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN
TWILIO_PHONE_NUMBER=+15551234567

# Application Settings
PORT=3000
    • TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN: Found on your console dashboard.
    • TWILIO_PHONE_NUMBER: The Twilio phone number you purchased.
    • PORT: The port your Express server will run on.

  2. Load Environment Variables: At the very top of your main application file (src/server.js), require and configure dotenv.

    javascript
    // src/server.js
require('dotenv').config();

const express = require('express');
// ... rest of the file

4. Implementing the Core Scheduling Logic

Now, let's set up the Twilio client and the service that handles scheduling.

  1. Initialize Twilio Client: Create a reusable Twilio client instance.

    javascript
    // src/config/twilioClient.js
const twilio = require('twilio');

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;

if (!accountSid || !authToken) {
    console.error('Error: Twilio Account SID or Auth Token not found in environment variables.');
    console.error('Please check your .env file and Twilio account setup.');
}

const client = twilio(accountSid, authToken);

module.exports = client;

  2. Create the SMS Scheduling Service: This service will manage scheduled jobs (initially in memory) and use node-cron to trigger sending.

    javascript
    // src/services/smsScheduler.js
const cron = require('node-cron');
const { v4: uuidv4 } = require('uuid');
const client = require('../config/twilioClient');

const scheduledJobs = new Map();

/**
 * Converts a Date object into a cron expression string.
 * @param {Date} date - The date/time to schedule the job.
 * @returns {string} Cron expression string.
 */
function dateToCron(date) {
    const minutes = date.getMinutes();
    const hours = date.getHours();
    const days = date.getDate();
    const months = date.getMonth() + 1;
    return `${minutes} ${hours} ${days} ${months} *`;
}

/**
 * Sends the SMS using the Twilio Messages API.
 * @param {string} jobId - The ID of the job being processed.
 * @param {object} details - Job details.
 */
async function sendSms(jobId, details) {
    console.log(`[${new Date().toISOString()}] Sending SMS for Job ID: ${jobId}`);
    const { to, message } = details;
    const from = process.env.TWILIO_PHONE_NUMBER;

    try {
        const resp = await client.messages.create({
            body: message,
            from: from,
            to: to
        });
        console.log(`[${jobId}] SMS sent successfully. Message SID: ${resp.sid}`);

        if (scheduledJobs.has(jobId)) {
            scheduledJobs.get(jobId).details.status = 'sent';
            scheduledJobs.get(jobId).details.messageSid = resp.sid;
            delete scheduledJobs.get(jobId).task;
        }
    } catch (err) {
        console.error(`[${jobId}] Error sending SMS:`, err.message || err);
        if (scheduledJobs.has(jobId)) {
            scheduledJobs.get(jobId).details.status = 'failed';
            scheduledJobs.get(jobId).details.error = err.message || 'Unknown error';
            delete scheduledJobs.get(jobId).task;
        }
    }
}

/**
 * Schedules an SMS message to be sent at a specific time.
 * @param {string} to - Recipient phone number (E.164 format).
 * @param {string} message - The SMS message text.
 * @param {Date} sendAt - The Date object representing when to send.
 * @returns {string} The unique job ID.
 * @throws {Error} If sendAt is in the past or cron scheduling fails.
 */
function scheduleSms(to, message, sendAt) {
    if (!(sendAt instanceof Date) || isNaN(sendAt)) {
        throw new Error('Invalid sendAt date provided.');
    }
    if (sendAt <= new Date()) {
        throw new Error('Schedule time must be in the future.');
    }

    const jobId = uuidv4();
    const cronTime = dateToCron(sendAt);
    const jobDetails = {
        jobId: jobId,
        to: to,
        message: message,
        sendAt: sendAt.toISOString(),
        status: 'pending',
        cronTime: cronTime,
        createdAt: new Date().toISOString()
    };

    console.log(`[${new Date().toISOString()}] Scheduling Job ID: ${jobId} at ${sendAt.toISOString()} (Cron: ${cronTime})`);

    try {
        const task = cron.schedule(cronTime, () => {
            sendSms(jobId, jobDetails);
        }, {
            scheduled: true,
            timezone: "Etc/UTC"
        });

        scheduledJobs.set(jobId, { task, details: jobDetails });
        console.log(`[${jobId}] Successfully scheduled.`);
        return jobId;
    } catch (error) {
        console.error(`[${jobId}] Failed to schedule cron job:`, error);
        throw new Error(`Failed to schedule SMS: ${error.message}`);
    }
}

/**
 * Retrieves the status of a scheduled job.
 * @param {string} jobId - The ID of the job to check.
 * @returns {object | null} Job details or null if not found.
 */
function getJobStatus(jobId) {
    const job = scheduledJobs.get(jobId);
    return job ? job.details : null;
}

/**
 * Cancels a pending scheduled job.
 * @param {string} jobId - The ID of the job to cancel.
 * @returns {boolean} True if cancelled successfully, false otherwise.
 */
function cancelJob(jobId) {
    const job = scheduledJobs.get(jobId);
    if (job && job.details.status === 'pending' && job.task) {
        try {
            job.task.stop();
            job.details.status = 'cancelled';
            delete job.task;
            console.log(`[${jobId}] Job cancelled successfully.`);
            return true;
        } catch(error) {
            console.error(`[${jobId}] Error stopping cron task during cancellation:`, error);
            return false;
        }
    }
    console.log(`[${jobId}] Job not found or not in pending state.`);
    return false;
}

module.exports = {
    scheduleSms,
    getJobStatus,
    cancelJob
};
    • In-Memory Store: scheduledJobs map holds job data. This is lost on server restart. See Section 8 for database persistence.
    • dateToCron: Converts a JavaScript Date object into the specific cron syntax needed by node-cron. It's crucial to schedule based on UTC (timezone: "Etc/UTC") to avoid ambiguity.
    • sendSms: The function executed by node-cron. It calls the Twilio API using the configured client. Includes basic success/error logging and status updates (in-memory).
    • scheduleSms: The main function. Validates input, generates a unique ID, converts the date to a cron string, schedules the sendSms function using cron.schedule, stores the job details and the cron task object, and returns the ID.
    • getJobStatus, cancelJob: Helper functions to check and cancel jobs (stops the node-cron task and updates status).

5. Building the API Layer with Express

Let's create the Express server and the API endpoint to receive scheduling requests.

  1. Set up Basic Express Server:

    javascript
    // src/server.js
require('dotenv').config();
const express = require('express');
const scheduleRoutes = require('./routes/schedule');

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

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

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

app.use('/api/schedule', scheduleRoutes);

app.use((err, req, res, next) => {
    console.error("Unhandled Error:", err.stack || err);
    res.status(err.status || 500).json({
        success: false,
        error: err.message || 'Internal Server Error'
    });
});

app.use((req, res, next) => {
    res.status(404).json({ success: false, error: 'Not Found' });
});

app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
});
    • Loads dotenv.
    • Initializes Express.
    • Uses middleware to parse JSON and URL-encoded request bodies.
    • Includes a basic /health endpoint.
    • Mounts the scheduling routes under the /api/schedule path.
    • Includes basic 404 and global error handlers.

  2. Define Schedule Routes: Implement the API endpoints for scheduling, checking status, and cancelling.

    javascript
    // src/routes/schedule.js
const express = require('express');
const { scheduleSms, getJobStatus, cancelJob } = require('../services/smsScheduler');

const router = express.Router();

router.post('/', (req, res, next) => {
    const { to, message, sendAt } = req.body;

    if (!to || !message || !sendAt) {
        return res.status(400).json({ success: false, error: 'Missing required fields: to, message, sendAt (ISO 8601 format)' });
    }

    if (!/^\+?[1-9]\d{1,14}$/.test(to)) {
        return res.status(400).json({ success: false, error: 'Invalid phone number format. Use E.164 (e.g., +15551234567).' });
    }

    const sendAtDate = new Date(sendAt);
    if (isNaN(sendAtDate)) {
        return res.status(400).json({ success: false, error: 'Invalid date format for sendAt. Use ISO 8601 (e.g., 2025-12-31T23:59:59Z).' });
    }

    try {
        const jobId = scheduleSms(to, message, sendAtDate);
        res.status(202).json({ success: true, jobId: jobId, message: 'SMS scheduled successfully.' });
    } catch (error) {
        if (error.message.includes('future') || error.message.includes('Invalid sendAt')) {
            return res.status(400).json({ success: false, error: error.message });
        }
        next(error);
    }
});

router.get('/:jobId', (req, res) => {
    const { jobId } = req.params;
    const jobDetails = getJobStatus(jobId);

    if (jobDetails) {
        res.status(200).json({ success: true, job: jobDetails });
    } else {
        res.status(404).json({ success: false, error: 'Job not found.' });
    }
});

router.delete('/:jobId', (req, res, next) => {
    const { jobId } = req.params;
    try {
        const cancelled = cancelJob(jobId);
        if (cancelled) {
            res.status(200).json({ success: true, message: 'Job cancelled successfully.' });
        } else {
            const jobDetails = getJobStatus(jobId);
            if (!jobDetails) {
                return res.status(404).json({ success: false, error: 'Job not found.' });
            } else {
                return res.status(400).json({ success: false, error: `Job cannot be cancelled (status: ${jobDetails.status}).` });
            }
        }
    } catch (error) {
        next(error);
    }
});

module.exports = router;
    • Uses an Express Router.
    • POST /: Handles scheduling requests. Performs basic validation on to, message, and sendAt. Converts sendAt (expected in ISO 8601 format) to a Date object. Calls scheduleSms and returns the jobId with a 202 Accepted status. Includes specific error handling for validation failures.
    • GET /:jobId: Retrieves job status using getJobStatus. Returns 404 if not found.
    • DELETE /:jobId: Attempts to cancel a job using cancelJob. Returns appropriate status codes based on success, failure, or job status.

6. Integrating Twilio (Sending Logic)

This part was largely covered in src/services/smsScheduler.js within the sendSms function. Key points:

  • Client Initialization: The pre-configured Twilio client from src/config/twilioClient.js is used.
  • Sending Method: client.messages.create() is used with the required parameters:
    • body: The message content.
    • to: Recipient number.
    • from: Your Twilio number (from .env).
  • Response Handling: The try...catch block handles both successful responses (logging the sid) and errors (logging details from the error response).
  • Status Update: The in-memory scheduledJobs map is updated to reflect 'sent' or 'failed' status.

Example API Test:

bash
curl -X POST http://localhost:3000/api/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "message": "This is your scheduled reminder!",
    "sendAt": "2025-01-15T10:30:00Z"
  }'

7. Error Handling, Logging, and Retries

Robust error handling is critical for a reliable scheduling system.

  1. Consistent Error Handling Strategy:

    • API Layer (src/routes/schedule.js): Validate inputs early and return specific 400 Bad Request errors. Use try...catch around service calls. Handle known errors gracefully (like scheduling in the past). Pass unknown errors to the global Express error handler using next(error).
    • Service Layer (src/services/smsScheduler.js): Use try...catch around node-cron scheduling and Twilio API calls. Log errors with context (like jobId). Update job status to 'failed' and store error information. Throw errors for critical failures (like invalid input date) to be caught by the API layer.
    • Global Error Handler (src/server.js): A final catch-all for unexpected errors, logging the stack trace and returning a generic 500 Internal Server Error response.

  2. Logging:

    • Current: Basic console.log and console.error are used.
    • Production Recommendation: Use a structured logging library like winston or pino.
      • Configure different log levels (info, warn, error).
      • Output logs in JSON format for easier parsing by log aggregation systems (like ELK Stack, Datadog, Splunk).
      • Include contextual information in logs: jobId, timestamp, relevant data.
      • Log key events: job scheduled, job execution started, SMS sent attempt, SMS sent success/failure (with Twilio sid or error details), job cancelled.

    Example Winston Setup:

    bash
    npm install winston
    javascript
    // src/config/logger.js
const winston = require('winston');

const logger = winston.createLogger({
    level: 'info',
    format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.json()
    ),
    transports: [
        new winston.transports.File({ filename: 'error.log', level: 'error' }),
        new winston.transports.File({ filename: 'combined.log' }),
    ],
});

if (process.env.NODE_ENV !== 'production') {
    logger.add(new winston.transports.Console({
        format: winston.format.simple(),
    }));
}

module.exports = logger;

  3. Retry Mechanisms:

    • Twilio Internal Retries: Twilio often handles transient network issues for message delivery internally.
    • Application-Level Retries (for Twilio API Calls): For specific, potentially temporary Twilio API errors (e.g., network timeouts, 5xx errors from Twilio), you could implement a simple retry within the sendSms function.

    Example Simple Retry Logic:

    javascript
    async function sendSms(jobId, details) {
    const MAX_RETRIES = 3;
    const INITIAL_DELAY_MS = 1000;

    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
        try {
            const resp = await client.messages.create({
                body: details.message,
                from: process.env.TWILIO_PHONE_NUMBER,
                to: details.to
            });
            console.log(`[${jobId}] Attempt ${attempt}: SMS sent successfully. SID: ${resp.sid}`);
            return;
        } catch (err) {
            console.error(`[${jobId}] Attempt ${attempt} failed:`, err.message);
            const statusCode = err?.status;

            const isRetryable = !statusCode || (statusCode >= 500 && statusCode <= 599);

            if (isRetryable && attempt < MAX_RETRIES) {
                const delay = INITIAL_DELAY_MS * Math.pow(2, attempt - 1);
                console.log(`[${jobId}] Retrying in ${delay}ms...`);
                await new Promise(resolve => setTimeout(resolve, delay));
            } else {
                console.error(`[${jobId}] Final attempt failed or error is not retryable.`);
                return;
            }
        }
    }
}
    • Scheduling Retries (Missed Jobs): The biggest challenge with the in-memory store is losing jobs on restart. A database (Section 8) is essential. With a DB, on application startup, you query for jobs that are 'pending' but whose sendAt time has passed, and either send them immediately or reschedule them slightly in the future. You also need to reschedule jobs whose sendAt is still in the future.

8. Creating a Database Schema and Data Layer (Production Enhancement)

Using an in-memory store (scheduledJobs map) is not suitable for production as all scheduled jobs are lost when the server restarts. A database is essential for persistence. We'll outline using PostgreSQL with Prisma as an example.

  1. Install Prisma:

    bash
    npm install prisma @prisma/client --save-dev

  2. Initialize Prisma:

    bash
    npx prisma init --datasource-provider postgresql

    This creates a prisma directory with a schema.prisma file and updates your .env with a DATABASE_URL variable.

  3. Configure Database Connection: Update the DATABASE_URL in your .env file to point to your PostgreSQL database. Example: DATABASE_URL="postgresql://user:password@host:port/database?schema=public"

  4. Define Database Schema:

    prisma
    // prisma/schema.prisma

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

datasource db {
    provider = "postgresql"
    url      = env("DATABASE_URL")
}

model ScheduledSms {
    id              String    @id @default(uuid())
    to_number       String
    message_text    String
    send_at         DateTime
    status          String    @default("pending")
    twilio_message_id String?
    error_message   String?
    cron_expression String?
    created_at      DateTime  @default(now())
    updated_at      DateTime  @updatedAt

    @@index([status, send_at])
}

  5. Apply Schema to Database (Migration):

    bash
    npx prisma migrate dev --name init_scheduled_sms

    This command creates the SQL migration file and applies it to your database, creating the ScheduledSms table.

  6. Generate Prisma Client:

    bash
    npx prisma generate

    This generates the typed database client in node_modules/@prisma/client.

  7. Update smsScheduler.js to Use Prisma:

    javascript
    // src/services/smsScheduler.js
const cron = require('node-cron');
const { v4: uuidv4 } = require('uuid');
const client = require('../config/twilioClient');
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

const activeCronTasks = new Map();

function dateToCron(date) {
    const minutes = date.getMinutes();
    const hours = date.getHours();
    const days = date.getDate();
    const months = date.getMonth() + 1;
    return `${minutes} ${hours} ${days} ${months} *`;
}

async function sendSms(jobId, details) {
    console.log(`[${new Date().toISOString()}] Sending SMS for Job ID: ${jobId}`);
    const { to, message } = details;
    const from = process.env.TWILIO_PHONE_NUMBER;

    try {
        const resp = await client.messages.create({
            body: message,
            from: from,
            to: to
        });
        console.log(`[${jobId}] SMS sent successfully. SID: ${resp.sid}`);

        await prisma.scheduledSms.update({
            where: { id: jobId },
            data: {
                status: 'sent',
                twilio_message_id: resp.sid,
                updated_at: new Date()
            }
        });
    } catch (err) {
        console.error(`[${jobId}] Error sending SMS:`, err.message || err);
        const errorMessage = err.message || 'Unknown error';

        await prisma.scheduledSms.update({
            where: { id: jobId },
            data: {
                status: 'failed',
                error_message: errorMessage,
                updated_at: new Date()
            }
        });
    }
}

async function scheduleSms(to, message, sendAt) {
    if (!(sendAt instanceof Date) || isNaN(sendAt)) {
        throw new Error('Invalid sendAt date provided.');
    }
    if (sendAt <= new Date()) {
        throw new Error('Schedule time must be in the future.');
    }

    const cronTime = dateToCron(sendAt);
    const jobDetails = {
        to_number: to,
        message_text: message,
        send_at: sendAt,
        status: 'pending',
        cron_expression: cronTime
    };

    const savedJob = await prisma.scheduledSms.create({
        data: jobDetails
    });
    const jobId = savedJob.id;

    console.log(`[${new Date().toISOString()}] Scheduling Job ID: ${jobId} at ${sendAt.toISOString()} (Cron: ${cronTime})`);

    try {
        const task = cron.schedule(cronTime, () => {
            sendSms(jobId, { to: savedJob.to_number, message: savedJob.message_text });
            activeCronTasks.delete(jobId);
        }, {
            scheduled: true,
            timezone: "Etc/UTC"
        });

        activeCronTasks.set(jobId, task);
        console.log(`[${jobId}] Successfully scheduled.`);
        return jobId;
    } catch (error) {
        console.error(`[${jobId}] Failed to schedule cron job:`, error);

        await prisma.scheduledSms.update({
            where: { id: jobId },
            data: { status: 'failed_scheduling', error_message: error.message }
        });

        throw new Error(`Failed to schedule SMS: ${error.message}`);
    }
}

async function getJobStatus(jobId) {
    const job = await prisma.scheduledSms.findUnique({
        where: { id: jobId }
    });
    return job;
}

async function cancelJob(jobId) {
    const job = await prisma.scheduledSms.findUnique({
        where: { id: jobId },
        select: { status: true }
    });

    if (!job) {
        console.log(`[${jobId}] Job not found in database.`);
        return false;
    }

    if (job.status !== 'pending') {
        console.log(`[${jobId}] Job not in pending state (status: ${job.status}). Cannot cancel.`);
        return false;
    }

    const task = activeCronTasks.get(jobId);
    if (task) {
        try {
            task.stop();
            activeCronTasks.delete(jobId);
            console.log(`[${jobId}] Cron task stopped.`);
        } catch (error) {
            console.error(`[${jobId}] Error stopping cron task during cancellation:`, error);
        }
    } else {
        console.warn(`[${jobId}] No active cron task found in memory map for pending job.`);
    }

    await prisma.scheduledSms.update({
        where: { id: jobId },
        data: { status: 'cancelled', updated_at: new Date() }
    });
    console.log(`[${jobId}] Job status updated to cancelled in database.`);
    return true;
}

async function loadAndReschedulePendingJobs() {
    console.log('Loading and rescheduling pending jobs...');
    const pendingJobs = await prisma.scheduledSms.findMany({
        where: { status: 'pending' }
    });

    let rescheduledCount = 0;
    for (const job of pendingJobs) {
        const sendAt = new Date(job.send_at);

        if (sendAt > new Date()) {
            try {
                const cronTime = dateToCron(sendAt);
                const task = cron.schedule(cronTime, () => {
                    sendSms(job.id, { to: job.to_number, message: job.message_text });
                    activeCronTasks.delete(job.id);
                }, {
                    scheduled: true,
                    timezone: "Etc/UTC"
                });
                activeCronTasks.set(job.id, task);
                console.log(`[${job.id}] Rescheduled pending job for ${sendAt.toISOString()}`);
                rescheduledCount++;
            } catch (error) {
                console.error(`[${job.id}] Failed to reschedule job:`, error);
                await prisma.scheduledSms.update({
                    where: { id: job.id },
                    data: { status: 'failed_scheduling', error_message: `Reschedule failed: ${error.message}` }
                });
            }
        } else {
            console.warn(`[${job.id}] Pending job's scheduled time ${sendAt.toISOString()} has passed. Marking as missed.`);
            await prisma.scheduledSms.update({
                where: { id: job.id },
                data: { status: 'failed', error_message: 'Scheduled time missed during downtime' }
            });
        }
    }
    console.log(`Rescheduled ${rescheduledCount} pending jobs.`);
}

module.exports = {
    scheduleSms,
    getJobStatus,
    cancelJob,
    loadAndReschedulePendingJobs
};
    • Prisma Client: Import and instantiate PrismaClient.
    • Database Operations: Replace scheduledJobs.set, scheduledJobs.get, scheduledJobs.delete with prisma.scheduledSms.create, prisma.scheduledSms.findUnique, prisma.scheduledSms.update.
    • Active Task Management: Since node-cron tasks run in memory, you still need a way to track active tasks (e.g., activeCronTasks map) so they can be cancelled (task.stop()). This map needs to be repopulated on server start by rescheduling pending jobs from the database.
    • Job Loading on Startup: Implement loadAndReschedulePendingJobs to query the database for 'pending' jobs when the application starts. Reschedule jobs whose send_at time is still in the future. Decide how to handle jobs whose time has already passed (send immediately, mark as failed/missed). Call this function from your main server startup logic (src/server.js).

  8. Update server.js to Load Pending Jobs:

    javascript
    // src/server.js (add after app setup)
const { loadAndReschedulePendingJobs } = require('./services/smsScheduler');

app.listen(port, async () => {
    console.log(`Server listening at http://localhost:${port}`);
    await loadAndReschedulePendingJobs();
});

9. Security Considerations

  1. Environment Variables: Never commit .env files to version control. Use environment variable management services in production (AWS Secrets Manager, Azure Key Vault, etc.).
  2. Input Validation: Validate all user inputs thoroughly. Use libraries like joi or express-validator for comprehensive validation.
  3. Rate Limiting: Implement rate limiting on your API endpoints to prevent abuse. Use packages like express-rate-limit.
  4. Authentication: Add authentication to your API endpoints to ensure only authorized users can schedule messages.
  5. HTTPS: Always use HTTPS in production to encrypt data in transit.
  6. Database Security: Ensure your database connection uses SSL/TLS and follows security best practices.

10. Testing

  1. Unit Tests: Test individual functions like dateToCron, scheduleSms, cancelJob.
  2. Integration Tests: Test the API endpoints using tools like supertest.
  3. Manual Testing: Use tools like Postman or curl to manually test the API.

Example Integration Test Setup:

bash
npm install --save-dev jest supertest
javascript
// tests/schedule.test.js
const request = require('supertest');
const app = require('../src/server');

describe('POST /api/schedule', () => {
    it('should schedule an SMS successfully', async () => {
        const response = await request(app)
            .post('/api/schedule')
            .send({
                to: '+15551234567',
                message: 'Test message',
                sendAt: new Date(Date.now() + 3600000).toISOString()
            });

        expect(response.status).toBe(202);
        expect(response.body.success).toBe(true);
        expect(response.body.jobId).toBeDefined();
    });
});

11. Deployment

  1. Environment Setup: Configure environment variables on your hosting platform (Heroku, AWS, Google Cloud, etc.).
  2. Database Migration: Run Prisma migrations on your production database.
  3. Process Management: Use process managers like PM2 to keep your application running and restart it on failure.
  4. Monitoring: Set up monitoring and alerting using services like New Relic, Datadog, or CloudWatch.
  5. Scaling: Consider horizontal scaling for handling high loads. Use load balancers and multiple instances.

Example PM2 Setup:

bash
npm install -g pm2
pm2 start src/server.js --name sms-scheduler
pm2 save
pm2 startup

Conclusion

You've built a complete SMS scheduling application with Node.js, Express, and Twilio. This guide covered project setup, API creation, scheduling logic, error handling, database persistence, security, testing, and deployment considerations. You now have a solid foundation for building production-ready messaging applications.

For further enhancements, consider:

  • Adding user authentication and authorization
  • Implementing webhook handlers for delivery receipts
  • Building a web dashboard for managing scheduled messages
  • Adding support for recurring messages
  • Implementing message templates and personalization
  • Adding support for international phone numbers and timezone handling

Frequently Asked Questions

How to schedule SMS messages with Node.js?

Use the `node-cron` library along with the Vonage Messages API. The `node-cron` library allows you to schedule tasks using cron syntax, and the Vonage API handles sending the SMS messages at the specified times. This guide provides a step-by-step tutorial on setting up this system.

What is the Vonage Messages API?

The Vonage Messages API is a service that enables sending messages through various channels, including SMS. You'll use the `@vonage/server-sdk` library in your Node.js application to interact with this API. This allows you to send SMS messages programmatically.

Why use dotenv for environment variables?

Dotenv helps manage sensitive information like API keys and secrets by loading them from a `.env` file. This keeps them out of your codebase, improving security. Never commit your `.env` file to version control.

When should I use a database for SMS scheduling?

A database is crucial for production applications. The in-memory storage used in the basic example is not persistent, meaning all scheduled messages are lost if the server restarts. A database like PostgreSQL or MongoDB provides reliable storage.

Can I cancel a scheduled SMS message?

Yes, you can cancel a scheduled SMS message using the provided API endpoint. The `DELETE /api/schedule/:jobId` route allows you to cancel a scheduled job by its unique identifier, as long as it's still in a 'pending' state. The system stops the scheduled task and updates the job status.

How to set up Vonage for SMS scheduling?

You need a Vonage API account, a purchased Vonage phone number, and a Vonage Application. Link the number to the application and configure your API key, secret, and application ID in a `.env` file. Ensure the Default SMS Setting is set to Messages API in the Vonage Dashboard.

What is node-cron used for in this project?

Node-cron is a task scheduler that uses cron syntax to define when tasks should run. In this project, it's used to schedule the execution of the SMS sending function at the specified date and time. It ensures messages are sent automatically.

How to handle errors when sending scheduled SMS?

Implement robust error handling using try-catch blocks around API calls and scheduling logic. Log errors with context, update job statuses, and consider retry mechanisms for transient errors. For production, use a structured logging library like Winston or Pino.

What is the purpose of the private.key file?

The `private.key` file contains your Vonage Application's private key, which is used for authentication. This key is required for your Node.js application to interact with the Vonage API securely. Keep this file secure and never commit it to version control.

How to structure a Node.js Express SMS scheduler project?

Create directories for routes, services, and config. The `routes` directory handles API endpoints, `services` contains the scheduling logic, and `config` holds the Vonage client initialization. This promotes organized and maintainable code.

What is the role of Express in SMS scheduling?

Express.js creates the web server and API layer for your SMS scheduling application. It handles incoming requests, routes them to the appropriate functions, and sends back responses. It provides the structure for your API.

How does the SMS scheduling system handle timezones?

The system schedules jobs based on UTC to avoid timezone ambiguities. The `dateToCron` function ensures the cron expression is generated and scheduled using UTC. This is crucial for accurate scheduling regardless of server location or user timezone.

How to test the SMS scheduling application locally?

You can test locally by sending requests to the API endpoints you created. Tools like Postman or curl can be used to send these requests. For testing webhooks, you can use ngrok to create a publicly accessible URL for your local server.

Next article