Message Delivery Failures & Error Codes

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

Mainstay sending issues

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 you see this error message and have questions, please reach out to Mainstay Support.

 

 

 

Twilio

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.

 

 

Phone Carrier

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.

 

 

Recipient Device

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:

 

The Contact panel will also indicate if Mainstay suspects this contact has an invalid phone. See "Error Codes & Suggested Actions" for which specific errors lead to this state. You can reset this status by clearing the phone number; this also resets if we successfully receive a message from this contact.

 

 

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.

This results in the contact being marked "Invalid Phone: true", which prevents sending future campaigns. Prior to 7/25/23, this resulted in an Opt Out.

 

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.

This results in an instant opt-out, which prevents sending future campaigns.

 

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.

This results in the contact being marked "Invalid Phone: true", which prevents sending future campaigns. Prior to 7/25/23, this resulted in an Opt Out.

 

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.

After 10 failures, the contact will be marked "Invalid Phone: true", which prevents sending future campaigns. Prior to 7/25/23, that would result in an Opt Out.

 

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.

After 10 failures, the contact will be marked "Invalid Phone: true", which prevents sending future campaigns. Prior to 7/25/23, that would result in an Opt Out.

 

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.

After 10 failures, the contact will be marked "Invalid Phone: true", which prevents sending future campaigns. Prior to 7/25/23, that would result in an Opt Out.

 

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.

 

30011 (MMS not supported by the receiving phone number in this region) 

If you received this error code, the recipient's device either doesn't support MMS, or MMS is not currently enabled for them.

 

30019 (Content size exceeds carrier limit)

This means the attachment (ie, image/GIF) was too big, and the carrier suppressed sending it. Mainstay recommends keeping those file attachments under 5 MB.

 

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.

 

30024 (Numeric Sender ID Not Provisioned on Carrier)

This means that the bot phone is not registered for A2P 10DLC for a particular carrier. If your bot phone was just registered, it could take a brief period of time for all carriers to provision the number. This may result in all messages towards a single carrier failing to send. Visit https://support.twilio.com/hc/en-us/articles/1260800720410-What-is-A2P-10DLC- for more information. 

 

30410 (Twilio Error)

Mainstay uses Twilio as our SMS provider. This error means there was an unhandled issue in their system. Please reach out to Mainstay support and we can investigate this with Twilio Support.