Message Delivery Flow
Communication between Mainstay and SMS recipients are sent through a few systems:
Mainstay <---> Twilio <---> phone carrier <---> recipient device
This is true whether a message is part of a Campaign, a question-and-answer exchange with the bot, or a Live Chat. Each of these systems is also a potential point of failure.
Mainstay occasionally fails to generate and send the message, whether due to a bug in our code or due to "upstream" outages with our platform providers, like Heroku and Amazon. This is the rarest form of delivery failure, and our automatic retry feature will attempt to send again right away. If it's more than a momentary outage and that retry doesn't work, then Mainstay Support or your Partner Success Manager will reach out.
Our SMS provider, Twilio, then forwards the message content to the phone carrier, if one can be identified. At this point, it's possible that the phone number is not registered, or corresponds to a landline device, so you might see an error like this in the Conversations page:
To see a list of all Twilio error codes, visit https://www.twilio.com/docs/api/errors. The most common ones are listed below.
Assuming the phone number is valid, Twilio will pass the content along to the phone carrier. At this point, carrier-specific policies may impact deliverability. For example, many carriers have spam filters to prevent dangerous messages; sometimes, partner messages get caught by mistake. The Conversations page might show something like this:
The carriers don't make these spam filter rules publicly available (since bad actors would then know exactly how to work around them!). But in general, we recommend avoiding generic link shorteners, since these are often used by spammers. Instead, many partners use their own branded link shorteners, or the mainst.ai link shortener built in to the Script Builder and Knowledge Base editor:
Additionally, terms like "free money!" can cause a message to be blocked - even if you're talking about scholarships.
Finally, the message is forwarded to the individual recipient. However, users can opt out of receiving messages, in which case the Conversations page might show this:
These individuals have indicated they don't want to receive messages to their phones, so we recommend respecting that boundary. If it's an urgent and important message, you can also try reaching out through another channel, such as email.
Delivery Failures - Contacts & Audiences
As shown above, individual messages will indicate any delivery issues in the Conversations page.
Additionally, when viewing an individual contact in the Conversations tool or the Contacts tool, the number of delivery issues will be listed on their profile:
This information is also available to use when building an Audience, to find people who do or do not have delivery failures:
Delivery Failures - Campaigns
If messages fail to send as part of a Campaign, information about the failures will be included in the Campaign Report page:
Clicking in for More detail reveals counts for each situation:
Details on each individual recipient are available in the downloaded report:
- Total Messages Sent - the number of messages this person was meant to receive
- Total Messages Delivered - the number of messages they actually received
- Failed Message Count - the number of messages that failed to be received
- Failed Message Codes - the list of error codes (see below) for those failed messages
Error Codes & Suggested Actions
11751 (Message media exceeds size limit)
You might see this if you attach a high-resolution image, or a long GIF, when sending a Script. Mainstay recommends keeping those file attachments under 5 MB.
12300 (Message uses invalid content type)
This error means a message included an attachment that is not supported. Mainstay supports PNG, JPEG, and GIFs in the Script Builder.
21211 (Invalid phone number)
The phone number provided is not properly formatted. Mainstay validates phone numbers during the manual import, API/integration import, and in-app editing processes, so this issue is generally resolved long before a message is sent.
21610 (Blocked by prior opt-out or #pause)
Users can opt out using the keyword #pause, which sends a signal to Mainstay to stop trying to send them messages; they can choose whether to make this permanent (until they send #unpause) or to automatically unpause after 2 weeks.
Users can also opt out of messages with the keyword STOP, which sends a signal to their phone carrier to block incoming messages.
21611 (Campaign exceeded the max. number of queued messages)
This is rare, but campaigns with an exceptionally large recipient count can be problematic. To mitigate this:
- Double-check the logic of your Audience or the size of the Import used to send this Campaign. Does the number of contacts in that list match your expectations?
- If necessary, consider splitting the campaign up into multiple campaigns. For example, instead of a single CSV import, you could schedule a set campaigns, using the same script but across 2 or more CSV imports.
- Ensure that you are not attempting to message more contacts than covered in your Mainstay contract. Mainstay purchases phone numbers (through Twilio) to scale up to your expected volume, so if those needs have changed, please contact your Partner Success Manager.
21614 (Not a valid phone number)
The phone number is not currently assigned to a mobile device. For example, maybe the phone number was entered incorrectly, or corresponds to a landline. To troubleshoot this, we recommend reaching out to the learner through another communication channel, such as email.
21617 (Message exceeds carrier-enforced character limit)
This indicates that the phone carrier has a stricter character limit than Mainstay. Often, these messages are simply split into separate chunks, and then reassembled by the user's device upon receipt. If you encounter this message, consider shorter messages; note Mainstay's built-in character counter on Scripts and Knowledge Base responses.
30001 (Too many messages sent at once; Try again later)
Similar to 21611, we recommend double-checking that you are sending the messages to the people you intend to message. Another potential issue could be scheduling too many campaigns at the same time - are any of your recipients accidentally included in multiple conflicting campaigns?
30003 (Number is unknown or no longer in service)
As with 21614, double-check that this is the correct phone number for this learner. If necessary, consider contacting them through other means, such as email.
30004 (Device cannot be reached)
This is a more general error that can indicate multiple causes, including that the end user has blocked this bot phone number. As above, consider contacting the user through other means.
30005 (Device cannot be reached and may no longer exist)
This error suggests the destination handset is unknown, and may not exist any more. As above, consider contacting the user through other means.
30006 (Landline or unreachable carrier)
When we receive this error code from Twilio, there's a stronger indication that the phone number corresponds to a landline phone number. This often happens when phone numbers are collected via web forms or Mainstay's web-chat. Wherever you are collecting lead information, make sure you specify the user should give a mobile number.
If you have a contact data integration, make sure you are correctly mapping the mobile phone to the Mainstay phone field.
30007 (Blocked by carrier spam filter)
Outside of invalid/landline phones, this is the most common error we see. This indicates that the phone carrier's spam detection picked up on something in the message and prevented the user from receiving it. These rules are not consistent between carriers, so it's possible that some learners (say, on Verizon) will receive a message while others (say, on AT&T) will not.
Unfortunately, identifying the exact issue can be tricky. If possible, we recommend sending variations of the offending message to different members of your team who have different phone carriers to find a version that will be acceptable to the most providers.
As we suggest above, avoid using terms like "free money" - these filters are often looking for keywords or phrases, regardless of context. Additionally, avoid generic link shorteners and instead use a branded link shortener or the mainst.ai link shortener built in to the Script Builder and Knowledge Base responses:
See Tips to Avoid SMS Carrier Blocks.
30008 (Unknown error)
This indicates that the carrier did not give any specific information about why a message was not received. If you see this error, you can contact Mainstay Support, who can request additional information from Twilio, but it is generally faster to try sending the message again, or communicating with the contact through another channel.
30023 (Daily message cap reached)
In March 2022, some carriers imposed new restrictions on message caps from bot numbers. Visit https://support.twilio.com/hc/en-us/articles/1260800720410-What-is-A2P-10DLC- for more information.
Article is closed for comments.