Retrieve an individual delivery report (or combined reports), which show=
s the current known status of messages sent in a given time period, or for =
a particular campaign or campaigns.
Conversely, the function getDelive=
ryReports (page 19) gets a list of available delivery report names, includi=
ng delivery reports for campaigns.
See also What is a sent message?
messages sent with the API can be given a 'tag'. The getDeliveryReport f= unction allows you to specify that tag in order to restrict your search.
To get the contents of a delivery report for the campaign name 'mycampai= gn-020411':
DeliveryReport[] reports =3D tmClient.getDeliveryReport("mycampa=
ign-020411");=20
To get the delivery report details for 'mycampaign-020411' between 01:00= and 02:00 on 1st Jan 2011:
Calendar cal_start =3D Calendar.getInstance();
cal_start.set(2011, 1, 1, 1, 0, 0);
Calendar cal_end =3D Calendar.getInstance();
cal_end.set(2011, 1, 1, 2, 0, 0);
DeliveryReport[] reports =3D tmClient.getDeliveryReport("mycampaign-02=
0411",=20
cal_start.getTime(), cal_end.getTime);
=20
Or, between 01:00 on 1st Jan 2011 and now:
Calendar cal =3D Calendar.getInstance();
cal.set(2011, 1, 1);
DeliveryReport[] reports =3D tmClient.getDeliveryReport("mycampaign-02=
0411",=20
cal.getTime(), new Date());=20
To get delivery report details for all campaigns and API sends between t= he same dates as the previous 2 examples:
Calendar cal_start =3D Calendar.getInstance();
cal_start.set(2011, 1, 1, 1, 0, 0);
Calendar cal_end =3D Calendar.getInstance();
cal_end.set(2011, 1, 1, 2, 0, 0);
DeliveryReport[] reports =3D tmClient.getDeliveryReport("all", ca=
l_start.getTime(),=20
cal_end.getTime);
reports =3D tmClient.getDeliveryReport("all", cal.getTime(), new =
Date());
=20
To get a delivery report with the name 'mycampaign-020411', restricted t= o those messages sent with custom tag 'test':
DeliveryReport[] reports =3D tmClient.getDeliveryReport("mycampa=
ign-020411", "test");=20
To get the status of messages from all delivery reports for messages sen= t with custom tag 'test':
DeliveryReport[] reports =3D tmClient.getDeliveryReport("all&quo=
t;, "test");
=20
The same as the previous 2 examples, but between 2 dates:
Calendar cal_start =3D Calendar.getInstance();
cal_start.set(2011, 1, 1, 1, 0, 0);
Calendar cal_end =3D Calendar.getInstance();
cal_end.set(2011, 1, 1, 2, 0, 0);
DeliveryReport[] reports =3D tmClient.getDeliveryReport("all", &q=
uot;test",=20
cal_start.getTime(), cal_end.getTime);
reports =3D tmClient.getDeliveryReport("all", "test", c=
al.getTime(), new Date());
=20
A complete example, including output:
DeliveryReport[] reports =3D tmClient.getDeliveryReport("all&quo=
t;);
for(DeliveryReport report: reports) {
=09System.out.println(report);
=09for(Hashtable<String, String> row: report.getRows()) {
=09=09System.out.println("\tMessage ID: " + row.get("message=
_id"));
=09=09System.out.println("\tLast Updated: " + row.get("last_=
updated"));
=09=09System.out.println("\tMobile Number: " + row.get("mobi=
le_number"));
=09=09System.out.println("\tStatus: " + row.get("status"=
;));
=09=09System.out.println("\tCustom Tag: " + row.get("custom&=
quot;));
=09}
}=20
Arguments:
String name:
name of the delivery report to retrieve or 'all' to retrieve all campaig= n/API report data.
String custom:
restrict search to those SMS sent with a custom 'tag' (see custom parame= ter 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 rep= ort and has 5 keys, 'name', 'last_updated', 'extension' and 'rows':
| Array key | Value |
|---|---|
| name | String. The name of the delivery report conta=
ining the message statuses. |
| last_updated | String. The last time a message delivery stat= us 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 =E2=80=93 this value no longer has an= y meaning. |
| rows | ArrayList. rows is an ArrayList of Hashtable = with keys 'message_id', 'mobile_number', 'status' and 'last_updated' (see b= elow). |
reportrow is an array with 4 keys:
| Array key | Value |
|---|---|
| message_id | String. The unique ID of the sent message (di= fferent for each number sent to). |
| mobile_number | String. The mobile number that the message wa= s 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 n= ot 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 r= eceive the message and it expired. DELIVERED means the message was re= ceived on the handset. NON-UK means you are on a UK-only acount and h= ave to send a non-UK number. |
| last_updated | String. The last time this message delivery s= tatus was updated, ISO 8601 format. This allows you to determine whether th= ere has been a change since you last accessed the report. |
Specific error codes:
| Code | Meaning |
|---|---|
| 0 | The custom value must contain only alpha-nume= ric characters. |
| 1 | The custom value must be between 1 and 20 charac= ters 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 sp= ecified search criteria. See General error codes.