Managing SMS Undelivered
Overview
SMS Undelivered helps identify recipients whose mobile numbers cannot successfully receive text messages. When an SMS send is determined to be undelivered, the Communication Planner records the event on the recipient’s record so users can review delivery issues and make informed decisions about future outreach.
What is SMS Undelivered?
An SMS message is classified as Undelivered when TargetX receives a delivery status from Twilio indicating that the message could not be delivered to the recipient. This terminology aligns with Twilio’s delivery-status classification.
Not every message that does not reach a recipient is classified as Undelivered. SMS delivery can fail for many reasons, and Twilio may assign other statuses, such as Failed or Dropped, depending on the issue. TargetX records common undelivered delivery activity in the CRM to prevent unnecessary message retries and help staff identify recipients whose phone numbers may require attention. Communication Planner automatically excludes records with SMS Undelivered selected, so you do not need to include this field as a filter in your recipient report.
What Happens When a Recipient Is Marked as SMS Undelivered?
If a text message cannot be delivered to a recipient’s mobile number, Communication Planner may mark the recipient as SMS Undelivered.
When a recipient is marked as SMS Undelivered:
- Future SMS messages from the Communication Planner will be blocked for that recipient.
- The recipient will no longer receive automatic SMS retry attempts.
- The reason for the delivery issue is recorded in the SMS Undelivered Reason field.
- The delivery issue date is recorded in the SMS Undelivered Date field.
This helps prevent repeated attempts to send messages to phone numbers that cannot receive SMS messages.
What Can Cause an SMS to Be Marked as Undelivered?
The SMS Undelivered status means that Twilio received a delivery receipt confirming that the message was not delivered. This can occur when the issue is related to the recipient’s phone number, mobile carrier, or SMS subscription status.
Common examples include:
- The phone number is invalid or incorrectly formatted.
- The phone number no longer exists.
- The phone number cannot receive text messages.
- The number is a landline.
- The recipient has unsubscribed from SMS messages.
- The recipient or carrier has blocked the message.
- The mobile device is unreachable.
- The carrier rejected delivery of the message.
In these situations, continuing to send SMS messages is unlikely to be successful, so Communication Planner prevents future SMS sends until the issue is reviewed.
Communication Planner blocks message retries, and future SMS sends when a contact is marked as SMS Undelivered for any of the following reasons:
|
Error Code |
Error Message |
Description |
|---|---|---|
| 21211 |
Invalid 'To' Phone Number | You attempted to initiate an outbound phone call or send a message, but the `To` phone number you supplied was not a valid phone number or was incorrectly formatted. |
| 21610 |
Attempt to send to unsubscribed recipient | You have attempted to message a 'To' number that has replied with "STOP" to one of your previous messages. You will not be able to send to the phone number specified in the 'To' parameter until the subscriber identified by the phone number has responded with "START". |
| 21611 |
This 'From' number has exceeded the maximum number of queued messages | The sending (“From”) phone number has reached its maximum queue of outbound messages. Twilio cannot accept another message from that sender until queued messages are processed. |
| 21612 |
Message cannot be sent with the current combination of "To" and/or "From" parameters | The message cannot be sent with the current combination of recipient (“To”) and sender (“From”) parameters. In other words, Twilio cannot route an SMS or MMS from that sender to that recipient. |
| 30003 | Unreachable destination handset | The destination handset you are trying to reach is switched off or otherwise unavailable. |
| 30004 | Message blocked | The destination number you are trying to reach is blocked from receiving this message (e.g., due to blacklisting). |
| 30005 | Unknown destination handset | The destination number you are trying to reach is unknown and may no longer exist. |
| 30006 |
Landline or unreachable carrier | The destination number is unable to receive this message. Potential reasons could include trying to reach a landline or, in the case of short codes, an unreachable carrier. |
| 30007 |
Carrier violation | Your message was flagged as objectionable by the carrier. To protect their subscribers, many carriers have implemented content or spam filtering. |
How the Fields are Updated
When a text message is identified as undelivered, Communication Planner automatically updates the recipient record with the SMS Undelivered status, the event date, and the reason for the delivery issue.
Common Use Cases
- Identify invalid or outdated mobile numbers.
- Create Reports showing recipients with delivery issues.
- Review recent SMS delivery problems.
Viewing SMS Delivery Details
Users can add the SMS Undelivered fields to Salesforce page layouts, Reports, and list views to monitor recipients who have experienced SMS delivery issues.
Frequently Asked Questions
What does Undelivered mean?
The text message was attempted but could not be successfully delivered.
Can I see why a message was undelivered?
Yes. Review the SMS Undelivered Reason field on the recipient record.
Can I report on undelivered messages?
Yes. The SMS Undelivered fields can be used in Reports, filters, and list views.
Can SMS sending be re-enabled?
Yes. If the underlying issue has been resolved, authorized users can clear the SMS Undelivered indicator to allow future SMS sending.
Will my recipient report need to filter on ‘SMS Undelivered’?
No. The Communication Planner checks whether the recipient record is marked as SMS Undelivered before attempting a send.