Skip to navigation

Delivery receipts

When you make a successful request to the SMS API, it returns an array of message objects, one for each message. Ideally these will have a status of 0, indicating success. But this does not mean that your message has reached your recipients. It only means that your message has been successfully queued for sending.

Vonage's adaptive routing then identifies the best carrier for your message. When the selected carrier has delivered the message, it returns a delivery receipt (DLR).

To receive DLRs in your application, you must provide a webhook for Vonage to send them to. Alternatively, you could use the Reports API to periodically download your records, including per-message delivery status.

Note: In most situations, a DLR is a reliable indicator that a message was delivered. However, it is not an absolute guarantee. See how delivery receipts work.

How delivery receipts work

sequenceDiagram participant Your Application participant Vonage participant Carrier participant Handset Your Application->>Vonage: Send an SMS Vonage->>Carrier: SMS Carrier->>Handset: SMS Handset->>Carrier: Delivery Receipt Carrier->>Vonage: Delivery Receipt Vonage->>Your Application: Delivery Receipt Webhook

Delivery receipts are either:

  • Carrier - returned when the service provider receives the message
  • Handset - returned when the user's handset receives the message

Not all DLRs guarantee that the target received your message. Some delivery receipts represent successful completion of only one stage in the delivery process, such as passing the message to another operator. Other delivery receipts are fakes. Because of this, Vonage cannot completely guarantee that a DLR is accurate. It depends on the countries you are sending messages to and the providers involved.

If your message is longer than can be sent in a single SMS, the messages are concatenated. You should receive a carrier DLR for each part of the concatenated SMS. Handset DLRs for a concatenated message are delayed. This is because the target handset has to process each part of the concatenated message before it can acknowledge receipt of the full message.

Understanding the delivery receipt

This is a typical DLR:

{
  "err-code": "0",
  "message-timestamp": "2018-10-25 12:10:29",
  "messageId": "0B00000127FDBC63",
  "msisdn": "447547232824",
  "network-code": "23410",
  "price": "0.03330000",
  "scts": "1810251310",
  "status": "delivered",
  "to": "Vonage"
}

The most important fields are status and err-code as these tell you whether your message was delivered and, if not, what went wrong.

DLR status messages

The status field in the DLR tells you if your SMS was delivered successfully. Possible values are:

status Description
accepted Message has been accepted for delivery, but has not yet been delivered
delivered Message has been delivered
buffered Message has been buffered for later delivery
expired Message was held at downstream carrier's retry scheme and could not be delivered within the expiry time
failed Message not delivered
rejected Downstream carrier refuses to deliver message
unknown No useful information available

DLR error codes

The err-code field in the DLR provides more detailed information and can help troubleshoot a failed delivery. A non-zero code indicates that the message could not be delivered.

err-code Meaning Description
0 Delivered Message was delivered successfully
1 Unknown Message was not delivered, and no reason could be determined
2 Absent Subscriber - Temporary Message was not delivered because handset was temporarily unavailable - retry
3 Absent Subscriber - Permanent The number is no longer active and should be removed from your database
4 Call Barred by User This is a permanent error:the number should be removed from your database and the user must contact their network operator to remove the bar
5 Portability Error There is an issue relating to portability of the number and you should contact the network operator to resolve it
6 Anti-Spam Rejection The message has been blocked by a carrier's anti-spam filter
7 Handset Busy The handset was not available at the time the message was sent - retry
8 Network Error The message failed due to a network error - retry
9 Illegal Number The user has specifically requested not to receive messages from a specific service
10 Illegal Message There is an error in a message parameter, e.g. wrong encoding flag
11 Unroutable Vonage cannot find a suitable route to deliver the message - contact support@nexmo.com
12 Destination Unreachable A route to the number cannot be found - confirm the recipient's number
13 Subscriber Age Restriction The target cannot receive your message due to their age
14 Number Blocked by Carrier The recipient should ask their carrier to enable SMS on their plan
15 Prepaid Insufficient Funds The recipient is on a prepaid plan and does not have enough credit to receive your message
50 Entity Filter The message failed due to entity-id being incorrect or not provided. More information on country specific regulations
51 Header Filter The message failed because the header ID (from phone number) was incorrect or missing. More information on country specific regulations
52 Content Filter The message failed due to content-id being incorrect or not provided. More information on country specific regulations
53 Consent Filter The message failed due to consent not being authorized. More information on country specific regulations
54 Regulation Error Unexpected regulation error - contact support@nexmo.com
99 General Error Typically refers to an error in the route - contact support@nexmo.com

The other fields in the DLR are explained in the API Reference.

Using the SMS API in campaigns

Before you start your messaging campaign, check the country specific features guide for the countries you are sending to. If the country you are sending to does not supply reliable DLRs, use the Conversion API to provide Vonage with more data points and ensure the best routing.

Optionally, you can identify specific customers or campaigns by including a reference with each message you send. These are included in the delivery receipt. Pass your chosen reference into the request by specifying a client-ref parameter of up to 40 characters.

Other resources

Improve this page