Handling SMS delivery receipts

Recently, we looked at how to send SMS messages using a standard HTTP POST-based API. As was intimated at the time, most APIs also allow you to process delivery receipts for the messages you send. This allows you to determine the status of the message, i.e. delivered, failed, expired etc. Let’s take a look at how this all works.

Sending SMS Messages – A Quick Recap

To send an SMS message, you plug into a standard API. You generally use a company known as an aggregator or a specific SMS provider to send messages. Each API is different but follows the same general guidelines, i.e. you specify:

  • Number you are sending the message to
  • Who the message is being sent from
  • The message body
  • Account user name and password for authentication purposes

Once the call is made, the API usually returns one of two things:

  • A confirmation message, which contains a generated message ID (some APIs allow you to generate your own message ID)
  • An error, which occurs when a particular message fails to send for one reason or another

If an error doesn’t occur, the message has been successfully sent. At this point your system should log the message in a database, along with the unique message ID. Here’s a typical response from iTagg, who we used previously to show how to send SMS messages:

error code|error text|submission reference 0|sms submitted|2891717007c4bf0ebf2c81cb4995cd2d-3

So what we have here are three pipe-separated values:

  • Error code – if an error occurred, this would be a non-zero value. As this message shows a successful send, the error code is 0, indicating success.
  • Error text – again, this would be populated with some useful error information if an error occurred. In this instance, the message is sms submitted, indicating all is well.
  • Submission reference – this is the part we’re interested in. The unique ID 2891717007c4bf0ebf2c81cb4995cd2d-3 is the identifier assigned by iTagg to the message. It is this identifier that will be passed as part of a delivery receipt.

Handling Delivery Receipts

Each provider’s API differs, and in the case of delivery receipts they differ greatly. We’ll use iTagg in this example to show how to process a delivery receipt, but let’s have a look at the values a couple of providers offer.


2ergo offer one of the better delivery receipt API mechanisms. It is quite thorough and offers the following values:

  • Delivered
  • Rejected
  • Expired
  • Undeliverable
  • Abandoned


iTagg can theoretically send multiple delivery receipts per message, e.g. “Acknowledged” when the message is sent to the network, and then “Delivered” once the message is delivered to the target mobile phone. Values they pass are:

  • Buffered
  • Acknowledged
  • Delivered
  • Failed
  • Unknown


Tanla’s mechanism is extremely simple; the message delivery was either successful or it failed.

  • Delivered
  • Failed

As we used iTagg’s API to send messages in the previous article, we’ll build our example delivery mechanism using iTagg too.

Keeping a Record

If you need it, refer back to the SMS Sending article for information on sending a message. Here’s the original code we wrote to send messages via iTagg:

To be able to process delivery receipts, we must store the message details in a database. Here’s a quick SQL Server database script to store basic message details:

Note we have implemented a workaround in the usp_MarkMessageAsDelivered stored procedure, to work around an iTagg quirk (all aggregators have them!).

To speed things up, use the ASP.NET project you created for the sending SMS article, and open up the code for the default page.
We’ll now update the code in the default page, to ensure the message is stored in the database after it is sent:

Try sending a message now. After sending, check out the messages table in the database – you should see the message you’ve just sent in there. That’s the first part dealt with.
The Next Part of the Story.
We now need to build a “listener” Web page to process delivery receipts. This listener Web site should receive an inbound delivery receipt, process it, and update the Messages table’s MessageDelivered Boolean column.
When iTagg pass us a delivery receipt, they pass a HTTP POST request containing one parameter:

  • xml

This contains an XML document, which houses delivery receipt information.

The xml parameter includes the following elements:

  • version – The iTagg version number for their delivery receipts.
  • msisdn – The mobile number the message was sent to.
  • submission_ref – The iTagg message ID. We need this to look up the value in the database.
  • status – This is the field we’re interested in. This may contain one of a variety of values as we saw earlier. We’re interested in values reading Delivered.
  • reason – This is only passed if a premium SMS message is set. We can ignore it here.
  • Timestamp – The date/time the action in this delivery receipt was actioned.
  • Retry – Denotes whether a premium-rate message should be retried or not.

Our listener page needs to split up the delivery receipt, then store it in the database. The code we’ll write to do this will consist of:

  • A small class to represent a delivery receipt
  • Some code in an ASP.NET page to create a delivery receipt object and to update the message in the database

Writing the Delivery Receipt Processor class

As we’ve just seen, iTagg passes an XML parameter containing a delivery receipt. We need to write a small class that parses this delivery receipt, so we can easily access the data. Here’s an example of the XML iTagg will send to us:

To add the class to our Web site:
1. Right-click on the Web site in Solution Explorer and choose Add New Item.

Figure 1: Adding a new item to the Web site

2. In the dialog that appears, choose Class. Call the class iTaggDeliveryReceipt.cs and click Add.

Figure 2: Choosing the class template

You may see this message:

Figure 3: Putting the class in the correct place

Click Yes if you do.
3. The code window for the class will open. Enter the code listing below (replacing what is already there):

This code is quite simple. It takes a string and converts it to an XML document. It then uses some XPATH statements to obtain the values for the class properties.

Now we just need to add a Web page to call the class and act as the listener.

Creating the Listener Web Page

All we need to do here is add a Web page, check if some POST data has been passed, and pass the POST data to the delivery receipt class. Once we have a delivery receipt object, we’ll update the database to mark the message as delivered.
1. In Solution Explorer, right-click on the Web site name again, and choose Add New Item again.
2. Choose Web Form and call it listener.aspx. Click Add.

3. Listener.aspx will open. The first line reads:

Modify the end of the line, so it reads:

If you don’t add the ValidateRequest tag, ASP.NET will think the iTagg XML is suspicious and will raise HTTP 500 errors back to iTagg.
4. Save and close listener.aspx. Find listener.aspx.cs in Solution Explorer and open it up.
5. Add this code, replacing any code already there:

This code uses the iTaggDeliveryReceipt class we created earlier to split up the incoming XML, checks whether the status message received is Delivered, and inserts the message into the database if Delivered was received.

As a last step, add this line to your web.config file, right underneath :
This allows us to view trace information for the Web site – we’ll be able to see what data iTagg sent to us.
We’re now in a position to try out the service.

Putting It All Together

Now we have the code written, we need to make it publicly accessible and tell iTagg where they should be sending delivery receipts to. The full process is:

  • Publish the listener to a publicly available Web address
  • Ask iTagg to send delivery receipts for your account to the publicly available Web address
  • Test the system

Publish the Listener

As we’re using C# and ASP.NET, we’ll use IIS as the Web server – IIS7 to be precise. To publish your site, we need to do two things:

  • Create an application to hold the Web site in IIS7
  • Publish the Web site

Remember this will only work if your server has a public Web or IP address. If you use a hosting service, publish the Web site containing the listener to that hosting service, exactly as you would publish any other Web site.

To create the application, open IIS7 and select Default Web Site (or the Web site you require if you host multiple sites). Right-click and choose Add Application:

Figure 4: Adding an IIS Application

Set the application name as itagglistener, and choose the directory on your server’s hard disk you want to store the Web site in. Make sure you choose an application pool that has access to your database too.

Figure 5: Specifying application details

Click OK to create the application.

You now need to log on to iTagg’s control panel to set up the location where delivery receipts should be published.

Configure the URL at iTagg

Go to www.itagg.com, and click on the Control Panel option.

You may be prompted to log in. Log in to display your control panel. On the left-hand side, find the Delivery Receipts option and click on it.

Figure 7: The iTagg delivery receipts management page

Set the full URL you want delivery receipts to be delivered to in the Delivery Receipts are currently being posted to… box. It’s important this contains the listener.aspx page name at the end, as in the example above. Once you’ve entered the correct URL, click Update to save the address.

You can use the iTagg interface to test if your listener Web page is working. Click the submit button in the Test the Delivery Receipt Mechanism section. You should see a response displayed along the following lines:

Figure 8: Sending a test delivery receipt from iTagg

We now know everything is working, so we can try sending a message.
Testing the System.
To test the system, send a message using our simple SMS sending Web site. Run the Web site and open the default page. Send a message.

Figure 9: Sending an SMS message

After sending the message, check the database – you should see your record has been added to the Messages table. Note that the MessageDelivered column is set to its default value of false.

Figure 10: Message not yet delivered

Wait for a couple of seconds until the message you sent is delivered to your handset. After delivery, check the database. The MessageDelivered column should be set to true, denoting that the message has indeed been delivered.

Figure 11: The message has been delivered

To prove that iTagg contacted us and sent the delivery receipt details, browse to your listener Web site’s ASP.NE T trace page. If your listener Web site is located at:
Then you should go to:
The trace list will be displayed:

Figure 12: The application trace

The number of items you will see in the list will vary, as it depends on how many hits you’ve generated. Look at items 8, 9, and 10 in the image above. Default.aspx was the page hit when the SMS message was sent (item 8). Why do we have two hits for listener.aspx (items 9 and 10)? Surely we only expect one hit, to tell us the message was delivered?
Remember earlier I mentioned that iTagg can send multiple delivery receipts for each message sent? This is what has happened here. Click on the first listener.aspx trace item.

Look at the line beginning with DR status. Note that the status is acked, i.e. the network has acknowledged the message. This may appear in the trace before the message has been delivered to your phone – it’s telling us the network has the message but it hasn’t yet been sent to the handset.

Figure 13: The acknowledgement trace

Click back and view the next listener.aspx hit.

Figure 14: The delivered trace

Note that the DR status now is Delivered. This trace item will only appear after the message arrives to your phone. You can also see a trace item showing us we’ve updated the database.
There you go, a simple delivery receipt processing mechanism. Easy isn’t it!


If things didn’t work as expected, make sure you have IIS set up correctly. Can you browse to the site from your browser? Can you hit the listener.aspx page from iTagg? If the answer to any of these questions is no, check your permissions.
If messages are not appearing in the database, the chances are your Web site is running under an application pool that doesn’t have access to the database. Grant access to the database and you’ll resolve the problem.


We’ve covered a lot of ground in this article. We’ve seen that various APIs can pass delivery receipts to our systems. These are useful as they allow us to accurately report to clients sending lots of SMS messages – the clients can find out how many messages arrived for a particular campaign, for example. This mechanism also helps us build a more accurate messaging system with detailed information held for each message.

To build the listener to support delivery receipts, we had to connect to an aggregator’s API – iTagg’s, in this example. To make everything work we had to have an account with iTagg, and tell iTagg where to send the delivery receipt messages to. We also had to ensure our listener Web site was publicly available.

With all of the various pieces in place, we successfully sent a message to a mobile phone and saw that its delivery status was updated in our messages table after iTagg had notified us that the message had been delivered (and prior to that, acknowledged).

Delivery receipts are an extremely important part of any messaging system infrastructure. They greatly enhance the reporting abilities of your messaging platform and can give you a granular view of message delivery rates. You don’t have to use them but doing so will give your system a competitive advantage – so take advantage. Good luck with your deliveries!

Exclusive tips, how-tos, news and comment

Receive monthly updates on the world of mobile dev.

Other Products

Market leading device intelligence for the web, app and MNO ecosystems
DeviceAtlas - Device Intelligence

Real-time identification of fraudulent and misrepresented traffic
DeviceAssure - Device Verification

A free tool for developers, designers and marketers to test website performance
mobiReady - Evaluate your websites’ mobile readiness

© 2024 DeviceAtlas Limited. All rights reserved.

This is a website of DeviceAtlas Limited, a private company limited by shares, incorporated and registered in the Republic of Ireland with registered number 398040 and registered office at 6th Floor, 2 Grand Canal Square, Dublin 2, Ireland