> ## Documentation Index
> Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Phone Numbers

> Reserved phone numbers that never reach a real phone and return a fixed delivery outcome, so you can rehearse delivered and failed messages end to end.

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`.

| Send to | Result | `error_code` | `error_message` |
| - | - | - | - |
| `+1 202 555 0100` | Delivered | none | none |
| `+1 202 555 0101` | Failed | `003` | Blocked as spam (permanent) |
| `+1 202 555 0102` | Failed | `004` | Rejected by destination |
| `+1 202 555 0103` | Failed | `021` | Destination is not a mobile phone |
| `+1 202 555 0104` | Failed | `012` | Invalid destination number |
| `+1 202 555 0105` | Failed | `300` | Recipient opted out |
| `+1 202 555 0106` | Failed | `005` | Expired during transmission |
| `+1 202 555 0110` | Delivered, then replies `Thanks for the update.` | none | none |
| `+1 202 555 0111` | Delivered, then replies `STOP` | none | none |
| Any other `555-01XX` | Delivered | none | none |

The codes are the same ones real messages fail with. See [Delivery error codes](https://docs.politicalcomms.com/api-reference/webhooks/error-codes.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.