An undelivered SMS in Twilio is not a single problem: it is a final status that can be caused by at least a dozen different failure conditions at different points in the delivery chain, from your API request through Twilio's platform to the carrier network to the handset. The Twilio Console logs and error codes together identify exactly which point in that chain failed, and each failure point has a specific fix. This guide walks you through the complete diagnostic sequence in order of most to least common cause.
Understanding the SMS Delivery Pipeline
Every SMS sent through Twilio passes through at least four stages before reaching the recipient's handset: your application's API request to Twilio, Twilio's internal message processing and routing, the carrier handoff where Twilio passes the message to the recipient's mobile carrier, and the carrier's delivery attempt to the destination handset. Each stage can fail independently and produces a different error code: failures at the Twilio layer produce 20xxx or 21xxx codes, failures at the carrier routing layer produce 30xxx codes, and failures at the handset layer produce codes like 30003 (unreachable handset) or 30006 (landline). The message status field in the Console log shows which stage reached completion: queued means the API request was accepted, sending means it was dispatched to the carrier, sent means the carrier accepted it, and delivered or undelivered reflects the carrier's delivery report back to Twilio. Understanding that undelivered means the carrier received the message but could not deliver it to the handset, while failed means the message never left Twilio, is the critical distinction that routes your entire investigation.
Step-by-Step Diagnostic Process
Open the Twilio Console and navigate to Monitor, then Logs, then Messages and find the specific message by its SID, To number, or timestamp: click the entry to open the detail view and note the final status, the error code (if shown), and the exact timestamp of each status transition. If the status is undelivered and an error code is present, look up the error code immediately: 30003 (unreachable handset) means the recipient's phone is off or out of coverage, 30004 (message blocked) means the carrier filtered it for content or compliance reasons, and 30007 (carrier violation) means your content or sending pattern triggered a carrier block. If the status is undelivered with no error code, the message experienced silent carrier filtering where the carrier dropped it without returning a delivery failure receipt to Twilio: this requires testing with a different carrier's number to isolate whether the issue is carrier-specific. Check the From number used to send the message: navigate to Console, then Phone Numbers, then Active Numbers and confirm the number is Active, has SMS capability enabled, and is not in a suspended state due to carrier compliance issues.
Common Causes of Undelivered Messages
Using a long code (10DLC) number to send messages without completing A2P 10DLC registration causes carriers to block messages with a 30007 error code: verify your registration status by navigating to Console, then Messaging, then Regulatory Compliance and confirming your Brand and Campaign are both approved. Sending to landline numbers or VoIP numbers that do not support SMS produces a 30006 error: validate destination numbers using the Twilio Lookup API with type=carrier before sending to confirm the line type is mobile. Content that triggers carrier spam filters, including messages with shortened URLs from public URL shorteners, messages with certain promotional keywords, or messages without a required opt-out phrase, results in silent carrier blocking or a 30004 error: test by sending a plain-text message with no links to the same recipient and comparing delivery results. Exceeding the throughput limit for your sending number (1 message per second for a standard long code, 10 per second for a Toll-Free number, up to 100 per second for a short code) causes messages to be queued beyond Twilio's queuing window and eventually rejected: check the message creation timestamp against the sent timestamp in the log to identify queuing delays longer than 5 minutes.
When to Escalate to Twilio Support
Escalate to Twilio support when you have a specific message SID showing undelivered, the error code is 30007 (carrier violation), and you have verified that your 10DLC registration is fully approved and your content complies with carrier requirements: this combination suggests a carrier-side routing issue that Twilio can investigate with its carrier partners by providing the message SID. File a support ticket when a significant percentage of messages to a specific carrier (for example, T-Mobile or Verizon) are failing while messages to other carriers succeed, as this is a carrier route issue that Twilio's network team can investigate and remediate. Include in every support ticket: the affected Message SIDs (at least 3 to 5 examples), the sending phone number, the destination carrier if known, the time window of the failures, and your 10DLC Brand SID and Campaign SID so Twilio's support team has immediate context. A specialist can also run a carrier trace on your behalf by providing the message SIDs to Twilio's carrier connectivity team, which produces a hop-by-hop delivery trace that shows exactly where in the carrier network the message was dropped.
Conclusion
Debugging undelivered SMS in Twilio requires following the message through each stage of the delivery pipeline, using the error code to identify the specific failure point, and applying the targeted fix for that code rather than making broad changes that may introduce new problems. If your messages are showing undelivered and you cannot identify the cause, contact our team and we will diagnose and fix it within the hour.
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)
Be the first to comment
No comments yet. Share your thoughts below.