Troubleshooting failed messages
What the most common SMS / iMessage / email failure modes look like and how to recover.
When a message fails to deliver we mark it failed in the conversation view and surface a reason from the underlying provider. Below are the most common reasons and how to recover.
SMS via Twilio
Common failure codes:
- 21610 / 21408 - the recipient opted out via STOP. We respect this; we will not send to that number again until they reply START.
- 21211 - invalid To number. Usually the phone column had bad data on import. Fix the lead's phone and try again.
- 30007 - carrier filtered the message as spam. Often happens when the message has too many emojis or links. Edit the template and resend.
- 21408 - permission to send region not enabled. Twilio's geographic permissions setting needs the destination country enabled.
iMessage via Bridge v2
- "Bridge unreachable" - the Mac mini in our datacenter is offline. We re-push automatically every two minutes; the message will deliver as soon as the bridge reconnects. If it stays offline more than 10 minutes, page on-call.
- "Recipient is not iMessage capable" - the recipient is on Android or has iMessage off. We auto-fall back to SMS via Twilio when the bridge tells us this; if no Twilio is connected the message just sits.
- "Message sent but read receipt never arrived" - this is normal. iMessage read receipts depend on the recipient enabling them. Delivery is what matters.
Email via SendGrid or Google
- 401 - the API key is wrong. Reconnect the integration.
- 403 - SendGrid sender is not verified. Finish sender authentication.
- Bounce - the recipient's mailbox is bad. Update the lead's email; bounces stop drip campaigns for that lead until you do.
When everything looks broken at once
Settings -> Integrations -> Health check. The page runs a live status probe against every connected provider and shows which one is failing. If a provider that was working stops working, this is usually the fastest way to triage.