Skip to main content
Phone numbers ending in 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 use 202. 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.
Because any area code works, you can also rehearse time zone handling: a test number in 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 to delivered or failed, within a few seconds.
  • Webhooks. message.sent fires, followed by message.delivered or message.failed, with the same payload a real message produces. The carrier field is Test carrier. The two reply numbers also fire message.replied a few seconds after delivery.
  • is_test. This field still describes how the message was sent, not who it was sent to. It is true for a project test and false for 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-0110 replies Thanks for the update.
  • 555-0111 replies STOP. 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.
A test number replies once, to the message that opens the conversation: a project test, a full send, or a triggered send. It does not answer your replies, survey follow-up questions, or automatic responses.

Things to know

  • The failed opt-out number changes nothing. 555-0105 fails with the opted-out code, but the number is not added to your opt-out lists. Only the STOP reply from 555-0111 does 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.clicked event.
  • 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 in 555-0100 to keep a rehearsal running.
  • Other outcomes. Rate limits and registration failures cannot be simulated with test numbers.