// Skip to main content

SMS Delivery Reports (DLR Reports)

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 SMS delivery reports can be found in our developer zone.


What are SMS Delivery (DLR) Reports?

For every text message that is sent through the SMS API, a delivery report is generated that provides detailed information on the delivery status of the SMS.

There are a wide variety of outcomes that allow you get very granular information about whether or not a message was delivered or not and in the case of non-delivery, why that might be the case.

For example the outcome 'expired' means the number is correct but the phone is either switched off or out range. The 'rejected' delivery report outcome means the network rejected the text because the number does not exist.

So there's plenty of detail that allows you to really understand and improve your mobile number data quality.

Are SMS delivery report always available?

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.

Read about 13 main reasons why an SMS might not be delivered.

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.

Please note that due to very large file sizes, delivery reports are available for 3 months, after which they are permanently deleted.

If you need access to historical delivery data, please ensure you download reports before they expire.


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.

Undeliverable

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.
More detailed reasons for SMS failure are provide in this article linked article.

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.


What can SMS delivery reports be used for?

The main function of SMS delivery reports is to provide detailed information on the delivery status of every message sent.

This information can be useful for a number of purposes.

Data cleansing / updating
Where a message is undelivered, contact the intended recipient via another channel such as email to obtain the correct mobile number.

Improve response rates
By improving mobile data quality, response rates to SMS marketing campaigns can be increased to improve the ROI.

Audit trail
Delivery reports provide definitive evidence that a message has been delivered to a phone if ever evidence of this is needed.

Systems monitoring
DLR reports allow you to check that all your sms systems are working as expected.

How long will it take for credits for failed messages to be allocated back to my SMS API 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.


SMS 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 SMS Delivery Reports

Some international mobile networks do not offer SMS DLR reports to anything like the detail or reliability of UK networks.

We always provide as much information as we possibly can but sometimes the data simply isn't passed on. When this happens it's very rare that we are able to provide more information than was included in the initial delivery report.

Further enquires to the relevant network are normally ignored! It's frustrating but it's part of the nature of SMS.

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