Delivery Receipts

Overview

Flowroute allows you to implement delivery receipts (DLRs), enabling you to track the status of an SMS that you send to your intended receiver. A message doesn’t just move directly from your phone to the intended receiver’s phone. Instead, message transit is typically a multi-step process; that is, the message makes several stops along its path to the receiver. By default, delivery receipts are not automatically implemented on your account. But by implementing this functionality, you can receive a delivery receipt notice for each stop the message makes during transit, tracking its path to its destination.

When an SMS is sent from your phone, the message is first processed by Flowroute and then sent to an External Short Message Entity (ESME), which is used to process SMS messages. From there, the message is typically sent to a carrier. From the carrier, the message again is typically sent to the receiver’s phone. In some cases, the message might transit to another ESME, to multiple carriers, or even to a combination of both.

In a simple scenario, the transit of a sent message might resemble this:

Messages are sent from your Flowroute account using the HTTP POST method. Your message is first processed internally by Flowroute, and then sent to the ESME. A 200 OK message is returned if the message was sent from Flowroute successfully to the ESME. However, in some circumstances, a message can fail to send to the ESME. This can be caused by any of the following HTTP errors:

• 429 Too Many Requests. This occurs when Flowroute believes you are sending too many messages at once and interprets the current message as spam. Your messaging has been throttled back because of the high number of messages sent per second. To learn more about message rate limits, see Flowroute Messaging Rate Limits.
• 503 Service Unavailable. A server error indicating that the ESME is unavailable at the moment. You will need to resend the message later. No MDR ID is created.

When sending from Flowroute, your message isn’t checked for whether or not you’re using a valid recipient phone number, or whether or not your Flowroute number is valid. This validation is performed once the message reaches the ESME. After reaching the ESME, the message is next sent out onto the carrier’s network. When this event occurs, a Level 1 DLR is sent back to you indicating success. As the message travels along the network, Level 2 DLRs are then sent. In some cases, a message might fail to send along any point of its transit. In those cases, a delivery receipt notice of the error is sent to you. More details on each type of DLR and possible errors are described below:

Level 1 DLR

The ESME processes a message, sending it out to the carrier’s network. Once the message is initially received by the carrier's network, a Level 1 DLR is returned and is sent to you. If an error is encountered, an error message is returned. See Level 1 DLR Examples for the differences between the Level 1 delivery receipt object in Messaging v2.1 and Messaging v2.

Once the message is on the carrier’s network, Level 2 DLRs are sent.

Level 2 DLR

Your message is now traveling along the carrier’s network. As mentioned before, a simple scenario is that a message moves from the ESME to the carrier’s network, eventually reaching the receiver’s phone, as shown below:

However, sometimes a message might not follow the simple path. A carrier’s setup might require additional stops along the way. For example, these stops might be from the initial ESME to one or more other ESMEs, from one carrier to another, or a combination of both. Regardless of how many entities your message hits along the way, a Level 2 DLR can be returned for each stop. Because of the way messages travel along a network, in some cases you might even receive a Level 2 DLR before you receive a Level 1 DLR. If an error is encountered, an error message is returned. See Level 2 DLR Examples for the differences between the Level 2 delivery receipt object in Messaging v2.1 and Messaging v2.

A Level 1 DLR will always be provided if the message clears Flowroute's servers. The response for the hop between ESME and the receiver's handset varies by carrier which may offer up to two Level 2 DLRs.

It is important to note that Level 2 DLRs are not guaranteed as carriers are not required to provide a Level 2 DLR or a final `delivered` receipt. Rather than a `delivered` receipt, a carrier may return an `accepted` or `queued by carrier` status in lieu of a final delivered acknowledgement - in tests these statuses have been virtually synonymous with `delivered`. The only exception to this standard is Toll-Free SMS which does guarantee a delivery status, and is one of the value-adds of Toll-Free vs Longcode SMS.

Integrating DLRs with your Flowroute Account

If you're an existing customer using v2 of our Messaging API, you will need to file a support request to integrate delivery receipt notifications into your account. Consider upgrading to v2.1 which embeds delivery receipt information in our SMS Message Detail Records (MDRs).

Example Delivery Receipt Messages

The following sections describe the information contained within Level 1 and Level 2 SMS delivery receipts according to your Flowroute API version.

Message Delivery Status

The following table displays all the possible message delivery status values and their corresponding DLR level:

Level 1 DLR Examples

The following example shows a Level 1 DLR with all fields included; however, regardless of which information is stripped out, the status field will always be returned. If you receive a Level 1 DLR that has all but the status stripped out, the DLR is correct and you did not receive an incomplete message.

Level 1 DLR Example for Messaging v2.1

{
   "data": {
       "attributes": {
           "body": "hey",
           "level": 1,
           "status": "smsc submit",
           "status_code": null,
           "status_code_description": null,
           "timestamp": "2018-01-29T21:36:51+00:00"
       },
       "id": "mdr2-8474b7ec053c11e8912f3a9ee87a8226",
       "links": {
           "related": "https://api.flowroute.com/v2.1/messages/mdr2-8474b7ec053c11e8912f3a9ee87a8226"
       },
       "type": "delivery_receipt"
   }
}

                    

Delivery Receipt Object for Messaging v2.1 (Level 1 or Level 2)

Level 1 DLR Example for Messaging v2

{ "attributes": {
    "status": "sent",
    "body": "",
    "from": "12061231234",
    "to": "17165551234"
  },
 "type": "delivery_receipt",
 "id": "mdr1-a78fb04f89724244bdeebc0581ef6d2f"
}

                    

A Level 1 delivery receipt object for Messaging v2 is composed of the following:

Level 2 DLR Examples

Level 2 DLR Example for Messaging v2.1

{
   "data": {
       "attributes": {
           "body": "hey",
           "level": 2,
           "status": "delivery success",
           "status_code": 1004,
           "status_code_description": "Message delivered to handset",
           "timestamp": "2018-01-29T21:36:54+00:00"
       },
       "id": "mdr2-8474b7ec053c11e8912f3a9ee87a8226",
       "links": {
           "related": "https://api.flowroute.com/v2.1/messages/mdr2-8474b7ec053c11e8912f3a9ee87a8226"
       },
       "type": "delivery_receipt"
   }
}

               

For an explanation on the Level 2 delivery receipt object for Messaging v2.1, see Delivery Receipt Object for Messaging v2.1.

Level 2 DLR Examples for Messaging v2: Delivered and Undelivered

Level 2 DLR Example: Delivered

The following shows an example of a successful Level 2 DLR response for Messaging v2:

{ 
    "attributes": 
    {
        "status": "delivered",
        "status_code": "1003",
        "from": "18551231234",
        "body": "hello there",
        "to": "1914441234"
    },
    "type": "delivery_receipt",
    "id": "mdr1-14bdef7399f14a42a4f4715182451fe7"
}

               

Level 2 DLR Example: Undelivered

The following shows an example of an undelivered message Level 2 DLR for Messaging v2:

{   
    "attributes": 
    {
        "status": "undelivered", 
        "status_code": "1103", 
        "from": "18441231234", 
        "body": "hello there" 
        "to": "12065553333"
    }, 
    "type": "delivery_receipt", 
    "id": "mdr1-81f8242e04124a2e9e172351f8bd490a"
}

                

A Level 2 delivery receipt object for Messaging v2 is composed of the following: