SMS Delivery Checklist (First 10 Minutes)¶

When SMS delivery failures occur, follow this checklist to quickly isolate the cause.

Immediate Checklist¶

1. Check Phone Number Status: Is the number active?
2. Review Opt-out Lists: Is the recipient on a suppression or STOP list?
3. Analyze Message Content: Does it contain spam keywords or suspicious URLs?
4. Check Rate Limits: Are you exceeding your throughput (MPS) limits?
5. Verify Number Format: Is the recipient number in correct E.164 format?

flowchart TD
    S["SMS send or delivery failing"] --> C1{"Sender phone number active?"}
    C1 -- no --> A1["Reprovision or replace the number"]
    C1 -- yes --> C2{"Recipient on a suppression or STOP list?"}
    C2 -- yes --> A2["Remove only via proper opt-in flow"]
    C2 -- no --> C3{"Content has spam keywords or suspicious URLs?"}
    C3 -- yes --> A3["Revise message content"]
    C3 -- no --> C4{"Exceeding MPS throughput limits?"}
    C4 -- yes --> A4["Throttle to the number's MPS limit"]
    C4 -- no --> C5{"Recipient number in E.164 format?"}
    C5 -- no --> A5["Correct the number format"]
    C5 -- yes --> ESC["Escalate to the SMS Delivery Failures playbook"]

Essential CLI Commands¶

# List the phone numbers provisioned on the ACS resource
az communication phonenumber list --connection-string "<your_connection_string>"

# Delivery status is not read from the CLI. Request a delivery report when sending,
# then consume the result through Event Grid (SMS Delivery Report event).
az communication sms send --sender "<from_number>" --recipient "<to_number>" --message "test" --deliveryReport --connection-string "<your_connection_string>"

Key KQL Queries¶

Run this in Log Analytics to see recent delivery failures and their reasons:

ACSSMSIncomingOperations
| where TimeGenerated > ago(1h)
| where OperationName == "SMSDeliveryReportsReceived"
| where ResultType == "Failed"
| summarize Count = count() by ResultDescription, ResultSignature, PhoneNumber
| order by Count desc

Immediate Triage Questions¶

• Is the failure happening for all carriers or just one?
• Are you sending international messages from a local number?
• Is your ACS resource in a region that supports the destination?

See Also¶

• SMS Delivery Failures Playbook
• SMS Rate Limiting Playbook

Sources¶

• Azure Communication Services SMS Troubleshooting Documentation
• Global SMS Carrier Best Practices