|
Delivery Receipts via HTTP(S) POST
Real-Time status reports for the messages you send
When you send messages, if you have a corporate account you can receive real-time delivery receipts for most destinations using the HTTP(S) protocol with the POST command. GET is not supported because of the security and truncation issues which can exist with this command. You can configure this yourself on the website once you have logged in to your corporate account. Simply select Configure Services->Delivery Receipts from the menu bar at the top of the page.
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. We would strongly urge you to use the HTTPS option rather than simply HTTP for improved security. A Username and PIN can help protect you against any would be spoofing attempt.
Configuration
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.csoft.co.uk:443/cgi-bin/deliveryreceipt |
| 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. |
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. |
Example POST
The following example has been split over multiple lines for presentational purposes, but would in fact be one continuous line in reality from SendTo into Timestamp1.
POST /cgi-bin/deliveryrecript.pl HTTP/1.0
Host: www.csoft.co.uk: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 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 occured (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. |
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