Skip to end of metadata
Go to start of metadata

 

Retrieve an individual delivery report (or combined reports), which shows the current known status of messages sent in a given time period, or for a particular campaign or campaigns.
Conversely, the function getDeliveryReports (page 19) gets a list of available delivery report names, including delivery reports for campaigns.
See also What is a sent message?

messages sent with the API can be given a 'tag'. The getDeliveryReport function allows you to specify that tag in order to restrict your search.

To get the contents of a delivery report for the campaign name 'mycampaign-020411':

Example

To get the delivery report details for 'mycampaign-020411' between 01:00 and 02:00 on 1st Jan 2011:

Example

Or, between 01:00 on 1st Jan 2011 and now:

Example

To get delivery report details for all campaigns and API sends between the same dates as the previous 2 examples:

Example

To get a delivery report with the name 'mycampaign-020411', restricted to those messages sent with custom tag 'test':

Example

To get the status of messages from all delivery reports for messages sent with custom tag 'test':

Example

The same as the previous 2 examples, but between 2 dates:

Example

A complete example, including output:

Example

Arguments:

 

String name: 

name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data.

String custom:

restrict search to those SMS sent with a custom 'tag' (see custom parameter of sendSms function). Up to and including 20, alpha-numeric characters.

Date date_start: 

restrict search to be from date_start (Europe/London time).

Date date_end: 

restrict search to be up to date_end (Europe/London time).

Returns:

 

an DeliveryReport object array. Each Hashtable represents a delivery report and has 5 keys, 'name', 'last_updated', 'extension' and 'rows':

Array keyValue
name

String. The name of the delivery report containing the message statuses.
For campaigns sent via the web interface, this is the campaign name that way specified.
For messages sent via one of our APIs, the name is GatewayAPI_DD-MM-YY, where DD is the calendar day, MM the month, and YY the year.

last_updated

String. The last time a message delivery status in this delivery report was updated, ISO 8601 format. This allows you to determine whether there was a change since you last accessed the report.

extensionDEPRECATED – this value no longer has any meaning.
rows 

ArrayList. rows is an ArrayList of Hashtable with keys 'message_id', 'mobile_number', 'status' and 'last_updated' (see below).

reportrow is an array with 4 keys:

Array key 

Value

message_id 

String. The unique ID of the sent message (different for each number sent to).

mobile_number

String. The mobile number that the message was sent to, in international format, e.g. 447000000000.

status 

String. The status of the message delivery.

PENDING means the status of the sent message is currently unknown.

REJECTED means that the relevant operator rejected the message and did not attempt to deliver it.

FAILED probably means that the number doesn't exist (or not anymore), or the recipient didn't turn on their phone to receive the message and it expired.

DELIVERED means the message was received on the handset.

NON-UK means you are on a UK-only acount and have to send a non-UK number.

last_updated 

String. The last time this message delivery status was updated, ISO 8601 format. This allows you to determine whether there has been a change since you last accessed the report.

Specific error codes:

CodeMeaning
0

The custom value must contain only alpha-numeric characters.

1The custom value must be between 1 and 20 characters in length.
2

The 'from' and 'to' timestamps must be in ISO 8601 format.

error code 404 is reported if no delivery reports are found using the specified search criteria. See General error codes.