HTTP Global SMS API

Receive a Delivery Receipt

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

Method

POST with JSON 

Response required

HTTP 200 response with an empty response body.

Available

All regions.

Prerequisites

You must have SMS messaging provisioned with OpenMarket.

More information

See Overview.

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

Field

Description

X-API-Version

Identifies that this request comes from version 4 of our HTTP API.

Returned: Always

Type: A string of 1 to 30 characters in length.

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-12-01T20:04:18.000Z",
         "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.

Member

Description

ticketId

The ticket ID that identifies the SMS message in OpenMarket requests and reporting. The maximum length is 23 characters.

Returned: always

Type: string

deliveryDate

The time and date that OpenMarket received a delivery receipt back from the mobile operator.

This is returned with most delivery receipts or status requests (not just "Message delivered" receipts). The date string is in the following form. Time zone is UTC:

YYYY-MM-DDTHH:MM:SSZ

For example:

2015-09-22T04:10:33Z

Returned: not always returned

Type: string

code

Code identifying the current delivery status for the message. See Delivery Receipt Codes and Troubleshooting.

Returned: always

Type: string

description

Description of the current delivery status for the message. Delivery Receipt Codes and Troubleshooting.

Returned: not always returned

Type: string

note1

Returned only if you included note1 in the MT request. This is the value you sent.

Returned: not always returned

Type: string

note2

Returned only if you included note2 in the MT request. This is the value you sent.

Returned: not always returned

Type: string

mobileOperatorId

 

This is decommissioned but still included for backwards compatibility. See instead the mobileOperatorId that is part of the destination object.

Returned: not always returned

Type: integer

totalSegments

You will receive totalSegments and segmentNumber if the message was split into multiple parts.

The value of totalSegments is the total number of parts into which OpenMarket split the message.

See Single and Multipart Messages.

Returned: not always returned

Type: integer

segmentNumber

Identifies the message part. The numbering begins at "1".

Returned: not always returned

Type: integer

type

Member

Description

type

The type of delivery receipt you are receiving. Only one option, final, exists.

Returned: always

Type: string

source object

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

This object is not always included in the response.

Member

Description

address

The source address submitted in the MT message. The maximum length is 20 characters.

Returned: always

Type: ASCII character string

ton

Indicates what type of number is set in address. Either:

  • 1 — An international format number
  • 3 — A short code
  • 5 — An alphanumeric string

Returned: always

Type: integer

destination object

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

The destination object is always present

Member

Description

address

The destination address specified in the MT message. This is between 5 to 20 characters.

Returned: always

Type: string

mobileOperatorId

A numeric ID representing the mobile operator as known by OpenMarket; e.g., 383 for AT&T in the US.

For a list of the valid IDs, see Mobile Operator IDs.

Returned: not always returned

Type: integer

alpha2Code

The country that the mobile number is registered in. This is based on the calling prefix. The ID we return is the 2-character ISO 3166 alphanumeric country code. For example:

  • GB — United Kingdom
  • US  — United States
  • IN  — India

Returned: not always returned

Type: string

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.