nexmo sms delivery receipt

How to Receive an SMS Delivery Receipt from a Mobile Carrier with Node.js

Published November 23, 2016 by Tomomi Imura

This is the third article of a series of Getting Started with Nexmo guide with Node.js.

In the previous articles, you have learned how to send SMS messages, also how to consume a webhook for incoming SMS with Node.js. In this article, you will learn how to find out if the SMS messages sent from your virtual number has been delivered.

GitHub icon View the source code on GitHub

How Do You Know When Your SMS Message is Delivered?

When you send a message to a mobile phone number using Nexmo API from your virtual number (See the Sending SMS with Node.js tutorial), the HTTP response from the API can tell you that the message has been successfully sent from your app. However, it doesn’t tell you if the message is actually delivered to the recipient or not. So what you need to do to find out the status is that to register a webhook callback that is made when the status of the delivery changes.

If you have set a webhook endpoint, Nexmo forwards this delivery receipt to it when the recipient’s mobile phone carrier returns a Delivery Receipt (DLR) to Nexmo to explain the delivery status of your message.

How Delivery Receipt (DLR) works - Nexmo

Setting the Endpoint with Nexmo

When you are developing, I recommend you should use a service like ngrok, which is briefly explained in my last tutorial. I am tunneling localhost:5000 on this example.

Once you set up with ngrok and get a forwarding URL, sign in to your Nexmo account, and go to Settings. Scroll all way down to “API Settings” and fill out the Callback URL for Delivery Receipt with the ngrok URL with a route, let’s call it receipt, and save.

Nexmo Setting for ngrok Webhook endpoints

Now, every time you send a message from your virtual number, the delivery receipt webhook call will be made that URL. Now, let’s write some code with Node.js and Express!

Handling a WebHook with Express

The code is almost same as the example in the last article, except the HTTP route. For DLR, use /receipt or whatever the callback URL that you have specified in the last step at the Settings.

Then define the handleParams function as following:

When you receive the DLR, you must send a 200 OK response. If you don’t, Nexmo resends the delivery receipt for the next 72 hours.

Let’s run the Node code, and try sending some messages from your virtual number to a real phone number!

If your message has been successfully sent to your mobile phone, you should get a receipt with the info including status, message ID, network code, timestamp, etc.

You can find out more about the info on the API Reference page.

Note: Some US carriers do not support the feature. Also, if you are sending SMS to a Google Voice number, you will not get any receipt. We do not provide reach to other virtual number providers due to fraud prevention purposes. If you have any particular business case where you would like to be able to reach virtual numbers, please contact our Support team!


Nexmo Logo

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at