getDeliveryReport

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 orcampaigns.

Conversely, the function getDeliveryReports gets a list of available delivery report names, including delivery reports for campaigns.

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.

See also What is a sent message?

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

Returns:

an array of arrays. Each nested array represents a delivery report and has 4 keys: 'name', 'last_updated', 'extension' and 'reportrow':

Array key	Value
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.
extension	DEPRECATED – this value no longer has any meaning.
reportrow	Array. reportrow is an array 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 account and have tried to send a non-UK number
last_updated	String. The last time this message delivery status was updated, ISO8601 format. This allows you to determine whether there has been a change since you last accessed the report.

Specific error codes:

Code	Meaning
0	The custom value must contain only alpha-numeric characters
1	The 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.

Next: getDeliveryReports
Home: Developers Documentation

You must know!

Our example code is an illustration of how you might integrate with our systems and is not certified for production environments. You are responsible for testing and QA.