Yes, Twilio's Programmable Messaging API has phone number validation logic built in. We will reject messages to numbers we are certain are incorrect. We will also reject messages that cannot be delivered due to incompatibility between the "From" and "To" numbers.
However, we don't guarantee that we will reject all messages to invalid or inactive numbers. It is your responsibility to provide accurate data to the best of your ability, and ensure that you are always sending to properly opted-in users as per our Messaging Policy.
Below, we will describe how Twilio validates the "To" phone numbers in your outbound message requests, and what errors you might encounter when you attempt to send to invalid or unreachable numbers.
Step 1: Checking to see if the "To" number is valid
When you make a POST request to Twilio's REST API, Twilio will check the validity of the "To" phone number in the request. If Twilio discovers that the "To" phone number provided cannot possibly exist based on its format, Twilio will respond to your API request with an HTTP 400 response and Error 21211.
Twilio will also fail the below with 21211:
- Messages sent to Short Codes. Twilio numbers cannot send to Short Codes.
- Messages sent to Alphanumeric Sender IDs. Alphanumeric Sender IDs are only capable of sending messages, they cannot receive messages.
- Messages sent to the same number as the "From" number. Numbers cannot send messages to themselves.
If the phone number seems to be valid based on its format, Twilio will move to the next step.
Step 2: Fetching mobile carrier information on the "To" number (and checking if the "To" is a mobile number)
After validating that the format of the "To" number is valid, Twilio will do a lookup on the number to get its mobile carrier information. This is similar to the lookup functionality offered in Twilio's Lookup API.
In the United States, Canada, and the UK, Twilio will attempt message delivery to landline devices, as message delivery to landlines is sometimes supported by carriers. The only exception is that short code numbers cannot communicate with landlines under any circumstances, so attempting to send from a short code number to a landline will result in an HTTP 400 status and error 21612.
In all other countries, if Twilio performs a number lookup and detects that a number is a landline number, Twilio will respond to your API request with an HTTP 400 status and error 21614.
In all countries: If our number lookup returns a 404 response indicating the number is not a currently valid, reachable number, we will fail the message with error 21614.
Step 3: Checking whether Twilio can reach the "To" number with the "From" parameter you provided
Assuming that we are able to retrieve carrier information for the "To" number as described in Step 2, Twilio will now check to make sure our system supports sending from the "From" number or sender you provided to the "To" number.
For example, if you provided a US short code as your "From" parameter and a Canada mobile number as your "To" parameter, your API request will result in an HTTP 400 status and error 21612, because a short code can only send to numbers in its own country.
On the other hand, if you provided a US short code as "From" and a US mobile number as "To," Twilio's system will recognize this as a valid combination and proceed to sending the message.
Once we complete this step, we will complete any additional processing that is needed on the message, and enqueue it to be sent.
Note: This step often fails due to regulatory restrictions in the destination country. You should always check the SMS Guidelines for the recipient country before starting any messaging campaigns there.
If your application is logging a lot of HTTP 400 responses from Twilio containing errors 21211, 21612, or 21614, it's likely that there's a problem with your contact list or the way you are collecting users' numbers. You should take steps to figure out what is causing these errors. Please refer to Twilio's error documentation, which includes troubleshooting tips.
As a reminder, Twilio's Messaging Policy and carrier policies require that you only send messages to users who have provided explicit consent to receive those messages from you. Failure to do this can result in failed messages due to invalid numbers, and moreover it can result in message filtering on the messages that do go through.
In general, it is a good idea to keep track of whether the numbers you collect from your users or customers are landlines or mobile. This makes it easier for you to know how best to reach them. If you don't have that information already, you may consider using the Twilio Lookup API. This enables you to check whether numbers are valid, whether they are mobile or landline, and which carrier the number is on.
Most countries around the world are increasingly regulating the types of content and Senders that can be used to send messages at scale. You should always check the SMS Guidelines for the recipient country before starting any messaging campaigns there.