E.164 is the international phone number format: a plus sign, the country code, then the number, with no spaces, dashes or parentheses. A US number like (212) 555-0199 becomes +12125550199. Most SMS APIs want this form, and the ones that accept looser input are still converting to it behind the scenes.
Users don't type E.164. They type spaces, dots, dashes, leading zeros and country codes in odd places. This post covers the shape of the format, how to normalize messy input, and the checks to run before a send so a bad number is caught by you instead of by an error code later.
What E.164 looks like
An E.164 number has three parts, written as one unbroken string. The plus sign marks it as international. Then comes the country code, then the national number. The full string is at most 15 digits, not counting the plus.
| Input a user types | E.164 | Note |
|---|---|---|
| (212) 555-0199 | +12125550199 | US, add the country code 1 |
| 212.555.0199 | +12125550199 | Strip the dots |
| 1-212-555-0199 | +12125550199 | The 1 is the country code already |
| +1 212 555 0199 | +12125550199 | Strip the spaces |
| 02071234567 | needs a country | A leading 0 is a national trunk prefix, not part of E.164 |
That last row is where most bugs live. In many countries a leading zero is dialed inside the country but dropped in E.164. If you strip non-digits and prepend a plus, you'll get a wrong number for those users.
Ready's send endpoint takes to in E.164, and a 10-digit US number is treated as +1. Here's the request shape:
POST https://api.tryready.com/v1/messages
{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true} Normalize on the way in, not on the way out
Normalize a number once, at the point you collect it, and store the E.164 form. Don't store what the user typed and reformat at send time. If you do, every code path that sends a text has to repeat the same cleanup, and one of them will get it slightly wrong.
A reliable approach follows five steps.
- Trim whitespace and remove everything except digits and a leading plus.
- If the input starts with a plus, keep it and treat the next digits as the country code.
- If it doesn't, apply the country you know from the account or the form. Don't guess from the digits alone.
- Remove the national trunk prefix where the country uses one.
- Check the result against that country's length rules.
For this, use a maintained phone number library rather than writing regular expressions. Google's libphonenumber has ports in most languages and carries the per-country rules, such as length and prefix, that a hand-written pattern will miss. Keep your own code to the policy decisions: what the default country is, and what to do with a number that fails.
Store the original input too if you want to show the user what they typed. Store the E.164 value as the key you send and dedupe on.
Format validity is not number validity
A number can be perfectly formatted and still be useless for texting. E.164 validation tells you the string could be a phone number. It doesn't tell you the number is in service, belongs to a mobile line, or can receive a text.
There are three levels of checking, each answering a different question.
- Format check: is this a possible number for this country? Free, local, instant, and it catches typos.
- Number lookup: is it a real, active line, and is it mobile or a landline? This needs a lookup against carrier data. Ready exposes it as
GET /v1/validate/:phone, and the number validation docs cover the response. - Send-time gates: is the number opted out, on your Ban list, or a known landline? These apply at the moment of the send.
Our post on phone number validation APIs goes deeper on the lookup layer, and how to tell if a number is valid or text-capable covers the reader's view of the same problem.
What Ready refuses before it charges you
Some checks run on every send with no setup. Opt-outs and numbers on your Ban list are refused up front and not charged. A number Ready's own sends have already seen as a landline is refused up front on every account, with no charge.
Number validation goes further. With landline validation switched on, numbers a lookup marks as landlines are refused too. That setting is off by default and costs $0.003 per segment when it's on. Don't assume it's what blocks landlines on its own, since the first rule above already catches numbers Ready has seen before.
So the order of defense looks like this: your format check first, which costs nothing, then your own lookup if you want a clean list, then the gates at send time. Each layer catches what the one before it can't.
Handling the failures
When validation fails, tell the user at the form, while they can fix it. "That doesn't look like a US number. Add the area code" is useful on the spot and useless three days later in a failed-send log.
For numbers that came from an import, keep a reject file instead of silently dropping rows. Write out the row, the original value and the reason. A person can fix a hundred typos in a spreadsheet faster than you can guess at them in code.
Two edge cases deserve a decision in advance:
- Extensions. A number with
x123isn't a texting number. Strip the extension and keep the main line, or reject it. - Short codes and service numbers. Five or six digit numbers aren't E.164 mobile numbers. Reject them at the form unless you build for them on purpose.
For bulk sends, POST /v1/messages/bulk takes at most 100 recipients per call, so a clean list also means fewer partial batches to untangle. Normalize the whole list before you split it. To send one message to a whole audience without batching, use POST /campaigns (campaigns API).
A short checklist
- Collect numbers with the country known, and store E.164.
- Use a maintained library for parsing, not regular expressions.
- Handle national trunk prefixes, especially a leading zero.
- Validate format at the form and run a lookup before a large send.
- Keep a reject file for imports.
- Treat the send-time refusals as a backstop, not as your validation.
If you're building the send path next, the SMS API integration guide shows where these checks sit in a full integration, and the messages docs have the request details.