This guide describes best practices that should be followed if you are sending SMS messages. In this guide you will learn what Deactivated Phone Numbers are, how to find out which phone numbers have been deactivated, and how to handle them.

What is a Deactivated Phone Number?

When a mobile subscriber either terminates their service or transfers their number to a different wireless carrier, this phone number is "deactivated" on their wireless carrier. These numbers eventually get recycled and are assigned to new subscribers. What this means is that a number you believe had opted into your programs now belongs to a different end user who has not opted into your messaging campaign. 

The wireless carriers routinely publish this information via "deactivation reports" that contain a lists of phone numbers that are deactivated within these networks. These reports are published to help message originators keep their programs in compliance.

Why is this important?

In the US, sending messages to end users who have not opted into your programs can result in complaints against you and your programs. This can result in your messages being marked as spam, leading to increased filtering by the carriers, or in the worst case scenarios, fines from the Federal Communications Commission (FCC).

Additionally, sending messages to deactivated phone numbers still incur costs to you, so by keeping your subscriber lists clean, you can save on unnecessary messages.

What do you need to do?

Twilio provides a copy of the deactivation reports to allow you to clean up your subscriber lists periodically. Carriers require these lists to be processed on a daily basis. These reports originate from the carriers and contain a list of phone numbers that have been deactivated on the networks. You should download these reports and compare them against your existing subscriber lists, removing any numbers that have been deactivated. 

What is inside the file?

The contents of the files are straightforward - it's a text file of deactivated phone numbers in e.164 format, each on a new line. The filename is the date the list of phone numbers were deactivated on. 

What about numbers that have ported to a new carrier?

The FCC implemented wireless phone number portability in 2004 meaning that any consumer switching carriers can keep their phone number. However, there are scenarios where an end user releases their number and obtains a new one. In those scenarios, Twilio and our carrier partners are unable to provide this information - they just show up as a regular deactivation and we have no knowledge of the new number. 

How do I get these reports?

Twilio has made these reports available via API for you. All you need to do is make a request to our new /Deactivations endpoint. These files are in a .txt format and are formatted for you to easily integrate into your existing processes and automate the cleaning of your subscriber lists. You can find the API documentation for the new endpoint here.