Delivery Reports

Overview

TextPower receives delivery reports on the messages it sends from US, Canadian and international carriers. Delivery reports can let you know which messages were received by the intended destination and give you information about why messages that you sent were not delivered.

Delivery reports are available via query using the TextPower APIs, from our customer portal site at https://customer.textpower.com or via POST to your own server.

Delivery Technical Data

There are wide differences in the data that individual carriers report for deliveries. TextPower attempts to standardize that data as much as possible but with several hundred possible failure codes among the 100+ carriers that TextPower supports, this is not feasible.

Delivery Reports consist of a numeric delivery code called a Reason Code and a textual Status Code.

Successful Delivery

There are two basic types of successful delivery reports depending upon the carrier.

  1. Carriers that can detect and verify delivery to the phone (the mobile device actually responds back to the carrier's network acknowledging that it was received). Successful delivery to these carriers is denoted by a Reason Code of 4 and a Status code of DELIVERED.
  2. Many carriers cannot or do not detect delivery to the phone. They report that the phone number is on their system and the message is queued on their system for delivery. Successful delivery to these carriers is denoted by a Reason Code of 6 and a Status Code of HP DELIVERED. HP DELIVERED stands for High Probability Delivered.

Unsuccessful Delivery 

There can be many reasons for unsuccessful delivery. Unfortunately there is no consistency among carriers as to either Reason Codes or Status Codes for unsuccessful delivery. In rough frequency of occurrence, the most common of these are:

  1. Number is not on the system of the carrier to which the message was sent. There are two possible reasons for this occurrence.
    1. The owner of the phone has changed to another carrier with the same phone number. TextPower detects these error messages and does an automatic lookup of the number. If it is now on a different carrier, the internally stored carrier code is changed and the message is resent with the Send Type field set to MSGRETRY. No further action is needed on the part of the TextPower customer.  In the vast majority of cases these messages are successfully delivered on the automated retry attempt that occurs after we lookup and verify the new carrier to which the number has been ported.
    2. The phone has simply disconnected and cannot be found on another carrier. No retry is sent but the TextPower customer needs to remove this number from their send lists.
  2. Number is not provisioned for SMS. Some carrier service plans do not include text messaging. The only thing that can be done about this is to get the phone owner to buy one.
  3. Short Code block: Particularly for business accounts, text messaging is provisioned but service to and from short codes is blocked. This can be reversed at no cost by the customer calling their carrier and asking that the Short Code block be removed.
  4. There are many other low frequency reasons for non-delivery that are not detailed here.

Capacity Issues with Posted Out Delivery Reports

Usually, delivery reports come in very quickly after the send. This could cause capacity problems with the TextPower customer’s server particularly when using TextPower’s bulk send capability. The current service level agreements TextPower has with its suppliers allow us to send messages at a rate of about 300/second in bulk configuration. By definition, this is rate that messages can be sent to you. If you elect to have delivery reports posted to your server, it must be capable of handling that rate. The TextPower servers can handle rates much larger than this. If reasonable service level agreements can be negotiated in the future, TextPower reserves the right to raise the delivery speed at any time without notice.

Technical Details of Delivery Reports

The TextPower customer must provide TextPower with a URL capable of handling POST data.  The POST parameters delivered to this URL will be:

Parameter Name

Data Type

Meaning

Campaign Name

String

The text name of the campaign that sent the message.

CampaignID

Integer

The unique numerical ID of the campaign that sent the message.

CellNumber

String

The cell number of the phone that the delivery status is being reported on.

ShortCode

String

The short code that the send went out on. For non-North American sends, short codes cannot be used and this data is meaningless.

ReasonCode

Integer

The Reason Code reported by the carrier.

Reason

String

The textual description of the report. This is the same as the Status Code referred to above.

SendID

Integer

The SendID of the message. (Always present)

QueueID

Integer

The QueueID of the message. QueueID is zero if the message was not queued.

DeferID

Integer

The DeferID of the message. DeferID is zero if the message was not sent as deferred.

TimeStamp

String

A string representation of the time of the report in the time zone of the TextPower customer. The time stamp is in the US format of MM/DD/YYYY HH:MM:SS.

Have more questions? Submit a request