[metadata]
article:modified_time: 2026-03-09T18:47:22.000Z
dcterms.modified: 2026-03-09T18:47:22.000Z
description: Learn how to track the status of outbound messages you send with Programmable Messaging in your web application. Track the sent and delivery status of SMS, MMS, and WhatsApp Messages using status callbacks. Understand the differences when using a Messaging Service.
og:updated_time: 2026-03-09T18:47:22.000Z
viewport: width=device-width
x-twilio-docs-origin: otk
x-twilio-docs-source: primary

[canonical-links]
https://www.twilio.com/docs/messaging/guides/track-outbound-message-status

[document-links]
"Addition of RawDlrDoneDate to Delivered and Undelivered Status Webhooks" Changelog page: https://www.twilio.com/en-us/changelog/addition-of-rawdlrdonedate-to-delivered-and-undelivered-status-webhooks
/docs
1. SMS foundations: /docs/messaging/onboarding/sms-foundations
2. Prepare your sender strategy: /docs/messaging/onboarding/prepare-your-sender-strategy
3. Build your account: /docs/messaging/onboarding/build-your-account
4. Monitor your application: /docs/messaging/onboarding/monitor-your-application
<Message>: /docs/messaging/twiml/message
<Redirect>: /docs/messaging/twiml/redirect
A2P 10DLC quickstart: /docs/messaging/compliance/a2p-10dlc/quickstart
API overview: /docs/messaging/api
Advanced Guide to Link Shortening and Link Tracking with Twilio Messaging: https://www.twilio.com/en-us/blog/setup-link-shortening-click-tracking
All docs...: /docs
AlphaSenders: /docs/messaging/api/alphasender-resource
Alphanumeric Sender IDs: /docs/messaging/services/alphanumeric-sender-ids-in-messaging-services
Best Practices for Messaging Delivery Status Logging: /docs/messaging/guides/outbound-message-logging
Best Practices for Scaling with Messaging Services: /docs/messaging/guides/best-practices-at-scale
BrandRegistrations: /docs/messaging/api/brand-registration-resource
Browse all Messaging tutorials: /docs/messaging/tutorials
Build with AI: /docs/ai
Bulk Messaging: send messages at scale: /docs/bulk-messaging
C# and ASP.NET MVC: /docs/usage/tutorials/how-to-set-up-your-csharp-and-asp-net-mvc-development-environment
ChannelSenders: /docs/messaging/api/messaging-service-channelsender-resource
Compliance Embeddable Onboarding Guide: /docs/messaging/compliance/toll-free/compliance-embeddable-onboarding
Compliance Toolkit: /docs/messaging/features/compliance-toolkit
Consent Management API: /docs/messaging/features/consent-api
Console Onboarding Guide: /docs/messaging/compliance/toll-free/console-onboarding
Contact API: /docs/messaging/features/contact-api
Content Editor: message templates for any messaging channel: /docs/content
Conversations: /docs/conversations
Conversations: two-way messaging: /docs/conversations-classic
Countries: /docs/messaging/api/pricing
Create Mock Brands and Campaigns: /docs/messaging/compliance/a2p-10dlc/mock-brand-api
Dashboards: /docs/messaging/features/messaging-insights/dashboards
Deactivations resource: /docs/messaging/api/deactivations-resource
Debugging Common Issues with SMS: /docs/messaging/guides/debugging-common-issues
DestinationAlphaSenders: /docs/messaging/api/destination-alphasender-resource
Developer Hub: https://www.twilio.com/en-us/developers
Direct Sole Proprietor Registration: /docs/messaging/compliance/a2p-10dlc/direct-sole-proprietor-registration-overview
Direct Standard and Low-Volume Standard Registration: /docs/messaging/compliance/a2p-10dlc/direct-standard-onboarding
FAQ: /docs/usage/webhooks/webhooks-faq
Facebook Messenger (Public Beta): /docs/messaging/channels/facebook-messenger
Feedback: /docs/messaging/api/message-feedback-resource
Flex: /docs/flex
Functions Editor: /docs/serverless/functions-assets/functions#get-started-with-serverless-and-twilio-functions
Functions and Assets Service: https://console.twilio.com/us1/develop/functions/services
General Usage: /docs/usage
Get started with Facebook Messenger: /docs/messaging/channels/facebook-messenger
Get started with Messaging Services: /docs/messaging/tutorials/send-messages-with-messaging-services
Get started with RCS messaging: /docs/rcs/onboarding
Get started with your Twilio trial account: /docs/usage/tutorials/how-to-use-your-free-trial-account
Getting Started with Twilio Webhooks: /docs/usage/webhooks/getting-started-twilio-webhooks
Go: /docs/usage/tutorials/how-to-set-up-your-go-and-gin-development-environment
Help Center: https://help.twilio.com
How are status callback requests sent?: /docs/messaging/guides/track-outbound-message-status#how-are-status-callback-requests-sent
How to Optimize Message Deliverability with Message Feedback: /docs/messaging/guides/send-message-feedback-to-twilio
How to Schedule and Track Marketing Campaigns: https://www.twilio.com/en-us/blog/how-to-schedule-and-track-marketing-campaigns
ISV Onboarding Overview: /docs/messaging/compliance/a2p-10dlc/onboarding-isv
Identity and Access Management (IAM): /docs/iam
Implement a status callback handler (simplified example): /docs/messaging/guides/track-outbound-message-status#implement-a-status-callback-handler-simplified-example
Installed Channel: /docs/messaging/channels
Intelligent Alerts: /docs/messaging/features/intelligent-alerts
Intelligent Discovery AI Assistant: /docs/messaging/features/intelligent-discovery-ai-assistant
Introducing Engagement Suite from Twilio Messaging: https://www.twilio.com/en-us/blog/engagement-suite
Java: /docs/usage/tutorials/how-to-set-up-your-java-development-environment
Link Shortening and Click Tracking SSL FAQ: https://www.twilio.com/en-us/blog/archive/2023/link-shortening-and-click-tracking-ssl-faq
Link Shortening: /docs/messaging/features/link-shortening
Log in: https://www.twilio.com/login
Manage opt-ins and opt-outs: /docs/messaging/tutorials/advanced-opt-out
Manage queueing and latency: /docs/messaging/guides/scaling-queueing-latency
Market Throughput Overview: /docs/messaging/guides/market-throughput-overview
Media: /docs/messaging/api/media-resource
Message Resource: /docs/messaging/api/message-resource
Message Scheduling: /docs/messaging/features/message-scheduling
Messages: /docs/messaging/api/message-resource
Messaging Insights "One-time Password (OTP) Conversion Report": /docs/messaging/features/messaging-insights/dashboards#otp-conversion-dashboard
Messaging Logs: /docs/messaging/features/messaging-logs
Messaging Quickstart: /docs/messaging/quickstart
Messaging Service: /docs/messaging/services
Messaging: /docs/messaging
Multi-Tenancy: /docs/messaging/features/multi-tenancy
Node.js: /docs/usage/tutorials/how-to-set-up-your-node-js-and-express-development-environment
Onboarding Guide: /docs/messaging/features/link-shortening/onboarding-guide
Outbound Message Status in Status Callbacks: /docs/messaging/guides/outbound-message-status-in-status-callbacks
Overview: /docs/messaging/channels
Overview: /docs/messaging/compliance/a2p-10dlc/troubleshooting-a2p-brands
Overview: /docs/messaging/features/link-shortening
Overview: /docs/messaging/features/messaging-insights
Overview: /docs/messaging/onboarding
Overview: /docs/messaging/services
Overview: /docs/messaging/twiml
PHP: /docs/usage/tutorials/how-to-set-up-your-php-development-environment
Phone Numbers: /docs/phone-numbers
PhoneNumbers: /docs/messaging/api/phonenumber-resource
Preventing Fraud in Programmable Messaging: /docs/messaging/guides/preventing-messaging-fraud
Privacy Policy: /en-us/legal/privacy
Programmable Messaging REST API: /docs/messaging/api
Programmable Messaging: /docs/messaging
Python: /docs/usage/tutorials/how-to-set-up-your-python-and-flask-development-environment
RCS: /docs/rcs
REST API Onboarding Guide: /docs/messaging/compliance/toll-free/api-onboarding
Receive and reply to incoming messages: /docs/messaging/tutorials/how-to-receive-and-reply
Recommendations: /docs/messaging/features/recommendations
Registration for Government and Non-Profit Agencies: /docs/messaging/compliance/a2p-10dlc/onboarding-for-government-and-non-profit-agencies
Required Business Information: /docs/messaging/compliance/a2p-10dlc/collect-business-info
Retrieve and modify message history: /docs/messaging/tutorials/how-to-retrieve-and-modify-message-history
Ruby: /docs/usage/tutorials/how-to-set-up-your-ruby-and-sinatra-development-environment
SDKs: /docs/libraries
SMS Geo Permissions: /docs/messaging/guides/sms-geo-permissions
SMS Pumping Protection Insights: /docs/messaging/features/messaging-insights/sms-pumping-protection-insights
SMS Pumping Protection: /docs/messaging/features/sms-pumping-protection-programmable-messaging
SMS developer quickstart: /docs/messaging/quickstart
SMS no-code quickstart: /docs/messaging/quickstart/no-code-sms-studio-quickstart
Safeguard with Message redaction: /docs/messaging/guides/privacy-message-redaction
Scenario 1: No Messaging Service: /docs/messaging/guides/track-outbound-message-status#scenario-1-no-messaging-service
Scenario 2: Messaging Service used: /docs/messaging/guides/track-outbound-message-status#scenario-2-messaging-service-used
Send SMS and MMS messages: /docs/messaging/tutorials/how-to-send-sms-messages
Send a message with status callback URL: /docs/messaging/guides/track-outbound-message-status#step-2-send-a-message-with-status-callback-url
Send and receive RCS messages: /docs/rcs/send-an-rcs-message
Send appointment reminders: /docs/messaging/tutorials/appointment-reminders
Send messages with Facebook Messenger: /docs/messaging/tutorials/send-message-with-facebook-messenger
Services: /docs/messaging/api/service-resource
Set Up Notifications for A2P 10DLC: /docs/messaging/compliance/a2p-10dlc/event-streams-setup
Set up a status callback endpoint: /docs/messaging/guides/track-outbound-message-status#step-1-set-up-a-status-callback-endpoint
ShortCodes resource: /docs/messaging/api/short-code-resource
ShortCodes: /docs/messaging/api/services-shortcode-resource
Sign up: https://www.twilio.com/try-twilio
Sole Proprietor Registration: /docs/messaging/compliance/a2p-10dlc/onboarding-isv-api-sole-prop-new
Standard and Low-Volume Standard Registration: /docs/messaging/compliance/a2p-10dlc/onboarding-isv-api
Step 2. Send a message with status callback URL: /docs/messaging/guides/track-outbound-message-status#step-2-send-a-message-with-status-callback-url
Studio: /docs/studio
Terms of service: /en-us/legal/tos
Test SMS Messaging with the Virtual Phone: /docs/messaging/guides/guide-to-using-the-twilio-virtual-phone
Toll-free Verifications resource: /docs/messaging/api/tollfree-verification-resource
Track the Message Status of Outbound Messages: /docs/messaging/guides/track-outbound-message-status
Traffic Optimization Engine: /docs/messaging/features/traffic-optimization-engine
Traffic Shaping: /docs/messaging/features/traffic-shaping
Transition from a Sole Proprietor Brand to a Standard Brand: /docs/messaging/compliance/a2p-10dlc/transition-sole-proprietor-to-standard-brand
Troubleshooting A2P 10DLC Standard/LVS Brands: /docs/messaging/compliance/a2p-10dlc/troubleshooting-a2p-brands/troubleshooting-and-rectifying-a2p-standardlvs-brands
Troubleshooting A2P Phone Number registration issues: /docs/messaging/compliance/a2p-10dlc/troubleshooting-a2p-brands/troubleshooting-a2p-phone-number-registration-issues
Troubleshooting Sole Proprietor Brand Registration Failures: /docs/messaging/compliance/a2p-10dlc/troubleshooting-a2p-brands/troubleshooting-sole-proprietor-brand-registration-failures
Troubleshooting and rectifying Campaigns: /docs/messaging/compliance/a2p-10dlc/troubleshooting-a2p-brands/troubleshooting-and-rectifying-a2p-campaigns-1
Twilio Docs: /docs
Twilio Health Score for Messaging: /docs/messaging/features/twilio-health-score-for-messaging
Twilio Serverless Functions: /docs/serverless/functions-assets/functions
Twilio tag: https://stackoverflow.com/questions/tagged/twilio
Twilio's request to your incoming message Webhook URL: /docs/messaging/guides/webhook-request
US A2P 10DLC Overview: /docs/messaging/compliance/a2p-10dlc
Usa2p: /docs/messaging/api/usapptoperson-resource
Use Externally Registered Campaigns: /docs/messaging/compliance/a2p-10dlc/externally-registered-campaigns-api
Usecases: /docs/messaging/api/usapptopersonusecase-resource
Verify: user verification and one-time passwords: /docs/verify
Vettings: /docs/messaging/api/brand-vetting-resource
Video: /docs/video
View as Markdown: /docs/messaging/guides/track-outbound-message-status.md
Voice: /docs/voice
Webhooks: /docs/usage/webhooks
What to Know Before Sending International SMS Messages: /docs/messaging/guides/sending-international-sms-guide
WhatsApp quickstarts: /docs/whatsapp/quickstart
WhatsApp: /docs/whatsapp
create a new service: /docs/serverless/functions-assets/functions/create-service
created as a protected endpoint: /docs/serverless/functions-assets/visibility#protected
creating a new Messaging Service in Console: /docs/messaging/tutorials/send-messages-with-messaging-services#create-and-configure-a-messaging-service
how to use one to send a message: /docs/messaging/api/message-resource#send-a-message-with-a-messaging-service
in the Console by using the Function Editor's debugging feature: /docs/serverless/functions-assets/functions/debugging
one of your Twilio numbers: /console/phone-numbers/incoming
security guide: /docs/usage/webhooks/webhooks-security
signature validation: /docs/usage/webhooks/webhooks-security
standard request properties: /docs/messaging/guides/webhook-request#request-parameters
status: /docs/messaging/api/message-resource#message-status-values
support team: https://help.twilio.com

[structured-data]
{"@context":"https://schema.org","@id":"https://www.twilio.com/docs/messaging/guides/track-outbound-message-status#article","@type":"TechArticle","author":{"@type":"Organization","name":"Twilio Developer Education Team"},"dateModified":"2026-03-09T18:47:22.000Z","description":"Learn how to track the status of outbound messages you send with Programmable Messaging in your web application. Track the sent and delivery status of SMS, MMS, and WhatsApp Messages using status callbacks. Understand the differences when using a Messaging Service.","headline":"Track the Message Status of Outbound Messages","inLanguage":"en","publisher":{"@type":"Organization","name":"Twilio"},"url":"https://www.twilio.com/docs/messaging/guides/track-outbound-message-status"}

[content]
Track the Message Status of Outbound Messages | Twilio
Skip to content
Skip to navigation
Skip to topbar
Twilio Docs
Programmable Messaging
Getting Started
SMS developer quickstart
SMS no-code quickstart
Messaging onboarding guide
Overview
1. SMS foundations
2. Prepare your sender strategy
3. Build your account
4. Monitor your application
Get started with RCS messaging
WhatsApp quickstarts
Get started with Facebook Messenger
API reference
API overview
Messages resource
Messages
Feedback
Media
Services resource
Services
AlphaSenders
ChannelSenders
DestinationAlphaSenders
PhoneNumbers
ShortCodes
Deactivations resource
ShortCodes resource
Toll-free Verifications resource
A2P 10DLC
BrandRegistrations
Vettings
Usa2p
Usecases
Pricing API
Countries
Preventing Fraud
Preventing Fraud in Programmable Messaging
SMS Pumping Protection
SMS Pumping Protection Insights
Tutorials
Receive and reply to incoming messages
Send SMS and MMS messages
Send appointment reminders
Retrieve and modify message history
Send and receive RCS messages
Send messages with Facebook Messenger
Browse all Messaging tutorials
Messaging Services
Overview
Get started with Messaging Services
Manage opt-ins and opt-outs
Best Practices for Scaling with Messaging Services
Manage queueing and latency
Alphanumeric Sender IDs
Messaging Features
Twilio Health Score for Messaging
Intelligent Alerts
Intelligent Discovery AI Assistant
Link Shortening
Overview
Onboarding Guide
Advanced Guide to Link Shortening and Link Tracking with Twilio Messaging
Link Shortening and Click Tracking SSL FAQ
How to Schedule and Track Marketing Campaigns
Introducing Engagement Suite from Twilio Messaging
Messaging Logs
Message Scheduling
Messaging Insights
Overview
Dashboards
Multi-Tenancy
Recommendations
SMS Pumping Protection
Traffic Optimization Engine
Traffic Shaping
Compliance Toolkit
Consent Management API
Contact API
Usage Guides
Get started with your Twilio trial account
Test SMS Messaging with the Virtual Phone
Preventing Fraud in Programmable Messaging
What to Know Before Sending International SMS Messages
SMS Geo Permissions
Twilio's request to your incoming message Webhook URL
Outbound Message Status in Status Callbacks
Track the Message Status of Outbound Messages
Best Practices for Messaging Delivery Status Logging
Safeguard with Message redaction
Debugging Common Issues with SMS
How to Optimize Message Deliverability with Message Feedback
Market Throughput Overview
TwiML
Overview
<Message>
<Redirect>
US A2P 10DLC
A2P 10DLC quickstart
US A2P 10DLC Overview
Required Business Information
Registration for Government and Non-Profit Agencies
Register Your Business
Direct Standard and Low-Volume Standard Registration
Direct Sole Proprietor Registration
Transition from a Sole Proprietor Brand to a Standard Brand
For ISVs: Register Your Customers
ISV Onboarding Overview
Standard and Low-Volume Standard Registration
Sole Proprietor Registration
Use Externally Registered Campaigns
Create Mock Brands and Campaigns
Troubleshooting A2P 10DLC Registrations
Overview
Troubleshooting Sole Proprietor Brand Registration Failures
Troubleshooting A2P 10DLC Standard/LVS Brands
Troubleshooting and rectifying Campaigns
Troubleshooting A2P Phone Number registration issues
Set Up Notifications for A2P 10DLC
Toll-Free Verification
Console Onboarding Guide
REST API Onboarding Guide
Compliance Embeddable Onboarding Guide
Messaging Channels
Overview
WhatsApp
RCS
Facebook Messenger (Public Beta)
Other Messaging products
Content Editor: message templates for any messaging channel
Conversations: two-way messaging
Verify: user verification and one-time passwords
Bulk Messaging: send messages at scale
Related docs
Phone Numbers
General Usage
Identity and Access Management (IAM)
Twilio Docs
Search
Search
Messaging
Voice
Video
Conversations
Flex
Studio
All docs...
Build with AI
SDKs
Help Center
Search
Log in
Sign up
Page tools
View as Markdown
Copy as Markdown
On this page
Before you begin
How to track outbound message status
Step 1. Set up a status callback endpoint
How are status callback requests sent?
Implement a status callback handler (simplified example)
Step 2. Send a message with status callback URL
Scenario 1: No Messaging Service
Scenario 2: Messaging Service used
What's next?
Looking for more inspiration?
Visit the
Developer Hub
On this page
Before you begin
How to track outbound message status
Step 1. Set up a status callback endpoint
How are status callback requests sent?
Implement a status callback handler (simplified example)
Step 2. Send a message with status callback URL
Scenario 1: No Messaging Service
Scenario 2: Messaging Service used
What's next?
Page Tools
View as Markdown
Copy as Markdown
Track the Message Status of Outbound Messages
This guide shows you how to use Twilio's status callbacks to track changes of the message status of outbound messages you send with
Programmable Messaging
.
Message status changes occur throughout the lifecycle of a message from creation, through sending, to delivery, and even read receipt for supporting messaging channels.
(information)
Info
The guide focuses on outbound messages created using the
Message Resource
of the
Programmable Messaging REST API
and covers the necessary considerations when using a
Messaging Service
.
Before you begin
Before you dive into this guide, make sure you're familiar with the following concepts:
Know how to send a message by using the Programmable Messaging API. You can follow a
Messaging Quickstart
in the programming language of your choice.
Review our guide
Outbound Message Status in Status Callbacks
to understand for which status changes Twilio sends a status callback request.
If you send high volumes of messages or schedule messages, learn what a
Messaging Service
is and
how to use one to send a message
.
The status callbacks covered in this guide are Twilio webhooks. Check out our guide to
Getting Started with Twilio Webhooks
. Find other webhook pages, such as a
security guide
and
FAQ
in the
Webhooks
section of the docs.
Note
: The code samples in this guide require some local setup steps. Select your language of choice below to learn how to set up your development environment:
Node.js
Python
C# and ASP.NET MVC
PHP
Java
Ruby
Go
How to track outbound message status
Tracking the message status of an outbound message is a two-step process:
Set up a status callback endpoint
How are status callback requests sent?
Implement a status callback handler (simplified example)
Send a message with status callback URL
Scenario 1: No Messaging Service
Scenario 2: Messaging Service used
Step 1. Set up a status callback endpoint
To track the message status of an outbound message, you must first create an API endpoint that:
Is served under a publicly accessible URL (the status callback URL)
Implements a status callback handler for Twilio's message status callback HTTP requests.
(warning)
Warning
A status callback URL must contain a valid hostname. Underscores are
not
allowed.
How you implement your status callback endpoint depends on your use case and technology preferences. This may mean you
Create and host a small web application to handle the requests in the programming language and framework of your choice
Add an additional new endpoint to your existing web application
Use a serverless framework like
Twilio Serverless Functions
.
How are status callback requests sent?
Twilio sends status callback requests as
POST
requests with the
Content-Type
set to
application/x-www-form-urlencoded
.
(warning)
Warning
The properties included in Twilio's request to the StatusCallback URL vary by messaging channel and event type and are subject to change.
Twilio occasionally adds new properties without advance notice.
When integrating with status callback requests, it is important that your implementation is able to accept and correctly run
signature validation
on an evolving set of parameters.
Twilio strongly recommends using the signature validation methods provided in the SDKs and not implementing your own signature validation.
In a status callback request, Twilio provides a subset of the
standard request properties
, and additionally
MessageStatus
and
ErrorCode
. These properties are described in the table below.
Property
Description
MessageStatus
The
status
of the Message resource at the time the status callback request was sent.
ErrorCode
If an error occurred (i.e. the
MessageStatus
is
failed
or
undelivered
), this property provides additional information about the failure.
For example, a status callback request sent when the Message resource for an outbound SMS changes
status
to
sent
, may contain the following content:
Copy code block
1
"AccountSid"
:
"ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2
"From"
:
"+15017250604"
3
"MessageSid"
:
"SM1342fe1b2c904d1ab04f0fc7a58abca9"
4
"MessageStatus"
:
"sent"
5
"SmsSid"
:
"SM1342fe1b2c904d1ab04f0fc7a58abca9"
6
"SmsStatus"
:
"sent"
SMS/MMS
For most SMS/MMS Messages that have a
Status
of
delivered
or
undelivered
, Twilio's request to the
StatusCallback
URL contains an additional property:
Property
Description
RawDlrDoneDate
This property is a passthrough of the Done Date included in the DLR (Delivery Receipt) that Twilio received from the carrier.
The value is in
YYMMDDhhmm
format.
YY
is last two digits of the year (00-99)
MM
is the two-digit month (01-12)
DD
is the two-digit day (01-31)
hh
is the two-digit hour (00-23)
mm
is the two-digit minute (00-59).
Learn more on the
"Addition of RawDlrDoneDate to Delivered and Undelivered Status Webhooks" Changelog page
.
RCS, WhatsApp, and other messaging channels
If the Message resource uses RCS, WhatsApp, or another messaging channel, Twilio's request to the
StatusCallback
URL contains additional properties. These properties are listed in the table below.
Property
Description
ChannelInstallSid
The
Installed Channel
SID that was used to send this message
ChannelStatusMessage
The error message returned by the underlying messaging channel if Message delivery failed. This property is present only if the Message delivery failed.
ChannelPrefix
The channel-specific prefix identifying the messaging channel associated with this Message
EventType
This property contains information about post-delivery events. If the channel supports read receipts (currently RCS and WhatsApp), this property's value is
READ
after the recipient has read the message.
Implement a status callback handler (simplified example)
(information)
Info
You may want to explore how status callback requests behave before working through your actual implementation. A lightweight way to accomplish this goal is to use
Twilio Serverless Functions
and inspect status callbacks
in the Console by using the Function Editor's debugging feature
.
Log into your Twilio Account
If you do not already have a suitable
Functions and Assets Service
in your Console, you can
create a new service
for your status callback handler endpoint. Let's assume you created a new service under the name
status-callback-prototyping
.
From your service go to the
Functions Editor
to
Add
a new Function e.g. under the path
/message-status
with the following handler code:
Copy code block
1
// Log Status Callback requests
2
3
exports
.
handler
= function
(
context
,
event
,
callback
) {
4
console.
log
(
"Invoked with: "
, event);
5
return
callback
(
null
,
"OK"
);
6
};
By default your new serverless function is
created as a protected endpoint
, which means Twilio Serverless performs signature validation to ensure only valid Twilio requests invoke your handler.
Save
the new function.
Deploy your new serverless function by pressing
Deploy All
.
Change the toggle control above the bottom-right corner logging window to
Live logs on
.
Click on the
Copy URL
link above the bottom-right logging window to copy the URL for your prototype status callback endpoint into your clipboard. The copied URL would look something like this:
https://status-callback-prototyping-1234.twil.io/message-status
.
You can now use your copied status callback URL in the next step of this guide:
Step 2. Send a message with status callback URL
.
Once you sent a message, you can inspect the logged status callback request in the bottom-right logging window of the Functions Editor in Console.
Expand image
Your response to Twilio's status callback request should have an HTTP status code of
200
(OK). No response content is required.
What your status callback handler should do when receiving a status callback request, depends on your use case.
The following simplified web application illustrates how you could log the
MessageSid
and
MessageStatus
of outbound messages as they move through their lifecycle.
(warning)
Warning
Status callback requests are HTTP requests and are therefore subject to differences in latency caused by changing network conditions.
Status callback requests are sent in accordance with the message status transitions described in the guide
Outbound Message Status in Status Callbacks
. Some of these status transitions may occur in quick succession.
As a result, there is no guarantee that the status callback requests always arrive at your endpoint in the order they were sent.
You should bear this consideration in mind when implementing your status callback handler.
(information)
Info
Read our guide
Best Practices for Messaging Delivery Status Logging
for advanced considerations when implementing a production-grade status logging solution.
Handle a Message status callback request
.css-1raivgc{box-sizing:border-box;background-color:inherit;color:inherit;font-family:inherit;line-height:1.75rem;padding-top:0.5rem;padding-bottom:0.5rem;padding-left:0.25rem;}
Node.js
Python
C#
Java
Go
PHP
Ruby
Report code block
Copy code block
1
const
http
=
require
(
'http'
);
2
const
express
=
require
(
'express'
);
3
const
bodyParser
=
require
(
'body-parser'
);
4
5
const
app
=
express
();
6
7
app.
use
(bodyParser.
urlencoded
({ extended:
true
}));
8
9
app.
post
(
'/message-status'
, (
req
,
res
)
=>
{
10
const
messageSid
=
req.body.MessageSid;
11
const
messageStatus
=
req.body.MessageStatus;
12
13
console.
log
(
`SID: ${
messageSid
}, Status: ${
messageStatus
}`
);
14
15
res.
sendStatus
(
200
);
16
});
17
18
http.
createServer
(app).
listen
(
1337
, ()
=>
{
19
console.
log
(
'Express server listening on port 1337'
);
20
});
Step 2. Send a message with status callback URL
In Step 1 you implemented a status callback handler which is publicly available at your status callback URL.
In this step you learn how to ensure Twilio sends status callback requests to your status callback URL for outbound messages.
How you do this may depend on whether you use a Messaging Service to send messages or not.
Scenario 1: No Messaging Service
For Twilio to send status callback requests, you need to provide your status callback URL in the
StatusCallback
parameter of each message for which you want to track the
MessageStatus
.
To get the following code sample to run, replace these values:
Replace the
From
phone number with
one of your Twilio numbers
Replace the
To
number with your mobile number
Replace the
StatusCallback
URL with your status callback URL
Send a Message without Messaging Service with a StatusCallback URL
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
Report code block
Copy code block
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const
twilio
=
require
(
"twilio"
);
// Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const
accountSid
=
process.env.
TWILIO_ACCOUNT_SID
;
7
const
authToken
=
process.env.
TWILIO_AUTH_TOKEN
;
8
const
client
=
twilio
(accountSid, authToken);
9
10
async function
createMessage
() {
11
const
message
= await
client.messages.
create
({
12
body:
"McAvoy or Stewart? These timelines can get so confusing."
,
13
from:
"+15017122661"
,
14
statusCallback:
"http://example.com/MessageStatus"
,
15
to:
"+15558675310"
,
16
});
17
18
console.
log
(message.body);
19
}
20
21
createMessage
();
Response
Copy response
1
{
2
"account_sid"
:
"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
,
3
"api_version"
:
"2010-04-01"
,
4
"body"
:
"McAvoy or Stewart? These timelines can get so confusing."
,
5
"date_created"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
6
"date_sent"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
7
"date_updated"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
8
"direction"
:
"outbound-api"
,
9
"error_code"
:
null
,
10
"error_message"
:
null
,
11
"from"
:
"+15017122661"
,
12
"num_media"
:
"0"
,
13
"num_segments"
:
"1"
,
14
"price"
:
null
,
15
"price_unit"
:
null
,
16
"messaging_service_sid"
:
"MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
,
17
"sid"
:
"SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
,
18
"status"
:
"queued"
,
19
"subresource_uris"
: {
20
"media"
:
"/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"to"
:
"+15558675310"
,
23
"uri"
:
"/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24
}
Scenario 2: Messaging Service used
Messaging Services can be configured to have a service-level Delivery Status Callback. When
creating a new Messaging Service in Console
, you can specify this service-level Delivery Status Callback in
Step 3 - Set up Integrations
.
You can use the status callback URL from Step 1 of this guide for this Delivery Status Callback integration. If you do so, you do not have to provide the status callback URL as a message-specific parameter.
Alternatively, you can provide a message-specific status callback URL in the
StatusCallback
parameter for a message created with the Messaging Service.
Which of these two options is more appropriate depends on your use case.
Option 1 - Use Service-level Delivery Status Callback
To get the following code sample to run, replace these values:
Replace the
MessagingServiceSid
with the SID of one of your Messaging Services that has a Delivery Status Callback integration configured in Console
Replace the
To
number with your mobile number
Send a Message using Messaging Service with Delivery Status Callback Integration
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
Report code block
Copy code block
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const
twilio
=
require
(
"twilio"
);
// Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const
accountSid
=
process.env.
TWILIO_ACCOUNT_SID
;
7
const
authToken
=
process.env.
TWILIO_AUTH_TOKEN
;
8
const
client
=
twilio
(accountSid, authToken);
9
10
async function
createMessage
() {
11
const
message
= await
client.messages.
create
({
12
body:
"McAvoy or Stewart? These timelines can get so confusing."
,
13
messagingServiceSid:
"MG9752274e9e519418a7406176694466fa"
,
14
to:
"+15558675310"
,
15
});
16
17
console.
log
(message.body);
18
}
19
20
createMessage
();
Response
Copy response
1
{
2
"account_sid"
:
"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
,
3
"api_version"
:
"2010-04-01"
,
4
"body"
:
"McAvoy or Stewart? These timelines can get so confusing."
,
5
"date_created"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
6
"date_sent"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
7
"date_updated"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
8
"direction"
:
"outbound-api"
,
9
"error_code"
:
null
,
10
"error_message"
:
null
,
11
"from"
:
"+14155552345"
,
12
"num_media"
:
"0"
,
13
"num_segments"
:
"1"
,
14
"price"
:
null
,
15
"price_unit"
:
null
,
16
"messaging_service_sid"
:
"MG9752274e9e519418a7406176694466fa"
,
17
"sid"
:
"SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
,
18
"status"
:
"queued"
,
19
"subresource_uris"
: {
20
"media"
:
"/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"to"
:
"+15558675310"
,
23
"uri"
:
"/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24
}
Option 2 - Use Message-specific status callback URL
(information)
Info
If your Messaging Service has a service-level Delivery Status Callback configured in the Console and you provide a message-specific
StatusCallback
URL, Twilio sends status callback requests to the message-specific
StatusCallback
URL.
To get the following code sample to run, replace these values:
Replace the
MessagingServiceSid
with the SID of one of your Messaging Services
Replace the
To
number with your mobile number
Replace the
StatusCallback
URL with your status callback URL
Send a Message using Messaging Service and StatusCallback URL
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
Report code block
Copy code block
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const
twilio
=
require
(
"twilio"
);
// Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const
accountSid
=
process.env.
TWILIO_ACCOUNT_SID
;
7
const
authToken
=
process.env.
TWILIO_AUTH_TOKEN
;
8
const
client
=
twilio
(accountSid, authToken);
9
10
async function
createMessage
() {
11
const
message
= await
client.messages.
create
({
12
body:
"McAvoy or Stewart? These timelines can get so confusing."
,
13
messagingServiceSid:
"MG9752274e9e519418a7406176694466fa"
,
14
statusCallback:
"http://example.com/MessageStatus"
,
15
to:
"+15558675310"
,
16
});
17
18
console.
log
(message.body);
19
}
20
21
createMessage
();
Response
Copy response
1
{
2
"account_sid"
:
"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
,
3
"api_version"
:
"2010-04-01"
,
4
"body"
:
"McAvoy or Stewart? These timelines can get so confusing."
,
5
"date_created"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
6
"date_sent"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
7
"date_updated"
:
"Thu, 24 Aug 2023 05:01:45 +0000"
,
8
"direction"
:
"outbound-api"
,
9
"error_code"
:
null
,
10
"error_message"
:
null
,
11
"from"
:
"+14155552345"
,
12
"num_media"
:
"0"
,
13
"num_segments"
:
"1"
,
14
"price"
:
null
,
15
"price_unit"
:
null
,
16
"messaging_service_sid"
:
"MG9752274e9e519418a7406176694466fa"
,
17
"sid"
:
"SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
,
18
"status"
:
"queued"
,
19
"subresource_uris"
: {
20
"media"
:
"/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"to"
:
"+15558675310"
,
23
"uri"
:
"/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
24
}
What's next?
Now that you know how to track the message status of your outbound messages, check out the resources below for additional information and related Twilio product documentation:
Read our guide
Best Practices for Messaging Delivery Status Logging
for advanced considerations when implementing a production-grade status logging solution.
Explore our guide
How to Optimize Message Deliverability with Message Feedback
.
See how Message Feedback supports the
Messaging Insights "One-time Password (OTP) Conversion Report"
. Learn how to analyze the effectiveness of messages sent to provide two-factor authentication (2FA) or multi-factor authentication (MFA) codes or other one-time passwords for user authentication or account verification.
Shorten links in messages with your own company-branded domain and track click-through-rates with
Link Shortening
.
Need some help?
We all do sometimes; code is hard. Get help now from our
support team
, or lean on the wisdom of the crowd by browsing the
Twilio tag
on Stack Overflow.
Terms of service
Privacy Policy
Copyright © 2026 Twilio Inc.
