Real-Time Delivery Receipts via HTTP(S) POST

When you send bulk SMS text messages using our SMS gateway, you can receive real-time delivery receipts for most destinations. Our Delivery Receipts via HTTP API supports both HTTP and HTTPS, although we strongly recommend using HTTPS for better security.

HTTP(S) POST

We do not support HTTP GET because there are security and truncation issues related to passing the message as a query string.

Service Configuration

You can configure the service on the website once you have logged in to your account. Simply click on the Real-Time Delivery Receipts section in your Account Centre menu. You will be prompted to specify these when you are configuring delivery of receipts via HTTP POST.

Parameter Type Size Description
URL string 255 The URI to be used to POST the SOAP delivery receipt to. It can be HTTP or HTTPS (recommended) and can use an IP address or FQDN with an optional port number. For example https://www.mycompany.com/cgi-bin/deliveryrecript.pl
Username string 20 The Username required to access your server. This is defined by you and is optional.
PIN string 20 The PIN required to access your server. This is defined by you and is optional.
URL
The URI to be used to POST the SOAP delivery receipt to. It can be HTTP or HTTPS (recommended) and can use an IP address or FQDN with an optional port number. For example https://www.mycompany.com/cgi-bin/deliveryrecript.pl
Username
The Username required to access your server. This is defined by you and is optional.
PIN
The PIN required to access your server. This is defined by you and is optional.

Field Descriptions

These are the fields that will be present in the HTTP POST body.

Parameter Type Size Description
Username string 20 The Username required to access your server. This is defined by you and is optional. If it is omitted, the tag=value pair will be sent as Username=NULL
PIN string 20 The PIN required to access your server. This is defined by you and is optional. If it is omitted, the tag=value pair will be sent as PIN=NULL

SendTo

numeric 15 The phone number of the device which received the message, normally in E.164/2000 format e.g. 447700912345. It called SendTo (as opposed to SentTo) so that it is symmetric with the original submission HTTP POST.
Timestamp1 string 20 The timestamp of when the Report status was recorded. If it is delivered, this is the time that the message was delivered to the phone. Format: YYYY-MM-DDTHH:MM:SSZ
MessageIdentifier string 15 The unique identifier that matches up to the one that was returned to you when the message was originally submitted.
Report numeric 3 A report code that gives the current delivery status of the message. This will match one of the Connection Software report codes.
Username
The Username required to access your server. This is defined by you and is optional. If it is omitted, the tag=value pair will be sent as Username=NULL
PIN
The PIN required to access your server. This is defined by you and is optional. If it is omitted, the tag=value pair will be sent as PIN=NULL
SendTo
The phone number of the device which received the message, normally in E.164/2000 format e.g. 447700912345. It called SendTo (as opposed to SentTo) so that it is symmetric with the original submission HTTP POST.
Timestamp1
The timestamp of when the Report status was recorded. If it is delivered, this is the time that the message was delivered to the phone. Format: YYYY-MM-DDTHH:MM:SSZ
MessageIdentifier
The unique identifier that matches up to the one that was returned to you when the message was originally submitted.
Report
A report code that gives the current delivery status of the message. This will match one of the Connection Software report codes .

Example POST

POST /cgi-bin/deliveryrecript.pl HTTP/1.0
Host: www.mycompany.com:80
Content-Type: text/html
Content-Length: 127; charset=utf-8

Username=ANOther.12345&PIN=123456789&SendTo=447700912345&Timestamp1=2005%2D07%2D26T14%3A11%3A00Z&MessageIdentifier=309B9A1A&Report=0

HTTP(S) Response

You must respond to each HTTP POST in order for the server to know that the delivery receipt was received and processed properly. If you do not, the same message may well be sent repeatedly with others being queued behind it. The response format is similar the POST format (i.e. tag=value).

Field Descriptions

Parameter Type Size Description

MessageIdentifier

string 15 The unique identifier that matches up to the one that was given to you in the HTTP POST (see above). This is intended for future developments when it may be possible to receive multiple delivery receipts in one POST.
Report numeric 3 Typically this is 0 unless some error condition has occurred (such as a mismatched delivery receipt) in which case you can either return the correct report code or default to the "catch all" of -1. The report code must match the Connection Software specified numbers, however; do not use your own.
Text string 255 Any descriptive text associated with the response. This is optional and can be left out. It is typically used for debugging integration problems.
MessageIdentifier
The unique identifier that matches up to the one that was given to you in the HTTP POST (see above). This is intended for future developments when it may be possible to receive multiple delivery receipts in one POST.
Report
Typically this is 0 unless some error condition has occurred (such as a mismatched delivery receipt) in which case you can either return the correct report code or default to the "catch all" of -1. The report code must match the Connection Software specified numbers, however; do not use your own.
Text
Any descriptive text associated with the response. This is optional and can be left out. It is typically used for debugging integration problems.

Example Response

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2002 09:31:42 GMT
Server: Apache/1.3.22 (Unix) (Red-Hat/Linux) mod_ssl/2.8.5 OpenSSL/0.9.6b DAV/1.0.2 PHP/4.0.6 mod_perl/1.24_01 mod_fastcgi/2.2.10
Content-Length: 45
Content-Type: text/html; charset=utf-8 MessageIdentifier=309B9A1A&Report=0&Text=OK

Your session is about to expire

You will be logged out in seconds.

Do you want to stay signed in?

Yes, keep me signed in     No, Sign me out