Receive Delivery Receipts

Delivery receipts provide feedback on the delivery of SMS messages, such as whether the message reached the handset.

• If you send an MT using JSON, you will receive a JSON delivery receipt.
• If you send an MT using XML, you will receive an XML delivery receipt.

OpenMarket forwards delivery receipts to a URL that you can either have provisioned for your account, or provide in the delivery element of the request. If our first attempt to forward a receipt is not successful, we will retry the delivery receipt for up to 24 hours.

To receive a delivery receipt, you must include the delivery element in the MT message request. See the Send an SMS operation for details.

Quick facts

Delivery receipts for a multipart message

If your message is sent in multiple parts, then you will receive a delivery receipts for each part. The request body will include segmentNumber and totalSegments, which identify each part and the total number of parts required for the whole message.

Note: When you submit an SMS message request, our synchronous reply will tell you whether the request was accepted, but does not identify if your message needs multiple parts. This is because we need to check the message's character use against the mobile operator's constraints before we can process the message.

See also Single and Multipart Messages.

Request from OpenMarket

Header fields

The request header from OpenMarket will look similar to the following:

POST / HTTP/1.1
User-Agent: OpenMarket
X-API-Version: 4 
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8
Content-Length: 424
Connection: close

Custom fields

Request body

The following examples contain all possible JSON objects and members. However, please note that some of these are not included in a request unless necessary.

{
   "deliveryReceipt" : {
      "mtStatus" : {
         "ticketId" : "01111-12013-1604Y-18MRN",
         "deliveryDate" : "2015-09-22T04:10:33Z",
         "code" : "0",
         "description" : "Message successfully sent to mobile operator",
         "mobileOperatorId" : 383,
         "note1" : "My Internal ID or text 1",
         "note2" : "My Internal ID or text 2",
         "segmentNumber" : 1,
         "totalSegments" : 2,
         "destination": {
            "address": "12515550123",
            "mobileOperatorId" : 383,
            "alpha2Code" : "US"
         },
         "source": {
            "ton" : 3,
            "address" : "222111"
         } 
      },
      "type" : "final"
   }
}

JSON properties

The JSON body has a top-level object that contains the one member, deliveryReceipt.

Multiples of the same object will not occur.

mtStatus object

Object that contains the message delivery status.

Note that this has many of the same name-value pairs as the mtStatus that is returned in the Get Message Status operation.

YYYY-MM-DDTHH:MM:SSZ

2015-09-22T04:10:33Z

type

source object

Object that contains details about the message sender (your details).

This object is not always included in the response.

destination object

Object that contains details about the message recipient (the end user's details).

The destination object is always present

Delivery Receipt codes

For the list of delivery receipt codes, see Delivery Receipt Codes and Troubleshooting.

Responding to the request

When you receive an OpenMarket MO message request, return an HTTP 200 response with an empty response body. OpenMarket will retry the request if it does not receive a response from your platform, or receives a non-200 response. You will need to make sure that you filter duplicate requests.

If there are any errors receiving the request, please use standard HTTP error response codes.

Troubleshooting

I can't seem to receive delivery receipts over HTTPS

If you do not receive requests from us to an HTTPS URL, but you can receive them over standard HTTP, a possible cause is that we do not recognize and trust your server's security certificate. You must obtain an additional certificate from one of the trusted certification authorities.