Diagnosing Twilio SMS Stuck in Queued or Undelivered Status

Recognizable Condition

You send an SMS via Twilio (REST API or Messaging Service) and the message resource shows SmsStatus of queued or undelivered. No StatusCallback webhook fires, or the callback arrives with an ErrorCode such as 30003, 30005, 30006, 30007, or 30008. In the Twilio Console message logs you see no outbound HTTP request from Twilio to your endpoint, or the request returns a non‑2xx status.

Cause / Diagnostic Table

Error Code	Common Meaning	Typical Trigger
30003	Unreachable destination / blocked	Carrier or handset blocked the number; destination may be on a do‑not‑call list.
30005	Unknown destination	Invalid E.164 format, deactivated number, or carrier cannot route.
30006	Landline or invalid	Destination is a landline (no SMS capability) or fails validation.
30007	Carrier spam filter	Message content, links, or sender reputation triggered filtering.
30008	Unknown error	Generic carrier failure; often transient but may indicate deeper routing issues.

Cross‑reference the ErrorCode with the Carrier field in Messaging Insights. The same code can have different root causes depending on the destination country and carrier.

Ordered Checks

1. Verify StatusCallback reachability – Ensure the callback URL is set on the Message resource or Messaging Service and responds with 200 OK within 15 seconds. Twilio retries on non‑2xx or timeout, but excessive failures disable the callback.

   # Test from the server that hosts your webhook
   curl -v -X POST "https://your-app.example.com/twilio/status" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "MessageSid=SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&MessageStatus=delivered&ErrorCode=0"
   

   Run on: the host that receives Twilio callbacks. Permissions: network egress to your domain. Placeholders: replace the URL and a valid MessageSid. Expected: HTTP 200 with empty body. Risk: exposing a test endpoint publicly; use a staging domain.

2. Inspect Messaging Insights or message logs – Pull the failed message’s ErrorCode, Carrier, and Price fields.

   # Using Twilio CLI (v2.x) – run locally with authenticated profile
   twilio api:core:messages:fetch --sid SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
     --properties error_code,carrier,price,status
   

   Run on: developer machine with Twilio CLI installed and logged in (twilio login). Permissions: Account SID / Auth Token with Message read scope. Placeholders: message SID. Expected: JSON output showing error_code and carrier name. Risk: CLI credentials stored in config; avoid committing them.

3. Confirm sender health – Check that the MessagingServiceSid or From number is active, not in a carrier violation state, and matches the destination country’s sender‑type rules (toll‑free, short code, 10DLC).

   twilio api:messaging:v1:services:fetch --sid MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   

4. Test with a known‑working destination and plain‑text body – Send a minimal message (e.g., "Test") to a verified mobile number you control. This isolates content filtering.

Fixes Tied to Findings

Missing or Failing StatusCallback

• Ensure the endpoint uses valid TLS (certificate chain trusted by public CAs). Self‑signed certs cause silent failures.
• Confirm the URL is publicly reachable (no VPN, firewall, or IP allow‑list blocking Twilio’s egress IPs). Twilio publishes its IP ranges; allow them if you restrict inbound.
• Respond with 200 OK and an empty body within 15 s. Any other status or timeout counts as failure.
• After fixing, resend the message or use the Message resource’s POST /Messages/{Sid}/Feedback to retry (if applicable).

Error 30007 – Carrier Spam Filter

• Remove opt‑out keywords ("STOP", "UNSUBSCRIBE") from promotional bodies unless you honor them via Twilio’s Advanced Opt‑Out.
• Strip URL shorteners and suspicious links; use branded domains with proper reputation.
• If using toll‑free or 10DLC, verify registration is complete and approved in the Twilio Console (Messaging → Senders).
• Consider moving high‑volume traffic to a registered short code, which has higher throughput and less filtering.

Error 30003 / 30005 – Unreachable or Unknown Destination

• Validate E.164 formatting: +[country code][subscriber number] with no spaces, dashes, or leading zeros.
• Scrub landline numbers using a number‑lookup API (Twilio Lookup or third‑party) before sending.
• For international destinations, confirm the sender type supports that country (e.g., US short codes cannot send to Canada).

Sender Violation or Suspension

• Open the Twilio Console → Messaging → Senders; look for "Violation" or "Suspended" status.
• Submit an appeal with sample message logs and proof of opt‑in compliance.
• As a temporary workaround, switch to a different verified sender (another toll‑free number or Messaging Service) while the appeal processes.

Escalation Criteria

Open a Twilio Support ticket (via Console → Help → Contact Support) when:

• Error codes persist after correcting sender registration, content, and destination validation.
• Messaging Insights shows carrier‑level filtering (ErrorCode 30007) without a documented cause for your specific sender and destination pair.
• Delivery rates drop below your historical baseline across multiple countries or senders for more than 24 hours.
• You suspect a platform‑wide issue (check Twilio Status first).

Include in the ticket: Message SIDs, timestamps, ErrorCode, carrier names, sender SIDs, and the steps you’ve already taken.

Verification Steps

1. Send a test SMS to a verified, working mobile number with a StatusCallback URL configured.

   curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
     -u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token \
     -d To=+15551234567 \
     -d From=+15557654321 \
     -d Body="Test message" \
     -d StatusCallback=https://your-app.example.com/twilio/status

2. Confirm you receive the callback sequence: queued → sent → delivered (or failed with an ErrorCode). All callbacks must share the same MessageSid.
3. In the Console or via CLI, inspect the message log for the test SID and verify ErrorCode is absent or 0.
4. Reproduce the original failure with a plain‑text body. If it succeeds, reintroduce variables (links, variables, sender) one at a time to pinpoint the filter trigger.

Limitations & Practical Checks

• Error codes are not globally uniform. A 30003 in the US may mean "blocked by carrier" while in another country it could indicate a temporary routing issue. Always correlate with the Carrier field.
• Status callbacks are best‑effort. Twilio does not guarantee delivery of the callback itself. A missing callback does not prove the SMS wasn’t delivered; always check the message resource’s final Status.
• Sender‑type rules differ. Toll‑free, 10DLC, and short codes each have distinct registration, throughput, and filtering behaviors. Changing content without updating sender registration can worsen filtering.
• Never embed Account SID or Auth Token in client‑side code or public repos. Use server‑side environment variables and rotate credentials if exposed.

Practical verification: After applying a fix, run the test sequence above for at least three distinct destination numbers (different carriers if possible) and confirm delivered callbacks with zero error codes. Track delivery rate over 24 hours before declaring the issue resolved.