Troubleshooting SMS Delivery

Symptom

When sending SMS, the message is not delivered. Unsuccessful delivery may include an error code.

Applies To

• Outbound SMS
• Error Codes
• Undelivered Messages

Resolution

Error Code Indicating API Request Not Accepted by Vonage

Message Not Delivered, Initial Response Code Successful (0)

In the case that Vonage accepted the API request, we will have passed the request to our supplier or operator and any failure occurred downstream. Review the following sections to determine the reason the SMS did not arrive.

Is the destination number a valid MSISDN?

Is the number valid and specified in the correct international format?

In many countries there is a difference between the local and the international format, or between SMS and voice calls. For instance, within the UK, numbers should start with a 0, but when calling or texting the number in the international format, one must add the international prefix (44) and remove the leading 0.

Remember also that Vonage will only accept MSISDNs specified with the international format. As such, one must include the international calling code prefix for each number.

Is the number active and valid?

If you are unsure if the number is valid, you can verify using our Number Insight API or in your Vonage API account dashboard.

Are you using Delivery Receipts (DLRs) as the unique indicator of delivery success or failure?

Yes: Some countries will not support DLRs, so a pending or missing Delivery Receipt may not necessarily indicate a failed delivery. Examples of countries without support for Delivery Receipts include Latin American countries, the US, and Canada (when sending from a long virtual number). In many of these countries, you will not get a DLR, or you might get one inconsistently. This does not mean that the message did not arrive.

No. The handset owner has directly reported that the message did not arrive:

In this case, other factors might be affecting the delivery of the SMS, including those related to the country’s regulations and restrictions.

Some countries have strict Do Not Call lists in place (such as India) and therefore, only certain types of traffic are allowed, or at certain times of the day (such as France). There are many other variables that may affect your traffic in each country. See our country-specific articles to help you understand what the issue could be.

I’ve checked the local regulations, I’m sending according to the rules, and the number is valid. What now?

If none of the above apply it may be that failed delivery is due to issues such as:

Carrier Spam Filters

Most carriers in developed markets prefer to use regulations to control the flow of spam. In developing markets, however, technology is used to filter out unwanted texts. These filters, however, are not perfect and can lead to filtering legitimate SMS traffic, as well. Some filters even send back a fake handset delivery confirmation. You think your message is delivered, but it is not. Furthermore, filter technology is in constant evolution, and associated algorithms change constantly. Keeping track of which carriers filter and how is a complex task.

Roaming

Unfortunately we cannot ensure delivery to roaming numbers due to the complexity and lack of reliability of Carrier Interconnection Agreements. Basically, this is related to the routing carrier not having Interconnection Agreements with the roaming operator.

Sending the Wrong Content

Not all phones support all languages. For instance, sending a Chinese message to a French phone will get to the handset but will not display to the user. Sending binary messages to an iPhone won’t work, either. Certain carriers also filter some keywords (such as the carrier’s own name) to prevent brand theft and scams.

Handset Cannot Receive SMS

There are any number of reasons that can prevent a phone from receiving an SMS that it would be able to receive under normal conditions, including the phone being out of reach, a full memory, roaming, temporary disconnection, the number not existing anymore, and so on.

Portability Failure

A lot of phones get ported everyday from one network to another. The number will still look like the original network but the real network has changed. To address this, carriers have introduced network look-ups that provide them with the real network before sending the message. This guarantees that the SMS is routed correctly. The process, however, is not perfect. Network look-ups are expensive, and many providers don’t do them everywhere. Some carriers, in fact, still don’t even support these looks-ups at all. Additionally, some portability databases only get updated every 24 hours.

Additional Information

If, after going through these troubleshooting steps, you still do not have a clear reason for why your message was not delivered, submit a support request, and include as many details as possible, such as the message ID or API key, destination number, and timestamp.