SMS Delivery Receipts in XML

Delivery receipts let you know whether a message has been delivered. We forward them to you by making an HTTP request to a URL of your choice. Your server must respond with a 200, OK, status code to indicate successful processing of the delivery receipt.

The easy way

Setting up default delivery receipt parameters on your account removes the need to specify the parameters on each request.

  1. Login to Clockwork and choose “Delivery Receipts” under the “Sending” menu option
  2. Enter your server URL
  3. Choose a delivery receipt type
  4. Save your settings

It takes around 30 minutes for the new defaults to be applied to your account. We make HTTP calls on port 80 and HTTPS on port 443, so you shouldn’t need to open any more ports.

The manual way

Set the DlrType, DlrUrl and DlrContent parameters on your API send.

DlrType 1: HTTP GET

Sent to your server using a standard HTTP GET. When sending an SMS set DlrContent to the query string you would like to receive, use the merge parameters to signal where the API should fill in values. All the merged values will be UrlEncoded.

DlrType 2: HTTP POST

The content type will be set to x-www-form-urlencoded so the request appears to your server as a form submission. Set DlrContent to the form fields you would like to receive, using the merge parameters to signal where the API should fill in values. All the merged values will be UrlEncoded.

DlrType 3: XML POST

An HTTP POST with the content type set to text/xml containing the XML specified in DlrContent when sending the message. The XML should use the merge parameters to signify where the API shold replace values. All merged parameters will be XML Encoded.

DlrType 4: Bulk XML

The bulk delivery receipt option will send you up to 100 delivery receipts in a single HTTP request with the content type set to text/xml. For customers sending large volumes of messages, this speeds up receipts as it removes the overhead of creating many separate connections and may reduce the load on your server. As a result of this improved efficiency there a couple of restrictions, the content cannot be customised and you must reply to each delivery receipt.

It’s important to note that using the bulk XML option will never slow down your delivery receipts, if they’re slowly trickling in one at a time from the mobile network we’ll forward them as soon as they arrive rather than wait for a batch to build up.

DlrContent Parameters

These parameters can be used in your DlrContent string and will be replaced before making the request. To use them simply surround them with # symbols, e.g. #TO#. These parameters must always be specified in upper case.

MSG_ID

The Clockwork Message ID returned when you sent the message.

TO

Phone number the message was sent to

FROM

From address of the text message

STATUS

Delivery status of the message.

DETAIL

The detail code provides more information on why a message has failed. Sometimes the mobile network doesn’t provide a reason, in these cases it will be set to unknown (1).

CLIENT_ID

Your unique ID, if provided, specified when sending the SMS.

Examples

HTTP GET or POST

DlrContent

msg_id=#MSG_ID#&status=#STATUS#&detail=#DETAIL#&to=#TO#

Sample Request

msg_id=AB_123456&status=DELIVRD&detail=0&to=441234567980

XML POST (Type 3)

DlrContent

1
2
3
4
5
6
7
<!--?xml version="1.0" encoding="utf-8"?-->
<Dlr>
  <MsgId>#MSG_ID#</MsgId>
  <Status>#STATUS#</Status>
  <Detail>#DETAIL#</Detail>
  <To>#TO#</To>
</Dlr>

Sample Request

1
2
3
4
5
6
7
<!--?xml version="1.0" encoding="utf-8"?-->
<Dlr>
  <MsgId>AB_123456</MsgId>
  <Status>DELIVRD</Status>
  <Detail>0</Detail>
  <To>441234567980</To>
</Dlr>

Bulk XML

With the bulk XML delivery receipts the receiving script must acknowledge each delivery receipt within the request. The response must contain the delivery receipt ID (DlrID) and a status (Response) indicating whether it has been processed correctly. Valid values for Response are “ok” and “error”. The DlrContent parameter is not used with this type.

Sample Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<?xml version="1.0" encoding="utf-8"?>
<DlrList>
  <Dlr type="SMS">
    <DlrID>CD_123456</DlrID>
    <ClientID>client1</ClientID>
    <MsgID>AB_123456</MsgID>
    <Status>ENROUTE</Status>
    <DestAddr>441234567890</DestAddr>
    <ErrCode>1</ErrCode>
    <SrcAddr>From</SrcAddr>
    <SubmitDate>20111021095428</SubmitDate>
    <StatusDate>20111021095433</StatusDate>
  </Dlr>
  <Dlr>
    <DlrID>CD_123457</DlrID>
    <ClientID>client2</ClientID>
    <MsgID>AB_123457</MsgID>
    <Status>DELIVRD</Status>
    <DestAddr>441234567891</DestAddr>
    <ErrCode>0</ErrCode>
    <SrcAddr>From</SrcAddr>
    <SubmitDate>20111021095428</SubmitDate>
    <StatusDate>20111021095433</StatusDate>
  </Dlr>
</DlrList>

Sample Response

1
2
3
4
5
6
7
8
9
10
<!--?xml version="1.0" encoding="utf-8"?-->
<DlrList_Resp>
  <Dlr_Resp>
    <DlrID>CD_123456</DlrID>
    <Response>ok</Response>
  </Dlr_Resp>  
  <Dlr_Resp>
    <DlrID>CD_123457</DlrID>
    <Response>ok</Response>
</DlrList_Resp>