When an SMS message is passed to the recipient’s mobile network by an SMS Gateway the network will attempt to deliver it to the handset which is assigned to the destination mobile number.
Ordinarily, the message will be delivered immediately and the network will return a delivery status of ‘DELIVERED’. If the message cannot be delivered a few different scenarios can play out.
Temporary Errors
If a ‘temporary’ error is returned by the mobile network in a delivery report, it indicates that there is currently a problem preventing the delivery of the message, such as the handset being out of range. As it implies, this problem may only be temporary. The mobile network will periodically try to re-deliver the message within the designated expiry period.
The SMS Works will update you with any temporary errors that we receive, leaving the message status as ‘SENT’. The delivery report JSON contains a ‘failurereason’ object, with a ‘permanent’ parameter that will be set to false. You can typically ignore these and wait for one of the following outcomes instead…
Permanent Errors
A ‘permanent’ error is returned by the mobile network when a definitive problem occurs that will prevent the message from being delivered, such as the recipient’s mobile service having been suspended by the network. If a permanent error occurs the mobile network will discard the message and they will not try to re-deliver it.
In this case, The SMS Works will send you a delivery report with a status of either ‘UNDELIVERABLE’ or ‘REJECTED’. The delivery report JSON contains a ‘failurereason’ object, with a ‘permanent’ parameter that will be set to true, along with the reason why it won’t be delivered. In some cases you may want to try to resend the message after a delay (for example, if the mobile network indicates that the handset is set to ‘Do not disturb’, which the recipient can alter at a later date). In most cases though it indicates a more long-term problem with the number, so you may want to update your data. We’ve grouped permanent errors into a few, easy to understand categories, to make your next steps easier to determine.
The SMS Works does not charge for messages that are not delivered. Whenever a permanent error occurs we will refund the applicable number of SMS credits to your account.
Message Expired
If a temporary error prevents the immediate delivery of a message then the mobile network will attempt to re-deliver the message up until a designated expiry time. By default, The SMS Works sets the message expiry to 48 hours. When the expiry time elapses, a delivery report with a status of ‘EXPIRED’ will be returned to you. As above, we do not charge for expired messages, and the relevant number of credits will be refunded to your SMS Works account.
Message Delivered
Our desired outcome! If a temporary error is overcome within the expiry period and the message can be delivered you’ll receive a delivery report with a status of ‘DELIVERED’. All is well.
