Receive an SMS Delivery Receipt (v3)

Delivery receipts inform you of the final delivery state for a message.

To receive a delivery receipt, you must include the delivery element in your MT message request.

If the SMS message was split into multiple parts (e.g., it was too long for a single SMS), then you will receive a delivery receipt for each part. In these instances the request will include two additional attributes: parentTicketId and segmentNumber.

Note: If the message originator was a US or Canadian landline or long code then you will not receive a delivery receipt.

Note: If you're new to OpenMarket, then integrate with our Global SMS (version 4) operations.
Customers currently integrated using v3 may continue to use it, although we encourage customers to migrate to v4 in order to take advantage of new features.

Quick facts

Schema

You can download a schema for the request here: https://www.openmarket.com/customer-center/download/sms/delivery-receipt-3.0.xsd

Request from OpenMarket

The request from OpenMarket includes data in the header field and request body. There are no parameters included in the request URL.

Header fields

There are no custom OpenMarket headers included in the request.

Example header

POST / HTTP/1.1
Connection: close
User-Agent: OpenMarket
Host: smsc-03.openmarket.com
Content-Length: 424
Content-Type: text/xml; charset=UTF-8

Request body

The request body contains the delivery receipt details.

Example delivery receipt

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveryReceipt ticketId="0112C-0402H-14019-14Y7K" >
   <response description="Message successfully delivered." code="4"/>
   <message deliveryDate="2012-04-02T18:01:14.293Z">
      <state description="Delivered to destination address by carrier" id="5"/>
      <reason description="Message successfully delivered." code="4"/>
   </message>
</deliveryReceipt>

You can find more examples below in Example requests,

deliveryReceipt element

response element

This element and the reason element are normally synonymous.

message element

state element

reason element

This element and the response element are normally synonymous.

Example requests

This example shows the delivery receipt for a message that was successfully delivered to a mobile operator that does not support handset delivery status receipts

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveryReceipt ticketId="01111-12013-1504Y-18K6Q">
   <response description="Message successfully sent to carrier." code="0"/>
   <message deliveryDate="2011-12-01T20:04:18.000Z">
      <state description="Delivered to carrier" id="3"/>
      <reason description="Message successfully sent to carrier." code="0"/>
   </message>
</deliveryReceipt>

This example shows the delivery receipt for a message successfully delivered to a subscriber handset by a mobile operator that does support handset delivery status receipts.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveryReceipt ticketId="0112C-0402H-14019-14Y7K">
   <response description="Message successfully delivered." code="4"/>
   <message deliveryDate="2012-04-02T18:01:14.293Z">
      <state description="Delivered to destination address by carrier" id="5"/>
      <reason description="Message successfully delivered." code="4"/>
   </message>
</deliveryReceipt>

This example shows the delivery receipt for a message that was rejected by the mobile operator.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveryReceipt ticketId="01111-12013-1504Y-18K6Q">
   <response description="Invalid destination address value." code="351"/>
   <message deliveryDate="2011-12-01T20:04:18.000Z">
      <state description="Delivery to carrier failed" id="7"/>
      <reason description="Invalid destination address value." code="351"/>
   </message>
</deliveryReceipt>

This example shows the delivery receipt for a multi-part MT segment that expired in the mobile operator's system before it could be delivered to the subscriber handset.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<deliveryReceipt ticketId="01111-12013-1504Y-19KMD" parentTicketId="01111-12013-1604Y-18MRN" note="My Internal ID or text" ">
   <response description="Message Delivery Error - Message expired by carrier" code="811"/>
   <message deliveryDate="2011-12-01T20:04:18.000Z" segmentNumber="2">
      <state description="Delivery to destination address failed" id="8"/>
      <reason description="Message Delivery Error - Message expired by carrier" code="811"/>
   </message>
</deliveryReceipt>

Responding to the request

Your platform should respond with an HTTP 200 response with "OK" in the response body. This response must be given in a timely manner (within 10 seconds).

HTTP/1.1 200 OK
Server: Microsoft IIS/6.0
Date: Tue, 29 Mar 2004 18:44:02 GMT
Content-Length: 2
Connection: close
Content-Type: text/html
 	
OK

OpenMarket will retry the request if we don't receive a response from your platform, or we receive a non-200 response. We will retry the delivery receipt for up to 24 hours. You will need to make sure that you filter duplicate requests.

Testing your integration

You can test receiving most of the delivery receipts sent by OpenMarket. See Testing Your SMS v3 Integration.

Troubleshooting

I'm not receiving any delivery receipts

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.