SMS Delivery Failures Playbook¶
Symptom: SMS not delivered to recipient.
Hypotheses¶
| Hypothesis | Likely Cause | Evidence Tag |
|---|---|---|
| Wrong phone format | Number not in E.164 format (e.g., missing +1) | [Observed] |
| Recipient opt-out | Recipient is on a STOP list or has previously opted out | [Inferred] |
| Carrier blocking | Content triggered spam filters or suspicious pattern detection | [Correlated] |
| Rate limiting | Exceeding the messages per second (MPS) limit for the number | [Measured] |
| Invalid number | Destination number is disconnected or does not exist | [Observed] |
Evidence Collection¶
1. Delivery Reports¶
Check the ACSSMSDeliveryReportEvents table in Log Analytics.
2. Monitor Metrics¶
Review the SmsMessagesSent vs SmsMessagesDelivered metrics in Azure Monitor.
3. CLI Check¶
Use the CLI to get the status of a specific message ID.
Validation¶
[Observed] Validate Phone Format¶
Ensure the number starts with + followed by the country code. If not, the SDK or service will reject the request with a 400 Bad Request.
[Inferred] Check Opt-out Status¶
Review recipient communication history. If they sent a STOP keyword, the carrier will block future messages.
[Measured] Review MPS Throttling¶
Check for 429 Too Many Requests in your app logs. Azure Monitor will show spikes in throttled requests.
Mitigation¶
- Fix Format: Normalize all phone numbers to E.164 before sending.
- Handle Opt-outs: Respect STOP keywords and implement a local suppression list.
- Optimize Content: Avoid short-links and suspicious keywords. Use a consistent sender name.
- Scale Throughput: If hitting rate limits, request a higher MPS limit or use a toll-free number.
See Also¶
Sources¶
- Azure SMS Delivery Report Status Codes
- CTIA Messaging Principles and Best Practices