Flowroute allows you to implement delivery receipts (DLRs), enabling you to track the status of an SMS 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.

Note:

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

When a message is sent from your phone, the message is first processed by Flowroute and then sent to an ESME, (External Short Message Entity), which is used to process SMS messages. From there, the message is typically then 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.

Note:

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 because of one of the reasons described below.

  • 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 sent messages. No MDR ID is created.
  • 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 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, an error DLR is returned 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 Example for an example message.

Level 1 DLR

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

Level 2 DLR

Your message is now travelling 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 of those. 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 examples of delivered and undelivered messages.

NOTE:

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

DLRs are not automatically integrated with your Flowroute account. If you'd like DLRs integrated with your account, you'll need to file a Support request here. Flowroute's Support team will then work to get your account integrated with delivery receipt functionality.

Example Delivery Receipt Messages

The following sections describe the information contained within Level 1 and Level 2 delivery receipts.

IMPORTANT!

There are times when DLR processing might strip out some of the fields in the DLR. 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
{ "attributes": {
    "status": "sent",
    "body": "",
    "from": "12061231234",
    "to": "17165551234"
  },
 "type": "delivery_receipt",
 "id": "mdr1-a78fb04f89724244bdeebc0581ef6d2f"
}

                

The response message is composed of the following:

Parameter Description
attributes Complex type composed of the following:
  • status - Indicates the message was sent successfully from the ESME, or failed was unsent.
  • body - The actual content of the message.
  • 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. This is generated by Flowroute when a 200 OK is returned from the ESME.
Level 2 DLR Examples: Delivered and Undelivered

The following section provides examples of both delivered and undelivered DLR messages.

Level 2 DLR Example: Delivered

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

{  "attributes": {
    "status": "delivered",
    "status_code": "1003",
    "from": "18551231234",
    "body": "<message contents>",
    "to": "1914441234"
  },
  "type": "delivery_receipt",
  "id": "mdr1-14bdef7399f14a42a4f4715182451fe7"
}

               

The response message is composed of the following:

Parameter Description
attributes Complex object composed of the following:
  • status - Indicates the message was delivered successfully, regardless of the entity type—ESME, Carrier, or handset. All successful deliveries in a Level 2 DLR will return delivered.
  • status_code - For any delivered message, 1003 is returned, indicating that the message was accepted by the next stop in its transit. More information on response codes and associated messages can be found here: 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 actual content of the message.
  • 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 generated when the message was received by the first ESME and a Level 1 DLR was created.
Level 2 DLR Example: Undelivered

The following shows an example of a DLR for an undelivered message:

{   "attributes": 
      {"status": "undelivered", 
       "status_code": "1103", 
        "from": "18441231234", 
        "body": "<message contents> 
        "to": "12065553333"
    }, 
    "type": "delivery_receipt", 
    "id": "mdr1-81f8242e04124a2e9e172351f8bd490a"
}

                
Parameter Description
attributes Complex object composed of the following:
  • status - Indicates the message was undelivered, regardless of the entity type—ESME, Carrier, or handset. All unsuccessfully deliveries in a Level 2 DLR will return undelivered.
  • status_code - The delivery receipt response code indicating the reason for the undelivered message. More information on response codes and associated messages can be found here: 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 actual content of the message.
  • 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 generated when the message was received by the first ESME and a Level 1 DLR created.