Back to Blog
Language How-Tos

How to Track Message Delivery Status in Twilio Using Node.js

Handle Twilio StatusCallback webhooks in Express.js to receive real-time delivery status updates and log them to your database.

DA
Danial A
Senior Twilio Consultant, Telphi Consulting
June 22, 2026
8 min read
Twilio
Node.js
JavaScript
How-To
Code
How to Track Message Delivery Status in Twilio Using Node.js

This tutorial builds an Express.js webhook that receives real-time delivery status updates from Twilio for every SMS your application sends, enabling you to track whether each message was delivered, failed, or bounced. It targets Node.js developers who need reliable delivery confirmation for notifications, alerts, or compliance logging. You will pass a statusCallback URL when sending messages and handle the incoming status POSTs in an Express route.

Prerequisites and Setup

Install the packages with npm install twilio express dotenv and expose your local server with npx ngrok http 3000 to get a public URL for the callback. Twilio POSTs status updates at multiple points in the message lifecycle: queued, sent, delivered, and failed or undelivered, so your endpoint will receive several POSTs per message. The MessageSid field in each callback lets you correlate status updates with the original send in your database. Your endpoint must respond with a 2xx status or Twilio will retry the callback, which can result in duplicate status entries if your handler is not idempotent.

npm install twilio express dotenv

# Start ngrok
npx ngrok http 3000
# Use the https URL as your statusCallback

The Complete Code

The statusCallback URL is passed as a parameter when calling client.messages.create(), and Twilio will POST to that URL each time the message status changes. The Express status handler reads req.body.MessageSid, req.body.MessageStatus, req.body.To, and req.body.ErrorCode from the form-encoded body. Responding with a 204 No Content status tells Twilio the callback was received and processed without sending any response body. Log failed and undelivered statuses with their error codes so you can trigger retries or alert your operations team.

require('dotenv').config();
const express = require('express');
const twilio = require('twilio');

const app = express();
app.use(express.urlencoded({ extended: false }));

const client = twilio(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);

const statusLog = {};

app.post('/status', (req, res) => {
  const sid    = req.body.MessageSid    || '';
  const status = req.body.MessageStatus || '';
  const to     = req.body.To            || '';
  const error  = req.body.ErrorCode     || '';

  statusLog[sid] = { status, to, error };
  console.log('[STATUS]', sid, '->', status, error ? '(error ' + error + ')' : '');

  if (status === 'failed' || status === 'undelivered') {
    console.warn('ALERT: delivery failure to', to, 'error code', error);
  }

  res.sendStatus(204);
});

async function sendWithTracking(to, body, callbackUrl) {
  const message = await client.messages.create({
    body,
    from: process.env.TWILIO_PHONE_NUMBER,
    to,
    statusCallback: callbackUrl,
  });
  console.log('Sent', message.sid, 'to', to);
  return message.sid;
}

app.listen(3000, () => {
  console.log('Status webhook on port 3000');
  sendWithTracking('+15551234567', 'Test delivery tracking.', 'https://xxxx.ngrok.io/status');
});

Testing and Debugging

Start the server, replace the ngrok URL in sendWithTracking() with your current tunnel URL, and run the script. Watch the terminal for a sequence of status POSTs: typically queued, then sent, then delivered within a few seconds for a successful SMS to a mobile number. If no callbacks arrive, verify your ngrok tunnel is still running and the statusCallback URL in your send call matches the Express route path exactly. Error code 30003 in a callback indicates the destination handset was unreachable; error 30008 indicates the carrier blocked the message.

Taking It Further

Persist each status update to a database table with SID, status, timestamp, and error code to build a complete delivery audit trail for every message you send. Write a retry function that catches failed or undelivered callbacks and queues the message for a second attempt after a configurable delay using setTimeout or a job queue like Bull. Build a real-time dashboard using Server-Sent Events or WebSockets that pushes delivery status updates to a browser so your operations team can monitor batch sends live. Alert your team via Slack or PagerDuty when the failure rate for a sending session exceeds a configurable threshold.

Contact Telphi Consulting to implement a delivery monitoring and alerting system for your Twilio SMS operations in Node.js.

Share this article:
0 views

Ready to Transform Your Business Communications?

Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.

Comments (0)

Join the discussion and share your thoughts (AI-moderated for quality)

Protected by AI moderation

Be the first to comment

No comments yet. Share your thoughts below.