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.

Mobile Support

Delivery receipts are only supported on mobile phones. They are not supported on handsets or landlines.

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.

Message Transit Path

The transit path a message takes once it leaves the ESME is dependent on the carrier. Flowroute has no control over a message’s path once it leaves the ESME.

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

Simple scenario

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.

Level 1 DLR

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:

Level 2 DLR: Basic Transit

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.

Delivery Receipt Response Codes

For a list of delivery receipt response codes and associated messages, see Delivery Receipt Response Codes.

Level 2 DLR: Multi-stop Transit

You should note that carriers are not required to provide DLRs. While a Level 1 DLR is always provided from the ESME to your handset, once it leaves the first ESME and makes its way to the receiver’s handset, it’s up to the carrier itself to provide a Level 2 DLR. It’s at the carrier’s discretion whether or not to provide one. In addition, a Level 2 DLR does not differentiate between when a message reaches another ESME or carrier, or when it reaches the receiver.

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.

Delivery Receipt Object and Processing

There are times when DLR processing might strip out some of the fields in the DLR.

Message Delivery Status

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

Status Level
Messaging v2.1 Messaging v2 Messaging v2 and v2.1
delivery success delivered 2
delivery failure undelivered 2
message buffered delivered 2
smsc submit sent 1
smsc reject undelivered 2
smsc intermediate notifications sent 1

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)

Parameter Description
data Delivery receipt object composed of attributes, id, links, and type.
attributes Object containing the different attributes of a delivery receipt:
  • body - The content of your outbound SMS.
  • level - This will always be 1 for a Level 1 DLR or External Short Messaging Entity (ESME) to carrier delivery and 2 for a Level 2 or a final DLR.
  • status - Status of the message. See specifics about Messaging v2.1 in Message Delivery Status.
  • status_code - The delivery receipt response code, if there is one. Otherwise, this will be set to null.
  • status_code_description - Corresponding explanation for the status_code.
  • timestamp - Date and time, to the second, on which the message was sent. This field displays date and time in UTC following the complete date plus hours, minutes and seconds ISO 8601 format.
id The message detail record (MDR) identifier with an mdr2 prefix. This is generated by Flowroute when a 200 OK is returned from the ESME.
links Links object pointing to the related outbound SMS Message Detail Record (MDR).
  • related - URL of the message detail record for the sent SMS.
type This will always be delivery_receipt.

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:

Parameter Description
attributes Object containing the different attributes of a delivery receipt:
  • status - Status of the message. See specifics about Messaging v2 (Level 1) in Message Delivery Status.
  • body - The content of your outbound SMS.
  • from - Your Flowroute phone number, in E.164 format; e.g., 12061234567.
  • to - The recipient’s phone number, in E.164 format; e.g., 12061234567.
type This will always be delivery_receipt.
id The message detail record (MDR) identifier with an mdr1 prefix. This is generated by Flowroute when a 200 OK is returned from the ESME.

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:

Parameter Description
attributes Complex object composed of the following:
  • status - Status of the message. See specifics about Messaging v2 (Level 2) in Message Delivery Status.
  • status_code - For any delivered message, 1003 is returned, indicating that the message was accepted by the next stop in its transit. For undelivered messages, the status code can be in any of the error codes explained in Delivery Receipt Response Codes.
  • from - Your Flowroute phone number, in E.164 format. For example, a valid E.164 format for a US number would be 11 digits long: 12061234567.
  • body - The content of your outbound SMS.
  • to - The recipient’s phone number, in E.164 format. For example, a valid E.164 format for a US number would be 11 digits long: 12061234567.
type This will always be delivery_receipt.
id The message detail record (MDR) identifier with an mdr1 prefix generated when the message was received by the first ESME and a Level 1 DLR was created.