SMS delivery status codes

Eagle.io delivers SMS notifications to phones via an outbound SMS gateway provider. This is a service which receives a request from eagle.io to send a message to a specific phone number, and then sends that message on to the appropriate carrier service, who will ultimately attempt to deliver the message to the phone of the user.

Many different carriers (or mobile network operators) exist globally, and the choice of which carrier to use for a specific phone number is generally determined by the which company the user receives their mobile/cell service from. Examples of carriers are Verizon or AT&T in the United States, Vodafone or O2 in the United Kingdom, and Telstra or Optus in Australia.

Whenever eagle.io sends an SMS, this will be shown in the debug events view. In the following example, 4 users have been sent the same message via SMS, but each message has a different delivery status:

The delivery status that appears after SMS in the debug events view (e.g. SMS [SENT] or  SMS [UNDELIVERED]) is reported by the outbound SMS gateway provider, which in turn can be based on what is reported to the gateway by the specific carrier. The status can be dynamically updated as the message progresses to it's final state.

A status of SENT means the message has been accepted by the outbound SMS gateway provider, and that may change to DELIVERED when the gateway has received confirmation of message delivery from the carrier. But it's possible that the message gets delivered without the gateway receiving any updated delivery information from the carrier. In that case, the status would stay as SENT but you don't know if the message was actually delivered or not. A status of DELIVERED or UNDELIVERED means a definitive answer has been received from the carrier. The UNDELIVERED status can occur for a number of reasons including carrier content filtering or availability of the destination handset, however the exact reason is not provided. The FAILED status means the message could not be sent to the carrier; this can happen for various reasons including queue overflows and account suspensions, but again the exact reason is not provided.

If one specific user is consistently getting a status of UNDELIVERED or FAILED for their messages, the first thing to check is that their phone number is accurate in their user profile. If they receive some messages but not others, then it could be an intermittent carrier or handset fault, or a carrier policy such as detecting some messages as spam or applying some other type of content filter. If a number of users who share the same carrier all experience the same failure, then a carrier content filter could be the cause.