Why did my SMS messages fail to be delivered?

Learn what the different message status ...

Learn what the different message status mean as well as the most common reasons for a failed delivery. By following best practice, you can avoid that your SMS messages are blocked by carriers.

Please note that it is currently not possible to send SMS traffic to Russia.


What does the delivery status of my SMS messages mean?

List of the delivery status that you may...

List of the delivery status that you may encounter when you send SMS traffic via GatewayAPI.



Initial value for before processing begins, waiting for actual status.



Used for messages where you set a sendtime in the future.



The message is held in our internal queue and awaits delivery to the mobile network.



Message has been sent to mobile network, and is on its way to its final destination.



The end users mobile device has confirmed the delivery, and if message is charged the charge was successful.



Message has exceeded its validity period without getting a delivery confirmation. No further delivery attempts.



Message was cancelled.



Message is permanently undeliverable. Most likely an invalid MSISDN.



The mobile network has accepted the message on the end users behalf.



The mobile network has rejected the message. If this message was charged, the charge has failed.



The message was accepted, but was deliberately ignored due to network-specific rules.

Why do my SMS messages fail to be delivered?

Invalid number One of the most common re...

Invalid number

One of the most common reasons for a failed delivery is an invalid number.
A number can be invalid if:

  • The number lacks a country code. GatewayAPI sends text messages to 200+ countries
    and it is therefore necessary to add a country code to make sure that the messages find the right end users.

  • The number is a landline.

  • The end user has changed number and the old number is disconnected.

  • The end user has filled in a wrong phone number
    (this happens more often than you would think).

Carrier filters Another common reason fo...

Carrier filters

Another common reason for text messages not being delivered is carrier filters.

The specifics vary at implementation, but in general they react to different patterns in the messages. The firewalls and filters have their limitations though. The spammers are continuously changing their approaches and in the pursuit to catch all spam traffic, the carriers sometimes block legitimate traffic as well.

The carrier filters can react, e.g. if many similar text messages are sent to the same number. This is a common occurrence when testing the setup. If text messages are sent on certain days or hours, they can be blocked as well. In France, for example, it is prohibited to send SMS messages for marketing purposes in the evening and during national holidays.

The content of the SMS messages can also cause messages to be blocked. This can happen if the SMS:

  • Lacks clear opt-out instructions.

  • Contains imprecise language with wrong capitalisation and punctuation.

  • Contains certain keywords which may be related to spam, sexual, religious or political content.

  • Includes links in the text. This is not allowed in some countries.

End users The end user’s mobile ph...

End users

The end user’s mobile phone can also be the culprit. It happens relatively often that the memory of the end user’s mobile phone is full, which means the phone cannot receive the SMS. Your end users could also have firewalls installed on their mobile phones, which can block the SMS. Furthermore, if the end user is traveling in another country, it could lead to the SMS not being delivered, since devices that are roaming are traditionally harder to reach.

Lastly, the end user’s phone can simply be turned off. Carriers will hold text messages for 24-72 hours and if the receiving mobile phone is not turned on within that time frame, the message will expire.

Sender ID The Sender ID is the ‘from’ fi...

Sender ID

The Sender ID is the ‘from’ field that is shown when a message is received. In some countries, such as the US, you can only use numerical characters as the Sender ID whereas in many other countries, it is allowed to use a Sender ID with alphanumeric characters.

Text messages with alphanumeric Sender IDs can be labeled as spam by many carriers though, so we recommend using it with caution and reading up on the restrictions in the country.

Scammers are using social engineering to mask their real identity and to pretend being a trustworthy institution, company or the like, and they do that e.g. by using well known Sender IDs.

Blocked by country-specific restrictions...

Blocked by country-specific restrictions

When you send SMS traffic to certain countries, such as China and the US, there can be certain country-specific restrictions. It is your responsibility to make sure they are being followed. For that reason we have made a Country Restriction section where you can find information about each country, so you can avoid that the SMS messages fail to be delivered.

Go to country-specific restrictions


Can I get a notification when your service is down?

Yes, simply sign up to receive notificat...

Yes, simply sign up to receive notifications regarding maintenance and any incidents that might occur on our status page.

GatewayAPI Status

on this page