ReportStandard

Schema to supply full details of messages sent as specified by a time-period and filtering options.

The 'UserID' and 'Password' elements identify the account. The 'ServiceName' element must be set to 'ReportStandard'. The 'SoftwareVersion' element is for internal 2SMS use only and should not be set.

The 'ServiceDetail' element may have an optional boolean 'reportError' attribute. If this is set to 'true' then any additional information on message progress reported by the SMS network will be included along with the 'Status' information.

The 'ServiceDetail' element may contain a variety of elements to set date range and filtering options for the report. The different options can be classified by the name of the first element.

1. An initial 'DateRange' element.

The 'DateRange' element determines the time period for the report according to one of three options:

With 'StartDate' and 'EndDate' children it returns a report for an explicitly specified time-period (up to 31 days). The DateTime information must be supplied in one of these ISO-8601 formats:
- yyyy-MM-dd'T'HH:mm:ss.SSS in the time-zone registered with the account.
- yyyy-MM-dd'T'HH:mm:ss.SSS'Z' in coordinated universal time (the 'useUTC' attribute must be set to true).
With a 'RelativeName' child it runs a report for a relative time period described by one of the enumerated values: 'Today'; 'Yesterday'; 'This Month'; or 'Last Month'. This is evaluated with respect to the time-zone registered with the account.
With a 'RecentDays' child it runs a report for the specified period of days (up to 14) in the time-zone registered with the account. E.g. a value of two would cover the time period from the start of the previous day until the current time.

The 'RelativeName' and 'RecentDays' elements may be followed by a 'SavedReport' element. This stores the report generating information for use with code 0360 requests. The 'SavedReport' element must contain the following children:

A 'Name' element containing the name to identify the report in future.
A 'Format' element containing any additional information useful to the client application (e.g. format for results).

The remaining XML nodes that accompany a 'DateRange' element are as follows:

An optional 'useUTC' attribute set to true if date input and output is to be in coordinated universal time.
An optional 'Status' element to filter results with a specific delivery status (e.g. Success, WithNetwork or Failed).
An optional 'Destination' element to filter results sent to a specific destination.
An optional 'GUID' element to filter results with a specific GUID reference value.
A compulsory 'Paging' element whose 'ItemsPerPage' attribute determines the number of items on the report's first page.

2. An initial 'ReportPage' element.

This method is used to extract subsequent pages of data from a previously run report. Reports are retained for at least 20 minutes since the last request for a page from the report. The following child nodes are supplied:

A compulsory 'ReportID' element identifies the report (obtained from the previous XML report response).
A compulsory 'Page' element determines the page of results for the given number of ItemsPerPage.
A compulsory 'ItemsPerPage' element determines the number of items on the returned page.
An optional 'useUTC' attribute set to true if date output is to be in coordinated universal time.

3. An initial 'Batch' element.

This method returns results for a specific batch (see code 0350 for a definition). The following child elements may be supplied:

A 'GUID' element (the original GUID reference of the batch).
A 'DateID' element (an integer timestamp based on when the initial message request was received).
An optional 'useUTC' attribute set to true if date output is to be in coordinated universal time.

The 'GUID' and 'DateID' for a batch may be obtained from a call to ReportRecentBatches (code 0350) or extracted from a response to a SendMessage request (code 0410).

4. An initial 'LoggedReport' element.

This method covers two report types whose results depend on when the report was last run:

With the text content 'messagesSinceLastRequest' the method returns all messages sent since this report was last run (provided they fall within the current or previous month).
With the text content 'messageStatusChanges' the method returns all messages either sent, or whose 'Status' has changed, since this report was last run (provided this occurred within the last four days).
The optional 'useUTC' attribute should be set to true if date output is to be in coordinated universal time.

5. Deprecated methods.

A number of additional options appear in the schema to support legacy applications with non ISO-8601 DateTime formats. They should not be used in new applications as support may be removed in future.

A 'ReportName' element: use 'DateRange' with 'RelativeName' or 'LoggedReport' child instead.
A 'GUID' and 'ReportName' element: use appropriate 'DateRange' method with filtering by the 'GUID' element.
A 'StartDate', 'EndDate' and 'ReportName' element: use 'DateRange' with 'StartDate' and 'EndDate' children instead.

This method returns a successful "00/OK" response if the report is successfully retrieved. The 'Result' element contains the number of 'Record' elements. The 'Detail' element contains a 'ReportTitle' element which describes the report, and a set of 'Record' elements, each of which describes a single SMS or email message. Each record contains the following children:

The 'Destination' element contains the email or SMS number of the message's recipient.
The 'Status' element contains information on whether the submission failed, was successful, or is still awaiting confirmation.
When requested the 'Error' element contains any additional information on message progress reported by the SMS network.
The 'GUID' element contains the GUID reference value for the message.
The 'DateSubmitted' element contains the time at which 2SMS received the message from the client application.
The 'DateToSend' contains the time at which the message was scheduled to be sent to its destination. The element will be empty if the message was requested to be sent as soon as received by 2SMS.
The 'DateSent' element contains the date at which 2SMS received acknowledgement that our SMS network connection had received the message and accepted it (not supplied for deprecated methods).
The 'DateReceived' element contains the date at which 2SMS last received a 'delivery receipt' for the message from our SMS network connection (this covers various options including, but not limited to message delivery to the handset).
The 'Message' element contains the actual text of the SMS message. Components of a long SMS message commence with 'part number/total parts:' string (e.g. '1/2:')
The 'ID' element contains a unique message ID that can be used in correspondence with 2SMS.

Times are returned in ISO-8601 format (except for deprecated methods). They are in the time-zone registered with the user's account unless the 'useUTC' attribute was set to true, in which case they are in coordinated universal time.

All 'DateRange' methods and the 'ReportPage' method also return a 'ReportPage' element with the following children:

The 'ReportID' element identifies the report for the retrieval of further pages.
The 'ItemsPerPage' element is the requested number of items per page.
The 'Page' element is the current page index of the report.
The 'TotalItems' element is the total number of records in the entire report.