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

Method

POST with XML body.

Response required

HTTP 200 with "OK" in the response body.

Available

All regions

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

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

Attribute

Description

ticketId

The ticket ID is a unique OpenMarket identifier for the SMS message. You can use it to retrieve the status of the message, and to identify the correct delivery receipt for a message. This ID is also passed to reporting and is useful if you need to query message activity with OpenMarket Support.

Returned: always

Type: string

parentTicketId

This is returned if the SMS message was split into multiple parts for sending. The parentTicketId matches the ticket ID we initially returned in response to your Send SMS request. The ticketId identifies the individual message part.

A long message is only divided into multiple parts if the message request included with the mlc option set to 2, or if your SMS account is provisioned by default to automatically divide long messages into multiple messages.

Returned: Only for multipart messages

Type: string

note

Returned if you included the note attribute with the message request. This has a maximum length of 200 characters.

Returned: Only when a note was submitted with the MT

Type: Latin-1 string

response element

This element and the reason element are normally synonymous.

Attribute

Description

code

The OpenMarket delivery response code defining the final outcome of the message. You will also see this code in your reports.

See Response and Delivery Receipt Codes for SMS Version 3 API.

Returned: always

Type: integer

description

Text description of the delivery response code.

Returned: If a description exists. Most (but not all) response codes have a description.

Type: string

message element

Attribute

Description

deliveryDate

The time and date the message reached the:

  • End user's mobile handset, if the mobile operator supports handset delivery receipts.
  • Mobile operator, if the operator does not support handset delivery receipts.

For example: 2015-12-25T06:02:18.123Z

Returned: Only when the message reached the handset (or mobile operator).

Type: UTC time in the format: YYYY-MM-DDThh:mm:ss.sssZ.

segmentNumber

The segment number for a message divided into multiple SMS messages. The numbering starts as "1". For example, if a long message is split into two SMS, then the segmentNumber of the second message is 2.

Returned: Only when a message is divided into multiple parts.

Type: integer

state element

Attribute

Description

id

Defines the state of SMS message delivery for the MT referenced in the delivery receipt. Valid values are: 1,2,3,5,6,7,8.

Returned: Always

Type: integer

description

Text description of state ID. Values for each ID number are:

  • 1 — Created
  • 2 — Submitted to carrier
  • 3 — Delivered to carrier
    Note: State ID 3 represents the final successful state of SMS message delivery for carriers which do not support handset delivery status receipts.
  • 5 — Delivered to destination address by carrier
    Note: State ID 5 represents the final successful state of SMS message delivery for carriers which do support handset delivery status receipts.
  • 6 — Delivery to carrier not attempted
  • 7 — Delivery to carrier failed
  • 8 — Delivery to destination address failed

Returned: Always

Type: string

reason element

This element and the response element are normally synonymous.

Attribute

Description

code

The OpenMarket delivery response code defining the final outcome of the message. You will also see this code in your reports.

See Response and Delivery Receipt Codes for SMS Version 3 API.

Returned: always

Type: integer

description

Text description of the delivery response code.

Returned: If a description exists. Most (but not all) response codes have a description.

Type: string

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.