Skip to main content

SMS Delivery Reports Overview

Smart phone

Customers of The SMS Works only pay for SMS messages that are delivered.
Failed messages are refunded back to customers’ accounts. 

All technical documents relating to delivery reports can be found in our developer zone.


Before we start...

Before diving into some of the detail, just a couple of quick but important points regarding delivery reports.

Please be aware that the sms delivery report service offered by the networks comes with no guarantees, service level agreements or contracts.

If a network has a problem and is unable to provide delivery reports, then unfortunately there is no comeback or way of retrieving them. Very occasionally, the network will simply provide no delivery report data at all.

When a delivery report is not provided, we have to assume that the message was delivered and the credit for that message will be used and not refunded.


Delivery Report Message Statuses

Delivered

Mobile number is correct; message has been successfully delivered to the handset.

Accepted

The SMS Works platform has accepted the message but no delivery report has yet been received from the networks.

Failed

The message could not be sent. The reason will be recorded on the delivery report. The FAILED status is only used for batch messages, where we need to record sending failures. For non-batch messages, any failure will be recorded in the API responses to your calls.

Undelivered

The message could not be delivered. (See below for possible reasons why a message might be undelivered. The text credit is added back to your account.

Expired

The message was not delivered within the validity period of the relevant mobile phone network.

Networks will try to deliver a message for up to 72 hours, then the message will expire. Different networks have different validity periods.

The credit for the message will be refunded.

Rejected

The message was rejected by The SMS Works Platform. See delivery report documentation for more precise definitions.

No credit will be deducted.


What are the main reasons for an ‘undelivered’ outcome?

There are several reasons why an SMS might fail to be delivered.

Incorrect or inactive number

The mobile number is wrong, inactive or no longer in use.

Wrongly formatted number or message

The mobile number has been incorrectly formatted or is incomplete. UK Mobile numbers can either start 07 or 447 (44 being the international dialling code for the UK).

The number contains too few or too many numbers.

The message contains unsupported characters.

No mobile phone signal

The mobile phone was out of range for 2 or 3 days and the message expired.

The mobile was switched off 

The phone was switched off and remained switched off until the message expired (after 2 or 3 days)

International roaming disabled

If international roaming is switched off, then some handsets may not receive texts.

‘Hanging text’

Occasionally a message can hang on the network despite the receiving handset having a strong signal. Switching the phone off and on again often resolves this issue. This is becoming increasingly rare but still happens occasionally.


How long will it take for credits for failed messages to be allocated back to my account?

The moment that you send out your texts, the relevant number of text credits are deducted from your account. Note that sending messages outside the UK uses 2 text credits.

Non-delivered messages are allocated back in real time as soon as delivery reports have been received and processed.

Any numbers that are not recognised by the Networks tend to generate failed reports fairly quickly, often within half an hour of the message being sent.

Messages that fail for any other reason, can take much longer, in some cases up to a few days. This is because the network will keep trying to deliver a message for up to 72 hours before it finally stops attempting delivery.

Please note that different network have different message expiry timing.


Delivery Report Errors

We've simplified error reporting grouping them in to simple codes that you can build logic or reporting around, to help you quickly identify why messages have not been delivered.

If an error is recorded as being 'permanent' then the message will not be delivered. If it is not permanent the message may still be delivered within the expiry period described above.

This information will be forwarded to your delivery report URL, and will be available in report exports and from our /messages and /messages/{:messageid} API end-points.

Delivery Report Error Codes

Error Code

Permanent

Description

1

true

Handset Error: Number does not exist or has not been assigned to a user.
4

true

Message has been sent to the operator, whereas the request was rejected, or a delivery report with status REJECTED was reverted.
6

false

Handset Error: No response. Handset may be switched off or in a low signal area.
8

false

Handset Error: Roaming not allowed.
9

true

Message has been sent to the operator, but has failed to deliver, since a delivery report with status UNDELIVERED was reverted from the operator.
10

true

Message has been rejected due to the user being subscribed to DND (Do Not Disturb) services, disabling any service traffic to their number.
15

true

The message was received and sent to the operator. However, it has been pending until the validity period has expired, or the operator returned EXPIRED status in the meantime.
20

true

Message has been rejected due to an anti-flooding mechanism. By default, a single number can only receive 20 varied messages and 6 identical messages per hour.

International Messages

Please note that we are unable to refund failed messages to non-UK numbers.