UK SMS HTTP
Important: The information and contents displayed in these pages is for the OpenMarket's legacy UK SMS APIs. This information is relevant if only you're still using these APIs. For information on migrating from these APIs, see the API Release Notes. Please note, however, that Reporting is still done through Partner Centre, located here: https://partner.mxtelecom.com/home.
Delivery reports provide feedback to applications concerning the delivery of MT messages. This information can include:
- Confirmation of successful billing for premium messages
- Confirmation of successful delivery to the handset (where this is supported by the mobile operator)
- Details of errors which prevented successful delivery
Enabling receipt of delivery reports
In order to receive delivery reports, two steps are necessary. Firstly, delivery reports must be requested when the corresponding MT message is submitted to OpenMarket:
- HTTP interface: via the report parameter.
- SMPP interface: via the registered_delivery parameter in the DELIVER_SM PDU.
Secondly, delivery reports must be routed to an HTTP URL of your choosing or via your SMPP connection. This routing is configured on a per-account basis; please contact us to have this routing configured or altered.
Interpreting delivery reports
A delivery report contains the following:
- The SMS ID of the MT message. This is a positive 64-bit integer used to uniquely identify an SMS message as it passes through OpenMarket's systems. As well as when sending delivery reports, OpenMarket will pass on this ID in the response back to a submitted SMS message and when delivering Mobile Originated SMS messages.
- A date, giving the time at which the delivery event occurred.
- A delivery report type code giving an overview of the delivery status of the message. This can be one of DELIVERED, FAILED, BUFFERED, or REJECTED and corresponds to the Type nibble in the detailed reason code.
- A detailed reason code, giving further information on the reason for the delivery report. This is a 4-byte integer.
Types of delivery report
OpenMarket my return the following delivery report types.
|
Type |
Description |
|---|---|
| REJECTED |
If a message or billing request is not accepted by the operator, OpenMarket may make several more attempts to submit the message, according to a retry strategy. If the message still has not been accepted once the retry strategy is complete (or immediately, in the case of permanent errors such as invalid destination), a REJECTED report is returned. |
| BUFFERED |
Buffered means that the message has reached a particular stage in its processing. It is not final confirmation of delivery OR failure (although they are sometimes used to confirm billing has been successful). |
| FAILED |
Failed means that the message has been failed after it was submitted to the mobile operator for delivery. |
| DELIVERED | Delivered means that the message has been successfully delivered to the handset, including billing the subscriber where this is separate. |
Detailed reason codes
The detailed reason code gives more information about the reason for the delivery notification, such as the error which prevented delivery of a message, whether billing has been successful, and so on.
The four bytes making up the reason code can be broken down as follows.
Byte one
| Most significant byte | |||
|---|---|---|---|
| Type nibble | Billing nibble | ||
| 0x1 | REJECTED | 0x0 | See below |
| 0x3 | BUFFERED | 0x1 | Post billing |
| 0x5 | FAILED | 0x2 | New subscription |
| 0x6 | DELIVERED | 0x4 | Message submitted |
The Type nibble corresponds directly to the delivery report type. Values other than those defined in the table are reserved, and applications should ignore any delivery reports with an unrecognised type.
The Billing nibble is a bitmask which gives information on the billing status of a premium message.
- The billing nibble may be set to 1 on REJECTED, BUFFERED or FAILED reports to indicate that the subscriber has been successfully charged, even though the message contents themselves may not have been delivered. The billing nibble will never be set to 1 when a message is billed using an operator-managed subscription (see below).
- The billing nibble may be set to 2 on any kind of report (including DELIVERED reports) to indicate that a new operator-managed subscription mandate was created while attempting to deliver the message, and the subscriber has been successfully charged. This is only set if the operator manages the subscription themselves.
- The billing nibble may be set to 4 on a REJECTED or FAILED report to indicate that although the billing transaction failed, the message was submitted to the operator for delivery. This will only happen with operators where billing happens after submission, indicating that although the message was sent to the subscriber, the subscriber could not be subsequently billed.
- On a REJECTED, BUFFERED or FAILED report, if neither the post-billing nor the new subscription bit is set, it indicates that the subscriber has not been charged. Note that, for historical reasons, the post-billing nibble is not always set on DELIVERED reports; however a DELIVERED report for a premium MT message always implies that the subscriber has been successfully charged.
Byte two & three
| Reason byte 1 | Reason byte 2 |
|---|---|
| Varies according to type | |
The Reason bytes give more detail on the reason for the delivery notification. Their meaning varies according to the type of report; see the tables below for further information.
Byte four
| Operator byte | |
|---|---|
| 0x00 | No information |
| 0x10 | On net |
| 0x11 | Virgin Mobile UK |
| 0x12 | MVNO |
| 0x20 | Alltel user ported to Verizon |
The Operator byte gives information on the operator of the subscriber. In most cases, this is not available, and this byte will be set to zero; however on some operators, the message-submission interface returns an indication of whether the subscriber was "on-net" or on a virtual operator. In this case, the Operator byte will be set to 0x10 for "on-net", 0x11 if the subscriber was on Virgin Mobile UK, or 0x12 if the subscriber was on an unknown MVNO. Other values are reserved for other MVNOs and applications should treat unrecognised values in the same way as a value of 0x00.
Reason byte tables
The following tables define the possible values for the Reason bytes within the delivery report reason code. The Billing nibble and Operator byte do not form part of this interpretation, so are represented by the character ‘.’ to indicate that they may take any value.
Reason bytes which are not defined in the tables below are reserved for future expansion. REJECTED and FAILED delivery reports are divided into groups, and thus if an application receives a reason code which it does not understand, it should ignore the less significant parts of the reason code and look for a reason code group which is recognised. In any case, the Type and Billing Nibbles alone will normally provide enough information for correct operation of applications.
0x1....... - REJECTED
For REJECTED delivery reports, the reason bytes give more information on why the message was not accepted by the operator. The table below defines the possible values for the reason bytes, and also documents the retry strategy which will have been used to resubmit the message to the operator before giving up and returning the REJECTED delivery report.
| Hexadecimal reason code | Symbolic name | Description | Notes |
|---|---|---|---|
| 0x1.0000.. | REASON_REJECTED | Unknown error |
An unexpected error occurred during delivery, where we cannot differentiate between a system failure (some part of system not functioning correctly) and an expected failure (unknown subscriber, etc). Retry strategy: General |
| 0x1.0004.. | REASON_REJECTED_EXPIRED | Message expired |
The message exceeded its validity period before a delivery attempt could be made. Retry strategy: Fail |
| 0x1.010... |
Reason code group: generic billing error A group of billing-related errors which do not fit into any of the other billing groups below. |
||
| 0x1.0100.. | REASON_REJECTED_BILLING | Billing failed (generic) |
An unexpected error occurred during billing, where we cannot differentiate between a system failure (some part of system not functioning correctly) and an expected failure (subscriber out of credit, etc). Retry strategy: Billing |
| 0x1.0101.. |
REASON_REJECTED_BILLING _PREPAYUNSUP |
Prepay billing unsupported |
Billing of prepay subscribers is not supported on this mobile operator. Retry strategy: Fail |
| 0x1.0102.. |
REASON_REJECTED_BILLING _PSMSBARRED |
MT charge barred (generic) |
Charges to this subscriber have been barred - no further information available from mobile operator. Retry strategy: Fail |
| 0x1.011... |
Reason code group: charge failed A group of billing-related errors: this particular charge has been rejected, but the subscriber is still billable. |
||
| 0x1.0110.. |
REASON_REJECTED_BILLING _CHARGEFAILED |
Charge failed |
This charge has been rejected by the mobile operator. Used where none of the reasons below apply, but we believe that the subscriber is still billable (unlike REASON_REJECTED_BILLING_PSMSBARRED). Retry strategy: Fail |
| 0x1.0112.. |
REASON_REJECTED_BILLING _MANDATE_TERMINATED |
Subscription billing mandate has been terminated |
A previously-active subscription billing mandate has now terminated. No further billing should be performed under this subscription. Retry strategy: Fail |
| 0x1.0113.. |
REASON_REJECTED_BILLING _MANDATE_EXCEEDED |
Charge exceeds terms of subscription billing mandate |
This charge exceeds the terms (eg, monthly limit) of a subscription billing mandate. Retry strategy: Fail |
| 0x1.012... |
Reason code group: credit control A group of billing-related errors: subscriber has reached a credit/spending limit. |
||
| 0x1.0120.. |
REASON_REJECTED_BILLING _SPENDCAP_OR_ OUTOFCREDIT |
Over spend limit or out of credit |
Subscriber has reached a spending limit, or is out of credit. Used when we cannot distinguish which. Retry strategy: Billing |
| 0x1.0121.. |
REASON_REJECTED_BILLING _SPENDCAP |
Subscriber has reached spending limit |
Subscriber has reached a spending limit (eg, monthly spend cap). Retry strategy: Billing |
| 0x1.0122.. |
REASON_REJECTED_BILLING _OUTOFCREDIT |
Subscriber out of credit |
Subscriber has exceeded their credit limit. This is specific to limits which can be resolved by the subscriber adding credit to their account. Note that this may apply to either pre or postpay subscribers. Retry strategy: Billing |
| 0x1.013... | Reason code group: problem billing subscriber account A group of billing-related errors: there is a problem billing this subscriber. |
||
| 0x1.0131.. |
REASON_REJECTED_BILLING _ACCOUNT_CLOSED |
Account closed |
Attempt to bill against a closed account. This subscriber should not be billed further. Retry strategy: Fail |
| 0x1.0132.. |
REASON_REJECTED_BILLING _ACCOUNT_LOCKED |
Account locked |
Attempt to bill against a locked/suspended account. Retry strategy: Fail |
| 0x1.0133.. |
REASON_REJECTED_BILLING _BARRED_RESELLER |
Billing barred (reseller settings) |
Subscriber obtains connectivity via a reseller; billing of this subscriber is therefore barred. Retry strategy: Fail |
| 0x1.0134.. |
REASON_REJECTED_BILLING _BARRED_ADULT |
Billing barred (adult) |
Adult settings on subscriber account prevent billing of subscriber. Retry strategy: Fail |
| 0x1.02.... |
Reason code group: source A group of error codes indicating there was a problem with the message originator. |
||
| 0x1.0200.. |
REASON_REJECTED _SOURCE |
Invalid source address |
Originator on this message was invalid. Retry strategy: Fail |
| 0x1.0201.. |
REASON_REJECTED _SOURCE_NOTPROVISIONED |
Provisioning error |
Short code has not been provisioned. Contact OpenMarket support. Retry strategy: General |
| 0x1.0202.. |
REASON_REJECTED _SOURCE_NOTPROVISIONEDTESTONLY |
Provisioned for testing only |
An attempt was made to send a message to an non-whitelisted number from a short code which has only been provisioned for testing. Retry strategy: Fail |
| 0x1.03.... |
Reason code group: destination temporary A group of error codes indicating a non-permanent problem with the destination (later traffic to this destination may succeed). |
||
| 0x1.0300.. |
REASON_REJECTED _DESTTEMP |
Invalid destination |
Temporary delivery problem to the destination. Retry strategy: Fail |
| 0x1.0301.. |
REASON_REJECTED _DESTTEMP_BARRED |
Barred |
Temporary bar on delivery of this content to the destination. Retry strategy: Fail |
| 0x1.0302.. |
REASON_REJECTED _DESTTEMP_SIMFULL |
SIM full |
Message could not be delivered as handset message memory is full. Retry strategy: Fail |
| 0x1.0303.. |
REASON_REJECTED _DESTTEMP_ABSENT |
Subscriber absent |
Message could not be delivered as handset is absent from the mobile operator. Retry strategy: Fail |
| 0x1.0304.. |
REASON_REJECTED _DESTTEMP_DELIVFAIL |
Delivery failed |
Temporary delivery problem to the destination. Retry strategy: Fail |
| 0x1.040... | Reason code group: destination permanent. A group of error codes representing a permanent problem with the destination (destination should be removed from subscriber list). |
||
| 0x1.0400.. |
REASON_REJECTED _DESTPERM |
Invalid destination |
Delivery to this subscriber has failed for an unknown reason. It may be due to a premium rate bar, so it may still be possible to deliver bulk or standard rate messages to this subscriber after failure of a premium message. Retry strategy: Fail |
| 0x1.0401.. |
REASON_REJECTED _DESTPERM_BARRED |
Barred |
Delivery to this subscriber has been barred. Retry strategy: Fail |
| 0x1.0402.. |
REASON_REJECTED _DESTPERM_NOSMS |
All SMS barred |
This subscriber cannot receive any SMS (premium rate, standard rate, or bulk) from any sender. Retry strategy: Fail |
| 0x1.0405.. |
REASON_REJECTED _DESTPERM_UNKNOWNSUB |
Unknown subscriber |
The destination of this message does not represent a known subscriber. For billing traffic, or traffic within the USA, this may be operator specific - i.e. the subscriber may be known by another operator. For non-USA bulk messages it means the number is invalid. Retry strategy: Fail |
| 0x1.0406.. |
REASON_REJECTED _DESTPERM_PORTED |
Ported off-net |
This subscriber is known to have ported off-net; delivery through this operator is no longer possible. Retry strategy: Fail |
| 0x1.0407.. |
REASON_REJECTED _DESTPERM_RESELLER |
Delivery barred (reseller settings) |
Subscriber obtains connectivity via a reseller; messaging to this subscriber is therefore barred. Retry strategy: Fail |
| 0x1.0408.. |
REASON_REJECTED _DESTPERM_MVNO |
Delivery barred (MVNO settings) |
Subscriber obtains connectivity via a virtual network (MVNO); messaging to this subscriber is therefore barred. Retry strategy: Fail |
| 0x1.05.... |
Reason code group: system error Group of errors representing an unexpected error when processing the message. |
||
| 0x1.0500.. |
REASON_REJECTED _SYSFAIL |
System error |
Some part of OpenMarket or the operator's systems are not functioning correctly. Contact OpenMarket support for more details. Retry strategy: General |
| 0x1.0501.. |
REASON_REJECTED _SYSFAIL_BILLING |
System error during billing |
As per REASON_REJECTED_SYSFAIL, for errors occurring during billing phase. Retry strategy: General |
| 0x1.06.... |
Reason code group: message A group of error codes representing a problem with the message content. |
||
| 0x1.0600.. | REASON_REJECTED_MSG | Bad message | Mobile operator rejected message contents. Used where we have no further information as to the problem with the contents. |
| 0x1.0601.. |
REASON_REJECTED_MSG _UNICODE |
Unicode not supported | Unicode (UCS2) messages are not supported on this mobile operator / short code. |
| 0x1.0602.. |
REASON_REJECTED_MSG _BINARY |
Binary not supported | Binary (8-bit) messages are not supported on this mobile operator / short code. |
| 0x1.0603.. |
REASON_REJECTED_MSG _OPTIN |
Invalid opt-in | Message could not be submitted to the mobile operator due to invalid opt-in details. |
| 0x1.0604.. | REASON_REJECTED_MSG_SPAM | Spam detected |
Spam detected. Retry strategy: Fail |
| 0x5.0604.. | REASON_FAILED_MSG_SPAM | Spam detected |
Message blocked due to spam. Retry strategy: Fail |
0x3....... - BUFFERED
BUFFERED reports indicate that a message has reached a particular stage in its processing; the reason bytes therefore describe what has just taken place.
| Hexadecimal reason code | Symbolic name | Description | Notes |
|---|---|---|---|
| 0x310002.. | REASON_BUFFERED | Buffered for unknown reason |
This reason code is returned when we receive a notification from the operator that they have been unable to deliver the message, but are continuing to retry. |
| 0x310001.. |
REASON_BUFFERED _BILLING_SUCCESSFUL |
Billing succeeded | Indicates that the message was successfully billed. Note that the Billing nibble will always be set to 1 with this reason code. |
| 0x3.0100.. |
REASON_BUFFERED _BILLING |
Buffered whilst awaiting a billing action | Buffered whilst awaiting a billing action. |
| 0x3.030... |
Reason code group: destination temporary Temporary delivery problem to the destination. |
||
| 0x3.0302.. |
REASON_BUFFERED _DESTTEMP_SIMFULL |
SIM full |
Message could not be delivered as handset message memory is full. |
| 0x3.0303.. |
REASON_BUFFERED _DESTTEMP_ABSENT |
Subscriber absent |
Message could not be delivered as handset is absent from the mobile operator. |
| 0x3.0304.. |
REASON_BUFFERED _DESTTEMP_DELIVFAIL |
Delivery failed |
Temporary delivery problem to the destination. |
0x5....... - FAILED
The reason bytes for FAILED delivery reports give more information on why the operator was unable to deliver the message after accepting it. The possible values are the same as those for REJECTED, except that they begin with 5 rather than 1. For instance, REASON_FAILED_DESTPERM is 0x50040000.
0x6....... - DELIVERED
The table below gives the reason bytes which can be associated with DELIVERED delivery reports. Note that, for historical reasons, the Billing nibble of DELIVERED reports may be set to zero; however, a DELIVERED report for a premium MT message always implies that the subscriber has been successfully charged.
| Hexadecimal reason code | Symbolic name | Description | Notes |
|---|---|---|---|
| 0x6.0000.. | REASON_DELIVERED | Message delivered to subscriber |
Message delivered to handset. |
| 0x620000.. |
REASON_DELIVERED_NEW _SUBSCRIPTION |
Delivered, with a new subscription initiated. | Message delivered to handset. As part of the billing process, a new operator-managed subscription billing mandate was created with the user's operator. |
| 0x6.0002.. |
REASON_DELIVERED _FAKEMT |
Fake MT message processed. | Control message (eg, STOP MT for subscription termination) has been processed. |
Examples
Below are some examples of reason codes, and their interpretations.
| Report type | Reason code (decimal) | Reason code (hexadeximal) | Symbolic name | Meaning |
|---|---|---|---|---|
| DELIVERED | 1610612736 | 0x60000000 | REASON_DELIVERED |
Delivered. |
| DELIVERED | 1610612752 | 0x60000010 | REASON_DELIVERED + 0x10 | Delivered and destination known on-net. |
| DELIVERED | 1610612753 | 0x60000011 | REASON_DELIVERED + 0x11 | Delivered to Virgin MVNO. |
| REJECTED | 268501248 | 0x10010100 |
REASON_REJECTED_BILLING _PREPAYUNSUP |
Rejected - prepay not supported. |
| FAILED | 1359151616 | 0x51030200 |
REASON_FAILED_DESTTEMP _SIMFULL + 0x01000000 |
Failed - SIM full, but post billing (i.e. subscriber was billed - if on net). |
| BUFFERED | 822083840 | 0x31000100 |
REASON_BUFFERED_BILLING _SUCCESSFUL + 0x01000000 |
Buffered - Message delivery state unknown as operator does not support handset delivery reports, but message successfully billed. |
Variations between operators
Not all operators support the same level of detail, and not all delivery report reason codes are therefore available on all operators. For instance, many US operators do not support handset delivery reports, in which case, REASON_DELIVERED would never be returned.