Real-Time Delivery Receipts via SOAP over HTTP(S)

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 SOAP API supports both HTTP and HTTPS, although we strongly recommend using HTTPS for better security.

Web Service Definition Language (WSDL)

The WSDL and XSD files are available at:

The WSDL file is the definitive resource for determining the API specification.

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. The following parameters are required to configure this API:

  • The URL to POST to
  • The Username that you require for authentication (optional).
  • The PIN that you require for authentication (optional).
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. 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. 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.

Tags in the SOAP POST

Parameter Type Size Description
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.

SentTo

numeric 15 The phone number of the device which received the message, normally in E.164/2000 format e.g. 447700912345.
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.
PIN
The PIN required to access your server. This is defined by you and is optional.
SentTo
The phone number of the device which received the message, normally in E.164/2000 format e.g. 447700912345.
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.

Tags in the SOAP response

Parameter Type Size Description

MessageIdentifier

numeric 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 HTTP POST

POST /cgi-bin/deliveryrecript.pl HTTP/1.0
Host: www.another.com:80
Content-Type: text/soap
Content-Length: 909

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"          
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
    xmlns:ns2="http://www.itsarrived.net/dtd/sendsms5.xsd">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitDeliveryReceipt>
<Username xsi:type="xsd:string">ANOther.61234</Username>
<PIN xsi:type="xsd:string">BLUE.music</PIN>
<Timestamp1 xsi:type="xsd:dateTime">2002-08-27T13:38:00Z</Timestamp1>
<SentTo xsi:type="xsd:string">447009123456</SentTo>
<MessageIdentifier xsi:type="xsd:string">3C7D98A4</MessageIdentifier>
<Report xsi:type="xsd:int">0</Report>
</ns2:SubmitDeliveryReceipt>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example HTTP 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: 730
Content-Type: text/soap; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
    xmlns:ns2="http://www.itsarrived.net/dtd/sendsms5.xsd"> 
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitDeliveryReceiptResponse>
<MessageIdentifier xsi:type="xsd:string">3C7D98A4</MessageIdentifier>
<Report xsi:type="xsd:int">0</Report>
<Text xsi:type="xsd:string">
</ns2:SubmitDeliveryReceiptResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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