Delivery Reports, Codes, Specifications and Notes

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 and can be delivered via POST to your own server.

This message delivery report code is compiled from various carriers, upstream aggregators, and other entities involved in the delivery of messages once they leave TextPower's control.  Messages are sent from us to various aggregators, depending on the necessary routing, and from there to carriers.  Some carriers report full delivery codes and others do not.  The file of all currently known delivery codes is available HERE.

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 on the carrier.

1. Carriers that can detect and verify delivery to the phone: 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. The 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.
   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. The 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. The number is a voice-over Internet protocol (VoIP) number, not an actual "landline" or mobile number.  Before we allow a number to opted in we check to see if it is a mobile number that can receive text messages.  If not, we do not allow it to be opted in.  The lookup process that all services like TextPower use to determine whether or not a number can receive text messages cannot definitively determine whether a VoIP number cannot receive a text because some VoIP numbers actually can.  As a result, those numbers are allowed to be opted in because the only way to determine with certainty whether that particular VoIP number can receive text messages is to send a message to it.  If it fails because that number doesn't allow text messaging it generates a specific error code (indicating it's a VoIP and therefore won't accept text messages).  Our system is programmed to then show the error in the MessageReports Sent Messages list and automatically opt out of that number.

4. The number may not be a true mobile number.  Here are ways that you can find out whether a number is truly a mobile number vs. a VoIP number or true non-mobile:

   1. When you upload a file of numbers each number is automatically checked to see if it is a mobile or non-mobile.  You can see a list of all numbers and their status (opted-in, opted-out, suspended, and non-mobile) by downloading the "Opt-in/Opt-out Report" in MessageReports.
   2. You can use our LookupCarrier API call.  For access to this call and documentation to support it please contact [e-mail] . 
   3. If you only want to check one number simply send a text message from any phone to short code 81888 - it does not have to be opted into any keywords on the TextPower system - with the word "lookup" followed by the phone number you are questioning.  For example, text "lookup 9995551212" and a reply text will be sent telling you whether that number is a cell phone number.

   There is no charge associated with either method (other than the possible charge for sending a text when using #2 - as with all text messages, message and data rates may apply).

5. 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.
6. There are many other low frequency reasons for non-delivery that are not detailed in the text of this FAQ but are available in the Reason Code table.

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. By definition, this is the rate which 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 shortcode that the send went out on. For non-North American sends, shortcodes 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.