How to Get an SMS Delivery Receipt in ASP .NET MVC
Published on May 18, 2021

Now that you have successfully sent an SMS and received an SMS using your Vonage number, it’s time to check the status of the message to ensure it was delivered. To do this, we have to fetch the delivery receipt, which will return the delivery status of the message.


  • A Visual Studio project

  • A project set up as described in the previous blog post in this tutorial series which you can find on GitHub.

  • Optional: Vonage CLI

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Receive webhooks on your localhost

The Vonage SMS API uses webhooks to inform the ASP.NET app of the status of the sent text message. As explained in the previous tutorial, we will be using ngrok to expose the port to the internet so Vonage’s servers can connect to it while testing.

Example of Ngrok running"Example of Ngrok running"

Go back to Visual Studio and run your program, then head over to the Vonage Dashboard. On the Settings page, towards the bottom, you will see Callback for Delivery Receipt under the API Settings. Paste the ngrok URL inside the textbox and add /SMS/DLR to the end of it. This will route the message to the Receive action in the SMS controller.

Configuring Nexmo webhooks"Configuring Nexmo webhooks"

Diving into code

In this tutorial series, we started by learning how to send an SMS.

In this first tutorial, we created an ASP.NET MVC project and added a controller called SMSController.cs. Afterwards, we created two action methods. One of which was to present the view for the details of the SMS (destination number and message text) and the other was to retrieve the values from the form and send an SMS.

In the second tutorial, we created another action method to print the details of incoming SMS message to the output window.

In order to read the delivery receipt, we will create an action method called DLR in the SMSController.cs.

Code example receiving DLR"Code example receiving DLR"

As you can see in the code above, you need to add [FromUri] in the parameter to be able to read the delivery receipt. Above this method, add a HTTPGetAttribute to restrict the method to handling GET requests. Print the messageID (message ID), msisdn (Vonage virtual number), to (destination number), and the status (status message) to the output window using ‘Debug.WriteLine’. You can check the list of status codes here.

Now you are ready to go! Send an SMS using your Vonage virtual number and open up the output window in Visual Studio. There you should see the delivery receipt for the text you have sent! You have now successfully setup your virtual number to return a status for a text message via a webhook!

Example output of a DLR"Example output of a DLR"

Rabeb OthmaniVonage Alumni

Rabeb was a Developer Advocate at Nexmo focusing on cloud communication APIs and helping developers get the best experience possible when building their apps. Other than writing code for a living, Rabeb advocates for bringing more women and minorities into tech, thus her involvement with Women Who Code and different tech communities. She leads the Women Who Code Network in Bristol.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls-all at your fingertips.

Subscribe to Our Developer Newsletter

Subscribe to our monthly newsletter to receive our latest updates on tutorials, releases, and events. No spam.