Messaging Web Service

Table of contents

1.1 FAULT RESPONSE FORMAT
1.2 CHECK USER REQUEST
1.2.1 FORMAT OF THE CHECK USER REQUEST
1.2.2 EXPLANATION OF THE CHECK USER REQUEST FORMAT
1.3 CHECK USER RESPONSE
1.3.1 FORMAT OF THE CHECK USER RESPONSE
1.3.2 EXPLANATION OF THE CHECK USER RESPONSE FORMAT
1.4 SEND MESSAGES REQUEST
1.4.1 FORMAT OF THE SEND MESSAGES REQUEST
1.4.2 EXPLANATION OF THE SEND MESSAGES REQUEST
1.5 SEND MESSAGES RESPONSE
1.5.1 FORMAT OF THE SEND MESSAGES RESPONSE
1.5.2 EXPLANATION OF THE SEND MESSAGES RESPONSE
1.6 CHECK REPLIES REQUEST
1.6.1 FORMAT OF THE CHECK REPLIES REQUEST
1.6.2 EXPLANATION OF THE CHECK REPLIES REQUEST FORMAT
1.7 CHECK REPLIES RESPONSE
1.7.1 FORMAT OF THE CHECK REPLIES RESPONSE
1.7.2 EXPLANATION OF THE CHECK REPLIES RESPONSE FORMAT
1.8 CHECK REPORTS REQUEST
1.8.1 FORMAT OF THE CHECK REPORTS REQUEST
1.8.2 EXPLANATION OF THE CHECK REPORTS REQUEST FORMAT
1.9 CHECK REPORTS RESPONSE
1.9.1 FORMAT OF THE CHECK REPORTS RESPONSE
1.9.2 EXPLANATION OF THE CHECK REPORTS RESPONSE FORMAT
1.10 CONFIRM REPLIES REQUEST
1.10.1 FORMAT OF THE CONFIRM REPLIES REQUEST
1.10.2 EXPLANATION OF THE CONFIRM REPLIES REQUEST FORMAT
1.11 CONFIRM REPLIES RESPONSE
1.11.1 FORMAT OF THE CONFIRM REPLIES RESPONSE
1.11.2 EXPLANATION OF THE CONFIRM REPLIES RESPONSE FORMAT
1.12 CONFIRM REPORTS REQUEST
1.12.1 FORMAT OF THE CONFIRM REPORTS REQUEST
1.12.2 EXPLANATION OF THE CONFIRM REPORTS REQUEST FORMAT
1.13 CONFIRM REPORTS RESPONSE
1.13.1 FORMAT OF THE CONFIRM REPORTS RESPONSE
1.13.2 EXPLANATION OF THE CONFIRM REPLIES RESPONSE FORMAT
1.14 DELETE SCHEDULED MESSAGES REQUEST
1.14.1 FORMAT OF THE DELETE SCHEDULED MESSAGES REQUEST
1.14.2 EXPLANATION OF THE DELETE SCHEDULED MESSAGES REQUEST FORMAT
1.15 DELETE SCHEDULED MESSAGES RESPONSE
1.15.1 FORMAT OF THE DELETE SCHEDULED MESSAGES RESPONSE
1.15.2 EXPLANATION OF THE DELETE SCHEDULED MESSAGES RESPONSE FORMAT
1.16 BLOCK NUMBERS REQUEST
1.16.1 FORMAT OF THE BLOCK NUMBERS REQUEST
1.16.2 EXPLANATION OF THE BLOCK NUMBERS REQUEST FORMAT
1.17 BLOCK NUMBERS RESPONSE
1.17.1 FORMAT OF THE BLOCK NUMBERS RESPONSE
1.17.2 EXPLANATION OF THE BLOCK NUMBERS RESPONSE FORMAT
1.18 UNBLOCK NUMBERS REQUEST
1.18.1 FORMAT OF THE UNBLOCK NUMBERS REQUEST
1.18.2 EXPLANATION OF THE UNBLOCK NUMBERS REQUEST FORMAT
1.19 UNBLOCK NUMBERS RESPONSE
1.19.1 FORMAT OF THE UNBLOCK NUMBERS RESPONSE
1.19.2 EXPLANATION OF THE UNBLOCK NUMBERS RESPONSE FORMAT
1.20 GET BLOCKED NUMBERS REQUEST
1.20.1 FORMAT OF THE GET BLOCKED NUMBERS REQUEST
1.20.2 EXPLANATION OF THE GET BLOCKED NUMBERS REQUEST FORMAT
1.21 GET BLOCKED NUMBERS RESPONSE
1.21.1 FORMAT OF THE GET BLOCKED NUMBERS RESPONSE
1.21.2 EXPLANATION OF THE GET BLOCKED NUMBERS RESPONSE FORMAT

Section 1: Messaging Requests and Responses

This section describes the XML format of requests and responses used by the MessageMedia Messaging Web Service. There are six requests supported by the XML Interface: Check User, Send Messages, Check Replies, Confirm Replies, Check Reports and Confirm Reports.

1.1 FAULT RESPONSE FORMAT

Fault responses are returned by the Messaging Web Service when a request cannot be fulfilled. If the Messaging service is being used as a SOAP web service the fault response will be returned within the detail element of the SOAP fault envelope as described in Section 5.1.4. If the Messaging service is being used as a generic HTTP-POST web service the fault response will be returned verbatim as a XML document.

The following listing provides an example fault response that would be returned if the XML request was either badly formed or was not valid against the relevant schema.

<faultResponse xmlns=”http://xml.m4u.com.au/2009″>
<error code=”invalidDataFormat”/>
</faultResponse>

Listing 7.1.1: Example Fault Response

Fault responses specify an error code that indicates the reason as to why the fault occurred. The following table describes each of the fault error codes in detail.

Error Code Description
authenticationFailed The user ID or password was invalid.
invalidDataFormat Either the request was not well-formed XML or the request was not valid against the relevant XML schema.
perDayMessageLimit There were not enough daily message credits to fulfill the Send Messages request. If there is not enough credit to send all messages in the request no messages will be sent. This error code only pertains to the Send Messages request.

Table 1.1.1: Fault Response Error Codes

A fault response always implies that no action was performed on behalf of the request. A perDayMessageLimit fault response implies that no messages were sent. For example, if the user has 100 daily message credits remaining but attempts to send a batch of 101 messages a perDayMessageLimit fault response will be returned because the Messaging Web Service could not fulfill the request in its entirety.

1.2 CHECK USER REQUEST

The Check User request is used to authenticate a user and obtain their account credit details.

1.2.1 FORMAT OF THE CHECK USER REQUEST

Listing 1.2.1.1 shows an example Check User request.

<checkUser xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
</checkUser>

Listing 1.2.1.1: Example Check User Request

1.2.2 EXPLANATION OF THE CHECK USER REQUEST FORMAT

This section provides an explanation of the elements and attributes that are used in the Check User request. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Check User request see the Check User request XML schema provided in Appendix A.1.

<checkUser> The root element of the Check User request.
xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.

Table 1.2.2.1: Explanation of Check User Request Format

1.3 CHECK USER RESPONSE

The Check User response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Check User request. The response provides the account credit details of the user.

1.3.1 FORMAT OF THE CHECK USER RESPONSE

Listing 1.3.1.1 shows an example Check User response.

<checkUserResponse xmlns=”http://xml.m4u.com.au/2009″>
<result>
<accountDetails type=”daily” creditLimit=”5000″ creditRemaining=”4995″/>
</result>
</checkUserResponse>

Listing 1.3.1.1: Example Check User Response

1.3.2 EXPLANATION OF THE CHECK USER RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Check User response. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Check User response see the Check User response XML schema provided in Appendix A.2.

 <checkUserResponse> The root element of the Check User response.
Xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
 <result> This element contains the result of the Check User request.
 <accountDetails> This element provides attributes which summarise the credit details of the account. This element will not be present if errors occur.
Type This attribute specifies the type of crediting used by the account. The value of this attribute is always “daily” as only the daily crediting type exists. Account credit limits are per-day message limits and are refreshed each day.
creditLimit This attribute specifies the daily credit limit of the account. This value indicates the number of individual SMS or voice messages which may be sent each day. For changes to this limit users should speak to their sales representative.
creditRemaining This attribute specifies the amount of daily credit remaining for the account. This value indicates the number of individual SMS or voice messages which may be sent for the current day.

Table 1.3.2.1: Explanation of Check User Response Format

1.4 SEND MESSAGES REQUEST

Listing 1.4.1.1 shows an example Send Messages request.

<sendMessages xmlns=”http://xml.m4u.com.au/2009“>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<messages sendMode=”normal”>
<message format=”SMS” sequenceNumber=”1″>
<origin>61410000000</origin>
<recipients>
<recipient uid=”1″>61410000001</recipient>
<recipient uid=”2″>61410000002</recipient>
<recipient uid=”3″>61410000003</recipient>
<recipient uid=”4″>61410000004</recipient>
</recipients>
<content>Message 1</content>
</message>
<message format=”SMS” sequenceNumber=”2″>
<recipients>
<recipient uid=”5″>61410000005</recipient>
</recipients>
<scheduled>2012-12-25T15:30:00Z</scheduled>
<content>Message 2</content>
</message>
<message format=”voice” sequenceNumber=”3″>
<recipients>
<recipient uid=”6″>61410000006</recipient>
</recipients>
<content>Message 3</content>
</message>
<message format=”SMS” sequenceNumber=”4″>
<recipients>
<recipient uid=”7″>61410000007</recipient>
<recipient uid=”8″>61410000008</recipient>
</recipients>
<deliveryReport>true</deliveryReport>
<validityPeriod>143</validityPeriod>
<content>Message 4</content>
</message>
</messages>
</requestBody>
</sendMessages>

Listing 1.4.1.1: Example of a Send Messages Request

Listing 1.4.1.2 shows an example Send Messages request with Tags.

<sendMessages xmlns=”http://xml.m4u.com.au/2009“>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<messages sendMode=”normal”>
<message format=”SMS” sequenceNumber=”1″>
<recipients>
<recipient uid=”5″>61410000005</recipient>
</recipients>
<content>Message 1</content>
<tags>
<tag name=”costCode”>101</tag>
<tag name=”dept”>AAAA</tag>
</tags>
</message>
</messages>
</requestBody>
</sendMessages>

Listing 1.4.1.2: Example of a Send Messages Request with Tags.

1.4.2 EXPLANATION OF THE SEND MESSAGES REQUEST

This section provides an explanation of the elements and attributes that are used in the Send Messages request. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Send Messages request see the Send Messages request XML schema provided in Appendix A.3.

<sendMessages> The root element of the Send Messages request.
Xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
 <userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
 <password> This element specifies the password of the user which is used for authentication.
 <requestBody> This element contains the list of messages to send.
 <messages> The body of a Send Messages request must always contain this element. This element specifies all the messages that are requested to be sent.
sendMode (Optional) This attribute specifies a “send mode” to be used to send the messages. Normally, this attribute should not be set, or be set to the default value of “normal”. Supported send modes are:• “dropAll” – to drop (not send) the requested messages, and return a result indicating that messages were sent / scheduled successfully or failed to send at random.
• “dropAllWithErrors” – to drop (not send) the requested messages, and return a result indicating that all messages failed to send.
• “dropAllWithSuccess” – to drop (not send) the requested messages, but return a result indicating all messages were sent / scheduled successfully.
• “normal” – to send the requested messages as normal.The “dropAll*” modes are intended for testing purposes only.
 <message> This element specifies a single message. A message always consists of one or more recipients and message content.
format This attribute specifies the format of the message. The format must be either “SMS” or “voice”. If a format other than these is specified the request will not pass schema validation and an invalidDataFormat error will be returned.
sequenceNumber (Optional) This attribute specifies a sequence number that is assigned to the message and is used to identify the message if an error occurs. Each message error in the response will specify the sequence number of the message that caused the error. Sequence numbers should be unique within the request.Sequence numbers must be unsigned integers and may range from 1 to 2147483647. If no sequence number is specified and a message error occurs the error will have a sequence number of zero.
 <origin> (Optional) This element specifies the message source address. The specified address will be used wherever possible, however due to limitations with various carriers, legislation etc, the final message is not guaranteed to come from the specified address.The address should not contain more than 11 characters, and should only consist of the following characters: 0-9, a-z, A-Z, and _This element will be ignored if the scheduled element is present.This element will be ignored if the corresponding feature has not been enabled in the MessageMedia gateway for this account.
 <recipients> This element contains the one or more recipient elements.
 <recipient> This element specifies a recipient of the message. A message must have one or more recipients.The recipient number may be specified in either international or non-international format. If the number is specified in non-international format then the international prefix of the user’s operating country will be used. The operating country may be specified by the user when the user signs up to use the service and may be changed via the MyAccount website.
uid (Optional) This attribute specifies a user-defined unique ID that is assigned to a message-recipient pair. The uid is an unsigned integer that uniquely identifies a message sent to a particular recipient.uid values are used for three things: to identify a message-recipient in the case of an error; to match a reply message to the sent message it is in response to; and to match a delivery report to the sent message it is in response to.If no uid value is specified a default value of zero is assigned.When using message tags, it is important to include a unique UID attribute for each recipient for all messages sent via a user account to ensure accurate reporting.When using message tags, a non-zero UID must be included for each recipient. Not including a UID or setting the UID to 0 will result in a validation error.
 <scheduled> (Optional) This element may optionally be used to schedule a message for future delivery. The content of this element specifies the date and time at which the message should be sent and must be specified in the standard XML schema dateTime format. The format of the dateTime data type is described in detail here and here.Briefly, the contents of this element should be specified in the format “YYYY-MM-DDThh:mm:ss” where:• YYYY indicates the year
• MM indicates the month
• DD indicates the day
• T indicates the start of the required time section
• hh indicates the hour
• mm indicates the minute
• ss indicates the secondTo avoid confusion scheduled messages should always specify a time zone. To specify a time zone you can either enter a dateTime in UTC time by appending a “Z” as in “2010-12-25T15:30:00Z” as is specified in the example in Listing 7.4.1. Time zones may also be specified as offsets from UTC by appending a positive or negative time as in “2010-12-25T15:30:00+05:00” or “2010-12-25T15:30:00-05:00”.Messages that are scheduled for a date and time less than or equal to the current date and time will be sent immediately.
<deliveryReport> (Optional) This element is a Boolean element which specifies whether delivery reporting is requested for the message. If this attribute is not specified a default value of “false” is assumed and no delivery reporting is requested. If this element has a value of “true” a delivery report will be requested for each message-recipient.Delivery reports only pertain to SMS messages (i.e. it is not possible to receive a delivery report for a voice message). See Section 7.8 for more information on delivery reports.
<validityPeriod> (Optional) This element specifies the validity period of the message. Should the message-recipient be unavailable the service provider will continue to attempt delivery until the delivery period expires.Validity period only applies to SMS messages. If this element is specified the value must be an unsigned byte (i.e. an integer between 0 and 255 inclusive). The value of the validityPeriod element determines the validity time period as follows:• For values ranging from 0 to 143 the time period is equal to: (value + 1) x 5 minutes
• For values ranging from 144 to 167 the time period is equal to: 12 hours + (value – 143) x 30 minutes
• For values ranging from 168 to 196 the time period is equal to: (value – 166) x 1 day
• For values ranging from 197 to 255 the time period is equal to: (value – 192) x 1 weekIf this element is not specified a value of 169 is assumed which equates to 3 days.
 <tags> (Optional) This element specifies the arbitrary set of tags which are name/value pairs. The tags are configured as custom fields for individual message (not actually sent out as part of message text).An example of this is tagging messages with a cost code to facilitate cost reconciliation for messages sent from various departments within an organisation:<tags>
<tag name=”costCode”>101</tag>
<tag name=”dept”>AAAA</tag>
</tags>If the message tags feature has not been enabled by MessageMedia for this account, usage of this element will result in validation error. Please contact support for more information.Including the same tag twice as below will result in a validation error<tags>
<tag name=”costCode”>101</tag>
<tag name=”costCode”>102</tag>
</tags>Tag names are case insensitive. The following tag blocks are identical:<tags>
<tag name=”costCode”>101</tag>
</tags>
<tags>
<tag name=”COSTCODE”>101</tag>
</tags><tags>
<tag name=”costcode”>101</tag>
</tags>When using message tags, it is important to include a unique UID attribute for each recipient for all messages sent via a user account to ensure accurate reporting.

When using message tags, a non-zero UID must be included for each recipient. Not including a UID or setting the UID to 0 will result in a validation error.

 <content> This element specifies the content of the message. There is no hard limit on the size of the content. SMS messages greater than 160 characters are not split up into multiple SMS messages—SMS concatenation is used so that they are delivered to the recipient as a single long message.

Table 7.4.2.1: Explanation of Send Messages Request Format

1.5 SEND MESSAGES RESPONSE

The Send Messages response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Send Messages request. The response provides a summary of the result of the request, the updated account credit details and a list of any messages that could not be sent due to errors.

1.5.1 FORMAT OF THE SEND MESSAGES RESPONSE

Listing 1.5.1.1 shows an example Send Messages response that does not contain any errors.

<sendMessagesResponse xmlns=”http://xml.m4u.com.au/2009″>
<result sent=”50″ scheduled=”10″ failed=”0”>
<accountDetails type=”daily” creditLimit=”5000″ creditRemaining=”2500″/>
</result>
</sendMessagesResponse>
Listing 1.5.1.1: Example Send Messages Response

In the example response shown in Listing 7.5.1.1 the result (specified by the result element) indicates that 50 individual messages were sent, 10 individual messages were scheduled and 0 individual messages failed. The accountDetails element provides a summary of the account details after the request has been fulfilled. This information can be used to keep track of remaining account credit.

Listing 1.5.1.2 shows an example Send Messages response that reports errors.

<sendMessagesResponse xmlns=”http://xml.m4u.com.au/2009″>
<result sent=”25″ scheduled=”5″ failed=”6”>
<accountDetails type=”daily” creditLimit=”5000″ creditRemaining=”1500″/>
<errors>
<error code=”emptyMessageContent” sequenceNumber=”1″>
<recipients>
<recipient uid=”1″>61410000001</recipient>
<recipient uid=”2″>61410000002</recipient>
<recipient uid=”3″>61410000003</recipient>
<recipient uid=”4″>61410000004</recipient>
</recipients>
</error>
<error code=”recipientBlocked” sequenceNumber=”2″>
<recipients>
<recipient uid=”5″>61400000001</recipient>
</recipients>
</error>
<error code=”invalidRecipient” sequenceNumber=”3″>
<recipients>
<recipient uid=”6″>ABC</recipient>
</recipients>
</error>
</errors>
</result>
</sendMessagesResponse>
Listing 1.5.1.2: Example Send Messages Response Containing Errors

In the example response shown in Listing 7.5.1.2 the result element indicates that 25 individual messages were sent, 5 individual messages were scheduled and 6 individual messages failed. In this example 3 errors are reported affecting 6 recipients in total. Each error specifies an error code that defines the type of error and the sequence number of the message that caused the error. Each affected recipient specifies the same uid value that was assigned to the recipient in the request.

There are 4 possible error codes. Each of these error codes is described in the following table.

Error Code Description
invalidRecipient One or more recipients were invalid.
recipientBlocked One or more recipients were on the blocked list
emptyMessageContent The message content was empty.
other An unknown error occurred. error elements with this code may contain an additional content element with a human-readable description of the error. Users who receive this type of error should contact MessageMedia Support.

Table 1.5.1.1: Types of Message Errors

Each error element in the response may be linked to the message element in the request that caused the error via the sequence number (sequenceNumber attribute). Additionally, each affected recipient element in the response can be linked to the recipient element in the request via the unique ID (uid attribute) assigned to that message-recipient. The uid attribute may also used to match a reply message to the sent message that the reply is in response to. For this reason it is recommended that sequence numbers be unique within a single Send Messages request and unique IDs be unique over the period of time within which a reply could be received. If a database is being used to store messages sent by the client application, a common practice is to use the integer-based primary key of the message as the unique ID. This guarantees that the ID will be unique and easily allows reply messages to be matched to sent messages.

1.5.2 EXPLANATION OF THE SEND MESSAGES RESPONSE

THIS SECTION PROVIDES AN EXPLANATION OF THE ELEMENTS AND ATTRIBUTES THAT ARE used in the Send Messages response. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Send Messages response see the Send Messages response XML schema provided in Appendix A.4.

<sendMessagesResponse> The root element of the Send Messages response.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This attributes of this element provide a summary of the result of the Send Messages request. It contains the accountDetails element as well as an errors element if any errors occurred.
sent This attribute specifies the number of message-recipients whose messages were successfully processed for sending. For example, if 3 messages were submitted in the request and each message had 5 recipients this attribute will report a value of 15.
scheduled Description
Error Code This attribute specifies the number of message-recipients whose messages were successfully scheduled for future delivery. For example, if 3 scheduled messages were submitted in the request and each message had 5 recipients this attribute will report a value of 15.If the scheduled date and time specified in the request is less than or equal to the current date and time the message will be sent immediately and will be reported in the sent count not the scheduled count.
failed This attribute is a Boolean attribute which specifies the number of message-recipients whose messages were not successfully processed. This number includes both failed non-scheduled and failed scheduled messages. If this number is greater than 0 the errors element will be present inside the result element and it will contain errors pertaining to each of the affected recipients.
<accountDetails> This element provides attributes which summarise the credit details of the account after the request has been fulfilled. It will also contain an errors element if (and only if) the failed attribute reports a value greater than 0.
type This attribute specifies the type of crediting used by the account. The value of this attribute is always “daily” as only the daily crediting type exists. Account credit limits are per-day message limits and are refreshed each day.
creditLimit This attribute specifies the daily credit limit of the account. This value indicates the number of individual SMS or voice messages which may be sent each day. For changes to this limit users should speak to their sales representative.
creditRemaining This attribute specifies the amount of daily credit remaining for the account. This value indicates the number of individual SMS or voice messages which may be sent for the current day.
<errors> (Optional) This element contains errors that occurred during the processing of the request and will be present only if errors occurred. If this element is present it will contain one or more error elements. This element will only be present if the failed attribute of the parent result element reports a value greater than 0. The total number of affected recipients reported by all error elements will be equal to the value of the failed attribute.
<error> This element reports an error that occurred in the processing of the request.
code This attribute specifies the error code of the error. The error code defines the type of error and is one of the values specified in Table 7.5.1.1.The error codes that may result from a Send Messages request are: invalidRecipient, recipientBlocked, emptyMessageContent and other.
sequenceNumber For a message error this attribute specifies the sequence number of the message that resulted in the error. If no sequence number was assigned to the message in the request the value of this attribute will be zero.
<content> (Optional) This element is sometimes specified within the error element. It is used to report additional error content. It is only used when value of the code attribute is “other”.
<recipients> This element contains one or more recipient elements.
<recipient> This element specifies the recipient who was affected by the error and as such did not receive their message.
uid This attribute specifies the user-defined unique ID that was assigned to the message-recipient pair in the request. For this reason unique values should be used so that the affected message-recipient can be correctly identified. If the uid was not specified in the request the value of this attribute will be zero.

Table 7.5.2.1: Explanation of Send Messages Response Format

1.6 CHECK REPLIES REQUEST

The Check Replies request is used to download reply messages that are waiting on the gateway. Reply messages are downloaded for a specific user account. Reply messages will remain marked as unsent and will be downloaded each time the Check Replies request is made until they are confirmed by the user as having been received. See Section 7.10 for details on confirming replies.

1.6.1 FORMAT OF THE CHECK REPLIES REQUEST

Listing 1.6.1.1 shows an example Check Replies request.

<checkReplies xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<maximumReplies>100</maximumReplies>
</requestBody>
</checkReplies>

Listing 1.6.1.1: Example Check Replies Request

1.6.2 EXPLANATION OF THE CHECK REPLIES REQUEST FORMAT

This section provides an explanation of the elements and attributes that are used in the Check Replies request. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Check Replies request see the Check Replies request XML schema provided in Appendix A.5.

<checkReplies> The root element of the Check Replies request.
xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the optional maximumReplies element.
<maximumReplies> (Optional) This element is used to specify the maximum number of replies to download in the response. If this element is not specified all waiting reply messages will be downloaded in the response.

Table 7.6.2.1: Explanation of Check Replies Request Format

1.7 CHECK REPLIES RESPONSE

The Check Replies response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Check Replies request. The response contains a list of unconfirmed reply messages waiting on the gateway. If the maximumReplies element was specified in the request then the value of that element will determine the maximum number of replies present in the response. If no maximum was specified all unconfirmed replies will be present in the response.

1.7.1 FORMAT OF THE CHECK REPLIES RESPONSE

Listing 1.7.1.1 shows an example Check Replies response.

<result returned=”3″ remaining=”0″>
<replies>
<reply format=”SMS” uid=”1″ receiptId=”13067831″>
<origin>61400000001</origin>
<received>2010-12-25T16:35:21Z</received>
<content>Reply Content 1</content>
</reply>
<reply format=”SMS” uid=”2″ receiptId=”13067832″>
<origin>61400000002</origin>
<received>2010-12-25T16:35:22Z</received>
<content>Reply Content 2</content>
</reply>
<reply format=”SMS” uid=”3″ receiptId=”13067833″>
<origin>61400000003</origin>
<received>2010-12-25T16:35:23Z</received>
<content>Reply Content 3</content>
</reply>
</replies>
</result>
</checkRepliesResponse>

Listing 1.7.1.1: Example Check Replies Response

1.7.2 EXPLANATION OF THE CHECK REPLIES RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Check Replies response. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Check Replies response see the Check Replies response XML schema provided in Appendix A.6.

<checkRepliesResponse> The root element of the Check Replies request.
xmlns always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This element provides attributes which summarise the result of the Check Replies request. It contains a list containing any downloaded reply messages.
returned This attribute specifies the number of replies returned in the response.
remaining This attribute specifies the number of replies remaining on the gateway for the user.
<replies> This element contains any reply messages downloaded from the gateway. It will contain zero or more reply elements. The reply messages are listed in ascending order of their received time.
<reply> (Optional) This element is used to specify a single reply message.
format This attribute specifies the format of the reply message. As only SMS reply messages are supported the value of this attribute will always be “SMS”.
uid This attribute specifies the unique user-defined ID assigned to the message that this reply is in response to. The value of this ID allows client applications to match inbound reply messages to outbound messages. If no uid was assigned to the outbound message this attribute will have a value of zero.
receiptId This attribute specifies a unique receipt ID. This ID is to be used by the client application when confirming receipt of the reply. Until replies are confirmed they will be marked as unsent and will be downloaded each time the Check Replies request is made. See Section 7.10 for details on confirming replies.
<origin> This element specifies the phone number of the sender of the reply message.
<received> This attribute specifies the date and time at which the gateway received the reply message and is specified in the standard XML schema dateTime format. The format of the dateTime data type is described in detail here and here. The received date and time is always specified in UTC.Briefly, the content of this element is specified in the format “YYYY-MM-DDThh:mm:ssZ” where:• YYYY indicates the year
• MM indicates the month
• DD indicates the day
• T indicates the start of the required time section
• hh indicates the hour
• mm indicates the minute
• ss indicates the second
• Z indicates the UTC time zone
 <content> This element specifies the content of the reply message.

1.8 CHECK REPORTS REQUEST
Table 1.7.2.1: Explanation of Check Replies Response Format
The Check Reports request is used to download delivery reports that are waiting on the gateway. Delivery reports are downloaded for a specific user account. A delivery report reports the delivery status of a sent message. Delivery reports may only be obtained for SMS messages not voice messages and must be requested explicitly in the Send Messages request (Section 7.4).

Delivery reports will remain marked as unsent and will be downloaded each time the Check Reports request is made until they are confirmed by the user as having been received.  See Section 7.12 for details on confirming reports.

1.8.1 FORMAT OF THE CHECK REPORTS REQUEST

Listing 1.8.1.1 shows an example Check Reports request.

<checkReports xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<maximumReports>100</maximumReports>
</requestBody>
</checkReports>

Listing 7.8.1.1: Example Check Reports Request

1.8.2 EXPLANATION OF THE CHECK REPORTS REQUEST FORMAT

<checkReports> The root element of the Check Reports request.
xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace..
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the optional maximumReplies element.
<maximumReports> (Optional) This element is used to specify the maximum number of delivery reports to download in the response. If this element is not specified all waiting delivery reports will be downloaded in the response.


1.9 CHECK REPORTS RESPONSE

The Check Reports response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Check Reports request. The response contains a list of unconfirmed delivery reports waiting on the gateway. If the maximumReports element was specified in the request then the value of that element will determine the maximum number of delivery reports present in the response. If no maximum was specified all unconfirmed delivery reports will be present in the response.

1.9.1 FORMAT OF THE CHECK REPORTS RESPONSE

Listing 1.9.1.1 shows an example Check Reports response.

<checkReportsResponse xmlns=”http://xml.m4u.com.au/2009″>
<result returned=”4″ remaining=”0″>
<reports>
<report uid=”1″ receiptId=”1351″ status=”delivered”>
<recipient>61400000001</recipient>
<timestamp>2009-10-08T15:31:21Z</timestamp>
</report>
<report uid=”2″ receiptId=”1352″ status=”delivered”>
<recipient>61400000002</recipient>
<timestamp>2009-10-08T15:31:22Z</timestamp>
</report>
<report uid=”3″ receiptId=”1353″ status=”pending”>
<recipient>61400000003</recipient>
<timestamp>2009-10-08T15:31:23Z</timestamp>
</report>
<report uid=”4″ receiptId=”1354″ status=”failed”>
<recipient>61400000004</recipient>
<timestamp>2009-10-08T15:31:24Z</timestamp>
</report>
</reports>
</result>
</checkReportsResponse>

Listing 1.9.1.1: Example Check Reports Response

Delivery reports indicate the delivery status of a previously sent SMS message. The status attribute or the report element defines this status. Table 7.9.1.1 describes the possible values that this attribute may assume and what each of these statuses indicate.

Value of the status Element Description
delivered The message was delivered to the recipient successfully. The timestamp element indicates the date and time (in UTC) that the message was delivered to the recipient’s handset.
pending The message is pending delivery. Some service providers send this delivery status when the message is delivered to their network and then send the delivered status when the message is delivered to the handset. For example, if the recipient’s handset is switched off some providers will first send this status and then send the delivered status when the recipient’s handset is turned on and the message is delivered. The timestamp element indicates the date and time (in UTC) that the message was delivered to the service provider’s network.
failed the message could not be delivered within the message’s validity period (for example, the recipient’s phone was switched off for an extended period).

Table 1.9.1.1: Delivery Status Descriptions

1.9.2 EXPLANATION OF THE CHECK REPORTS RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Check Reports response. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Check Reports response see the Check Reports response XML schema provided in Appendix A.8.

<checkReportsResponse> The root element of the Check Reports response.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This element provides attributes which summarise the result of the Check Reports request. It contains a list containing any downloaded delivery reports.
returned This attribute specifies the number of delivery reports returned in the response.
remaining This attribute specifies the number of delivery reports remaining on the gateway for the user.
<reports> This element contains any delivery report downloaded from the gateway. It will contain zero or more report elements. The delivery reports are listed in ascending order of their timestamp.
<report> (Optional) This element is used to specify a single delivery report.
uid This attribute specifies the unique user-defined ID assigned to the message that this delivery report is in relation to. The value of this ID allows client applications to match delivery reports to outbound messages. If no uid was assigned to the outbound message this attribute will have a value of zero.
receiptId This attribute specifies a unique receipt ID. This ID is to be used by the client application when confirming receipt of the delivery report. Until delivery reports are confirmed they will be marked as unsent and will be downloaded each time the Check Reports request is made. See Section 7.12 for details on confirming delivery reports.
status This attribute specifies the status of the message that the delivery report is in relation to. The status of the message can be one of the following values:• delivered
• pending
• failed
• unknownThese values are described in Table 7.9.1.1.
<recipient> This element specifies the phone number of the message recipient that the delivery report is in relation to.
<timestamp> This attribute specifies a date and time in UTC. The delivery status of the message (i.e. the value of the status element) determines the meaning of this element. If the delivery status is equal to “delivered” then the timestamp element indicates the date and time at which the message was received on the recipient’s handset. If the status is equal to “pending” then the timestamp is equal to the date and time at which the message was received by the recipient’s service provider’s network. If the status is equal to “failed” then the timestamp is equal to the date and time at which the message was deemed failed by the recipient’s service provider.This element is specified in the standard XML schema dateTime format. The format of the dateTime data type is described in detail here and here. The value of this element is always specified in UTC.Briefly, the content of this element is specified in the format “YYYY-MM-DDThh:mm:ssZ” where:• YYYY indicates the year
• MM indicates the month
• DD indicates the day
• T indicates the start of the required time section
• hh indicates the hour
• mm indicates the minute
• ss indicates the second
• Z indicates the UTC time zone

Table 1.9.2.1: Explanation of Check Reports Response Format

1.10 CONFIRM REPLIES REQUEST

The Confirm Replies request is used to confirm the receipt of reply messages that were downloaded from the gateway. Replies that are unconfirmed will be downloaded each time a Check Replies request is made. When reply messages are confirmed they are marked as sent and will not be downloaded again. It is not possible for a user to confirm replies that do not belong to them.

Reply messages must be confirmed on an individual basis. Replies are specified by their receipt ID. This receipt ID is the same receipt ID that the reply message was assigned in the Check Replies response. The receipt ID is specified by the attribute receiptId. See Section 7.7 for details on the Check Replies response.

1.10.1 FORMAT OF THE CONFIRM REPLIES REQUEST

Listing 1.10.1.1 shows an example Confirm Replies request.

<confirmReplies xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<replies>
<reply receiptId=”13067831″/>
<reply receiptId=”13067832″/>
<reply receiptId=”13067833″/>
<reply receiptId=”13067834″/>
<reply receiptId=”13067835″/>
</replies>
</requestBody>
</confirmReplies>

Listing 1.10.1.1: Example Confirm Replies Request

1.10.2 EXPLANATION OF THE CONFIRM REPLIES REQUEST FORMAT

This section provides an explanation of the elements and attributes that are used in the Confirm Replies request. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Confirm Replies request see the Confirm Replies request XML schema provided in Appendix A.9.

<confirmRepliesResponse> The root element of the Confirm Replies request.
xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the list of reply messages to confirm.
<replies> This element contains one or more reply elements.
<reply> This element is used to specify a single reply message to be confirmed as having been received. This element contains no content. It specifies the reply message to confirm via its receiptId attribute.
receiptId This attribute specifies the receipt ID of the reply message to confirm. The receipt ID must be the same receipt ID that was provided to the client application in the Check Replies response. It is not possible for a user to confirm replies that do not belong to them. See Section 7.7 for details on the Check Replies response.


1.11 CONFIRM REPLIES RESPONSE

The Confirm Replies response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Confirm Replies request. The response reports the number of reply messages that were confirmed.

1.11.1 FORMAT OF THE CONFIRM REPLIES RESPONSE

Listing 1.11.1.1 shows an example Confirm Replies response.

<confirmRepliesResponse xmlns=”http://xml.m4u.com.au/2009″>
<result confirmed=”5″/>
</confirmRepliesResponse>

Listing 1.11.1.1: Example Confirm Replies Response

1.11.2 EXPLANATION OF THE CONFIRM REPLIES RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Confirm Replies response. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Confirm Replies response see the Confirm Replies response XML schema provided in Appendix A.4.

<confirmRepliesResponse> The root element of the Confirm Replies response.
<result> This element provides an attribute which specifies the number of replies confirmed.
confirmed This attribute specifies the total number of replies that were confirmed by the request. Only replies that belong to the user can be confirmed. If erroneous receipt IDs were specified in the request they will not be included in this total.

1.12 CONFIRM REPORTS REQUEST

The Confirm Reports request is used to confirm the receipt of delivery reports that were downloaded from the gateway. Delivery reports that are unconfirmed will be downloaded each time a Check Reports request is made. When delivery reports are confirmed they are marked as sent and will not be downloaded again. It is not possible for a user to confirm delivery reports that do not belong to them.
Delivery reports must be confirmed on an individual basis. Delivery reports are specified by their receipt ID. This receipt ID is the same receipt ID that the delivery report was assigned in the Check Reports response. The receipt ID is specified by the attribute receiptId. See Section 7.9 for details on the Check Reports response.

1.12.1 FORMAT OF THE CONFIRM REPORTS REQUEST

Listing 1.12.1.1 shows an example Check Reports request.

<confirmReports xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<reports>
<report receiptId=”1351″/>
<report receiptId=”1352″/>
<report receiptId=”1353″/>
<report receiptId=”1354″/>
<report receiptId=”1355″/>
</reports>
</requestBody>
</confirmReports>

Listing 1.12.1.1: Example Confirm Reports Request

1.12.2 EXPLANATION OF THE CONFIRM REPORTS REQUEST FORMAT

 

This section provides an explanation of the elements and attributes that are used in the Confirm Reports request. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Confirm Reports request see the Confirm Reports request XML schema provided in Appendix A.11.

<confirmReports> The root element of the Confirm Reports request.
xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the list of delivery reports to confirm.
<reports> This element contains one or more report elements.
<report> This element is used to specify a single delivery report to be confirmed as having been received. This element contains no content. It specifies the delivery report to confirm via its receiptId attribute.
receiptId This attribute specifies the receipt ID of the delivery report to confirm. The receipt ID must be the same receipt ID that was provided to the client application in the Check Reports response. It is not possible for a user to confirm delivery reports that do not belong to them. See Section 7.9 for details on the Check Reports response.

Table 1.12.2.1: Explanation of Confirm Reports Request Format


1.13 CONFIRM REPORTS RESPONSE

The Confirm Reports response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Confirm Reports request. The response reports the number of delivery reports that were confirmed.

1.13.1 FORMAT OF THE CONFIRM REPORTS RESPONSE

Listing 7.13.1.1 shows an example Confirm Reports response.

<confirmReportsResponse xmlns=”http://xml.m4u.com.au/2009″>
<result confirmed=”5″/>
</confirmReportsResponse>

Listing 1.13.1.1: Example Confirm Reports Response

1.13.2 EXPLANATION OF THE CONFIRM REPLIES RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Confirm Reports response. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Confirm Reports response see the Confirm Reports response XML schema provided in Appendix A.12.

<confirmReportsResponse> The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace..
xmlns The user ID or password was invalid.
<result> This element provides an attribute which specifies the number of delivery reports confirmed.
confirmed This attribute specifies the total number of delivery reports that were confirmed by the request. Only reports that belong to the user can be confirmed. If erroneous receipt IDs were specified in the request they will not be included in this total

1.14 DELETE SCHEDULED MESSAGES REQUEST

The Delete Scheduled Messages request is used to request the unscheduling of messages that have been submitted to the gateway but are still yet to be sent. Only messages that were given a scheduled timestamp in the Send Messages request can be unscheduled. Only messages sent from the given account can be unscheduled. Messages submitted to the gateway via other APIs may be deleted via this method.

Messages must be confirmed on an individual basis. Messages are specified by their message ID. This message ID is the same message ID that was specified in recipient uid attribute in the Send Messages request. Messages with an unrecognised message ID will be ignored. See Section 7.4 for details on the Send Messages request.

1.14.1 FORMAT OF THE DELETE SCHEDULED MESSAGES REQUEST

Listing 1.14.1.1 shows an example Delete Scheduled Messages request.

<deleteScheduledMessages xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<messages>
<message messageId=”1351″/>
<message messageId=”1353″/>
<message messageId=”1354″/>
</messages>
</requestBody>
</deleteScheduledMessages>

Listing 17.14.1.1: Example Confirm Reports Request

1.14.2 EXPLANATION OF THE DELETE SCHEDULED MESSAGES REQUEST FORMAT

This section provides an explanation of the elements and attributes that are used in the Delete Scheduled Messages request. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Delete Scheduled Messages request see the Delete Scheduled Messages request XML schema provided in Appendix A.13.

<deleteScheduledMessages> The root element of the Delete Scheduled Messages request.
xmlns The XML namespace attribute. This value of this attribute must always be “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the list of messages to unschedule.
<messages> This element contains one or more message elements.
<message> This element is used to specify a single message to be deleted from the scheduled send queue. This element contains no content. It specifies the message to delete via its messageId attribute.
messageId This attribute specifies the message ID of the message to unschedule. The message ID must be the same message ID that was specified in the Send Messages request. It is not possible for a user to delete messages that do not belong to them. See Section 7.4 for details on the Send Messages request.


1.15 DELETE SCHEDULED MESSAGES RESPONSE

The Delete Scheduled Messages response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Delete Scheduled Messages request. The response reports the number of messages that were unscheduled.

1.15.1 FORMAT OF THE DELETE SCHEDULED MESSAGES RESPONSE

Listing 1.15.1.1 shows an example Delete Scheduled Messages response.

<deleteScheduledMessagesResponse xmlns=”http://xml.m4u.com.au/2009″>
<result unscheduled=”3″/>
</deleteScheduledMessagesResponse>

Listing 1.15.1.1: Example Delete Scheduled Messages Response

1.15.2 EXPLANATION OF THE DELETE SCHEDULED MESSAGES RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Delete Scheduled Messages response. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Delete Scheduled Messages response see the Delete Scheduled Messages response XML schema provided in Appendix A.14.

<deleteScheduledMessagesResponse> The root element of the Delete Scheduled Messages response.
Xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This element provides an attribute which specifies the number of messages deleted.
unscheduled This attribute specifies the total number of messages that were deleted by the request. Only messages that belong to the user can be deleted. If erroneous messageIDs were specified in the request they will not be included in this total.

1.16 BLOCK NUMBERS REQUEST

The Block Numbers request is used to prevent the authenticated account being able to send messages to the specified numbers in future.

1.16.1 FORMAT OF THE BLOCK NUMBERS REQUEST

Listing 1.16.1.1 shows an example Block Numbers request.

<blockNumbers xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<recipients>
<recipient uid=”1″>61410000001</recipient>
<recipient uid=”2″>61410000002</recipient>
<recipient uid=”3″>61410000003</recipient>
<recipient uid=”4″>61410000004</recipient>
</recipients>
</requestBody>
</blockNumbers>

1.16.2 EXPLANATION OF THE BLOCK NUMBERS REQUEST FORMAT

 

This section provides an explanation of the elements and attributes that are used in the Block Numbers request. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Block Numbers request see the Block Numbers request XML schema provided in Appendix A.15.

<blockNumbers> The root element of the Block Numbers request.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the list of recipients to block.
<recipients> This element contains the one or more recipient elements.
<recipient> This element specifies a recipient block.
uid (Optional) This attribute specifies a user-defined unique ID that is a assigned to the recipient. The UID is an unsigned integer the uniqely identifies the recipient for a given Block Numbers request.uid values are used to report which recipients failed to be blocked in the Block Numbers response.If no uid value is specified a default value of zero is assigned.

Table 1.16.2.1: Explanation of Block Numbers Request Format

1.17 BLOCK NUMBERS RESPONSE

The Block Numbers response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Block Numbers request. The response provides a summary of the result of the request, including a list of any recipients that could not be blocked.

1.17.1 FORMAT OF THE BLOCK NUMBERS RESPONSE

Listing 1.17.1.1 shows an example Block Numbers response

<blockNumbersResponse xmlns=”http://xml.m4u.com.au/2009″>
<result blocked=”2″ failed=”2″>
<errors>
<error code=”invalidRecipient” sequenceNumber=”0″>
<recipients>
<recipient uid=”1″>61410000001</recipient>
<recipient uid=”2″>61410000002</recipient>
</recipients>
</error>
</errors>
</result>
</blockNumbersResponse>

Listing 1.17.1.1: Example Block Numbers Response

1.17.2 EXPLANATION OF THE BLOCK NUMBERS RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Block Numbers response. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Block Numbers response see the Block Numbers response XML schema provided in Appendix A.16.

<blockNumbersResponse> The root element of the Block Numbers response.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This attributes of this element provide a summary of the result of the Send Messages request. It contains the accountDetails element as well as an errors element if any errors occurred.
blocked This attribute specifies the number of recipients that were successfully added to the block list.
failed This attribute specifies the number of recipients that could not be added to the block list. If this number is greater than 0 the errors element will be present inside the result element and it will contain errors pertaining to each of the affected recipients.
<errors> (Optional) This element contains errors that occurred during the processing of the request and will be present only if errors occurred. If this element is present it will contain one or more error elements. This element will only be present if the failed attribute of the parent result element reports a value greater than 0. The total number of affected recipients reported by all error elements will be equal to the value of the failed attribute.
<error> This element reports an error that occurred in the processing of the request.
code This attribute specifies the error code of the error. The error code defines the type of error and is one of the values specified in Table 7.5.1.1.The error codes that may result from a Block Numbers request are: invalidRecipient and other.
sequenceNumber This attribute attribute is not used, and will always be zero.
<recipients> This element contains one or more recipient elements.
<recipient> This element specifies the recipient who was affected by the error and as such was not blocked.
uid This attribute specifies the user-defined unique ID that was assigned to the recipient in the request. For this reason unique values should be used so that the affected message-recipient can be correctly identified. If the uid was not specified in the request the value of this attribute will be zero.

1.18 UNBLOCK NUMBERS REQUEST

The Unblock Numbers request is used to remove existing number blocks.

1.18.1 FORMAT OF THE UNBLOCK NUMBERS REQUEST

Listing 1.18.1.1 shows an example Unblock Numbers request.

<unblockNumbers xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<recipients>
<recipient uid=”1″>61410000001</recipient>
<recipient uid=”2″>61410000002</recipient>
<recipient uid=”3″>61410000003</recipient>
<recipient uid=”4″>61410000004</recipient>
</recipients>
</requestBody>
</unblockNumbers>
Listing 1.18.1.1: Example Unblock Numbers Request

1.18.2 EXPLANATION OF THE UNBLOCK NUMBERS REQUEST FORMAT

This section provides an explanation of the elements and attributes that are used in the Unblock Numbers request. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Unblock Numbers request see the Unblock Numbers request XML schema provided in Appendix A.17.

<unblockNumbers> The root element of the Unblock Numbers request.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the list of recipients to unblock.
<recipients> This element contains the one or more recipient elements.
<recipient> This element specifies a recipient unblock.
uid (Optional) This attribute specifies a user-defined unique ID that is a assigned to the recipient. The UID is an unsigned integer the uniqely identifies the recipient for a given Block Numbers request.uid values are used to report which recipients failed to be unblocked in the Unblock Numbers response.If no uid value is specified a default value of zero is assigned.

Table 1.18.2.1: Explanation of Unblock Numbers request Format

1.19 UNBLOCK NUMBERS RESPONSE

The Unblock Numbers response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Unblock Numbers request. The response provides a summary of the result of the request, including a list of any recipients that could not be unblocked.

1.19.1 FORMAT OF THE UNBLOCK NUMBERS RESPONSE

Listing 1.19.1.1 shows an example Unblock Numbers response.

<unblockNumbersResponse xmlns=”http://xml.m4u.com.au/2009″>
<result unblocked=”2″ failed=”2″>
<errors>
<error code=”invalidRecipient” sequenceNumber=”0″>
<recipients>
<recipient uid=”1″>61410000001</recipient>
<recipient uid=”2″>61410000002</recipient>
</recipients>
</error>
</errors>
</result>
</unblockNumbersResponse>
Listing 1.19.1.1: Example Unblock Numbers Response

1.19.2 EXPLANATION OF THE UNBLOCK NUMBERS RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Unblock Numbers response. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Unblock Numbers response see the Unblock Numbers response XML schema provided in Appendix A.18.

<unblockNumbersResponse> The root element of the Unblock Numbers response
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This attributes of this element provide a summary of the result of the Send Messages request. It contains the accountDetails element as well as an errors element if any errors occurred.
unblocked This attribute specifies the number of recipients that were successfully added to the block list.
failed This attribute specifies the number of recipients that could not be removed from the block list. If this number is greater than 0 the errors element will be present inside the result element and it will contain errors pertaining to each of the affected recipients.
<errors> (Optional) This element contains errors that occurred during the processing of the request and will be present only if errors occurred. If this element is present it will contain one or more error elements. This element will only be present if the failed attribute of the parent result element reports a value greater than 0. The total number of affected recipients reported by all error elements will be equal to the value of the failed attribute.
<error> This element reports an error that occurred in the processing of the request.
code This attribute specifies the error code of the error. The error code defines the type of error and is one of the values specified in Table 7.5.1.1.The error codes that may result from an Unblock Numbers request are: invalidRecipient and other.
sequenceNumber This attribute attribute is not used, and will always be zero
<recipients> This element contains one or more recipient elements.
<recipient> This element specifies the recipient who was affected by the error and as such was not unblocked.
uid This attribute specifies the user-defined unique ID that was assigned to the recipient in the request. For this reason unique values should be used so that the affected message-recipient can be correctly identified. If the uid was not specified in the request the value of this attribute will be zero.

Table 1.19.2.1: Explanation of Unblock Numbers Response Format

1.20 GET BLOCKED NUMBERS REQUEST

The Get Blocked Numbers request is used retrieve a list of numbers that are currently blocked for the authenticated account.

1.20.1 FORMAT OF THE GET BLOCKED NUMBERS REQUEST

Listing 1.20.1.1 shows an example Get Blocked Numbers request.

<getBlockedNumbers xmlns=”http://xml.m4u.com.au/2009″>
<authentication>
<userId>Username</userId>
<password>Password</password>
</authentication>
<requestBody>
<maximumRecipients>50</maximumRecipients>
</requestBody>
</getBlockedNumbers>

Listing 1.20.1.1: Example Get Blocked Numbers Request

1.20.2 EXPLANATION OF THE GET BLOCKED NUMBERS REQUEST FORMAT

This section provides an explanation of the elements and attributes that are used in the Get Blocked Numbers request. Element names are specified in bold and written as . Attribute names are specified in bold and written as attribute. For a definitive specification of the Get Blocked Numbers request see the Get Blocked Numbers request XML schema provided in Appendix A.19.

<getBlockedNumbers> The root element of the Get Blocked Numbers request.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<authentication> This element contains userId and password elements which are required to authenticate the user.
<userId> This element specifies the user ID which, in conjunction with the password, is required to authenticate the user. The user ID is the account name that the user is assigned by MessageMedia.
<password> This element specifies the password of the user which is used for authentication.
<requestBody> This element contains the list of recipients to unblock.
<maximumRecipients> (Optional) This element is used to specify the maximum number of blocked numbers to include in the response. If this element is not specified all blocked numbers will be included in the response.

Table 1.20.2.1: Explanation of Get Blocked Numbers Request Format

1.21 GET BLOCKED NUMBERS RESPONSE

The Get Blocked Numbers response is returned by the MessageMedia Messaging Web Service in response to a valid, authenticated Get Blocked Numbers request. The response provides a list of numbers currently blocked for the authenticated account.

1.21.1 FORMAT OF THE GET BLOCKED NUMBERS RESPONSE

Listing 1.21.1.1 shows an example Get Bocked Numbers response.

<getBlockedNumbersResponse xmlns=”http://xml.m4u.com.au/2009″>
<result found=”4″ returned=”4″>
<recipients>
<recipient uid=”0″>61410000001</recipient>
<recipient uid=”0″>61410000002</recipient>
<recipient uid=”0″>61410000003</recipient>
<recipient uid=”0″>61410000004</recipient>
</recipients>
</result>
</getBlockedNumbersResponse>

Listing 1.21.1.1: Example Get Blocked Numbers Response

1.21.2 EXPLANATION OF THE GET BLOCKED NUMBERS RESPONSE FORMAT

This section provides an explanation of the elements and attributes that are used in the Get Blocked Numbers response. Element names are specified in bold and written as <element>. Attribute names are specified in bold and written as attribute. For a definitive specification of the Get Blocked Numbers response see the Get Blocked Numbers response XML schema provided in Appendix A.20.

<getBlockedNumbersResponse> The root element of the Get Blocked Numbers response.
xmlns The XML namespace attribute. This value of this attribute is always “http://xml.m4u.com.au/2009” as this is the target namespace.
<result> This attributes of this element provide a summary of the result of the Send Messages request. It contains the accountDetails element as well as an errors element if any errors occurred.
found This attribute specifies the number of recipients that were found to be blocked for the authenticated account.
returned This attribute specifies the number of recipients that are included in this response, that is in the recipients element.This number will be the the smallest of the found attribute value and the maxiumumRecipients value (if any) specified in the Get Blocked Numbers request that this result is in response to.
<recipients> This element contains one or more recipient elements
<recipient> This element specifies the recipient that is on the block list.
uid This attribute attribute is not used, and will always be zero.

Table 7.21.2.1: Explanation of Get Blocked Numbers Response Format