555-0100 through 555-0199 are reserved in every US area code and can never belong to a real person. The platform treats them as test numbers: a message sent to one is never handed to a carrier, and the last two digits decide what happens to it.
Use them to see how your integration handles each outcome before you send to real people.
Outcomes
Use any area code. The examples use202.
The codes are the same ones real messages fail with. See Delivery error codes for what each one means and how to react.
Where they work
Everywhere a real number works:- A project test, from the app or
POST /v1/projects/{id}/test. - A full project send. Upload a list of test numbers and schedule the project as usual.
- A triggered send, through
POST /v1/projects/{id}/recipients. - A conversation reply.
212 is treated as Eastern time, one in 415 as Pacific.
What you will see
A test number behaves like a real recipient in every way except that no phone receives the message.- Status. The message moves to
sent, then todeliveredorfailed, within a few seconds. - Webhooks.
message.sentfires, followed bymessage.deliveredormessage.failed, with the same payload a real message produces. Thecarrierfield isTest carrier. The two reply numbers also firemessage.replieda few seconds after delivery. is_test. This field still describes how the message was sent, not who it was sent to. It istruefor a project test andfalsefor a full send, even to a test number.- Reports and exports. Test-number messages are counted in project totals, error reports, and exports like any other message.
- List analysis. Analyzing a list reports test numbers as mobile numbers on
Test carrier, so an analyzed list keeps them.
Billing
A message to a test number is billed at your normal per-message rate, exactly like a message to a real number, and a reply from a test number is billed like any inbound message. Your balance, usage, and invoices show both the same way, so you can rehearse those too.Replies and STOP
555-0110 and 555-0111 text back about eight seconds after the message is delivered. The reply arrives exactly as a real one does: it appears in the conversation, fires message.replied, and can be answered from the app or POST /v1/conversations/{conversation_id}/messages.
555-0110repliesThanks for the update.555-0111repliesSTOP. The number is added to the sender’s opt-out list and the conversation is marked opted out, so later sends from that sender skip it. Remove it from the opt-out list to rehearse again, or use the same ending in another area code.
Things to know
- The failed opt-out number changes nothing.
555-0105fails with the opted-out code, but the number is not added to your opt-out lists. Only theSTOPreply from555-0111does that. - Link clicks are real. A tracked link in a message to a test number is a working link. Open it from the conversation in the app to produce a real
link.clickedevent. - Projects can still pause. If most of a large send goes to the blocked or rejected numbers (
555-0101,555-0102), the project is paused for a high carrier block rate, as a real project would be. Mix in555-0100to keep a rehearsal running. - Other outcomes. Rate limits and registration failures cannot be simulated with test numbers.
