You test an SMS API without real texts by splitting the work into three layers. Mock the HTTP call in unit tests, use a test mode or test key for integration tests, and send a few real texts to numbers you own before launch. No single layer covers everything, and the gaps between them are where the surprises live.
The reason people look for a sandbox is simple. A real send costs money, can reach a real person, and can trip carrier filters if your test traffic looks like spam. This post covers what sandboxes usually do and don't prove, what Ready offers, and a staging setup that keeps a loop in a test script from texting your customer list.
What a sandbox proves and what it doesn't
A sandbox proves your request is shaped correctly and your code handles the response. It doesn't prove a text reaches a handset. Carrier filtering, registration status, quiet hours and landline detection all happen on the real send path, so a simulated send usually skips them.
That split is useful once you know it. Use this table to decide what each layer is for.
| Layer | What it proves | What it can't prove |
|---|---|---|
| Mocked HTTP in unit tests | Your code builds the right request and handles each error | That the API accepts the request |
| Test mode or test key | Auth, payload shape, response handling, idempotency | Delivery, carrier filtering, real compliance gates |
| Real send to your own phones | The full path, including opt-out replies | Behavior at volume |
| Small real batch to staff | Timing, segment counts, STOP handling | Your whole list's data quality |
If a vendor's docs say "test mode" without listing what it skips, assume it skips the carrier hop and the compliance checks.
What Ready gives you for testing
A test key simulates POST /v1/messages and POST /v1/messages/bulk: nothing is sent or charged, and each result has a test-msg-… id and its segments. Writes it can't simulate answer 403 test_key_not_allowed. On the MCP server a test key simulates send_sms and refuses every other tool that changes or bills something. See the test keys docs and the MCP docs.
We won't promise more than that here. A simulated send is a useful check on your code, and it isn't a delivery test.
For real sends, every text is charged at the normal rate from the first one. You need a card on file and a number of your own, which is $2 a month.
An account can also send up to 500 texts a month before it registers, at its normal per-text rate. That's enough room to run your integration tests against real phones before you file 10DLC registration. After that the account has to register. Our 10DLC explainer covers why.
Test numbers: use your own phones, and fake numbers in fixtures
Test numbers come in two kinds, and people mix them up. One kind is a number you control, like your own cell or a teammate's, which receives real texts. The other is a placeholder in your test data that should never be dialed at all.
For fixtures, use numbers in the reserved 555-01xx range, like +12125550199, the format Ready's own examples use. They're clearly fake, so a fixture that leaks into a real send goes nowhere. Keep them in E.164 form, with a plus sign and country code, since that's what the API expects. A 10-digit US number is treated as +1.
For real-phone tests, keep a short list of staff numbers who have agreed to be texted. A test text is still a text, so the same rules apply: the recipient agreed, and STOP works. If a tester replies STOP, that number is opted out of that account until it replies START. Plan for that before you hand testers a script.
A staging setup that can't text your customers
The most common testing accident isn't a bad send. It's staging pointed at a production contact list. Three guards prevent it.
- Separate keys per environment. Staging gets its own key, held in its own secret store. Production keys never appear in a staging config.
- An allowlist in your own code. Before any send in a non-production environment, check the recipient against a short list of approved test numbers and refuse everything else. This is a few lines and it catches the worst mistake.
- A separate account for staging. If your platform texts on behalf of customers, use a separate sub-account with its own number for tests, so test traffic never shares a number or an opt-out list with a real customer.
Add a fourth for good measure: log every outbound request in staging with the destination, so you can see what a test run would have sent.
What to test before you go live
Here's a checklist that covers the things a simulated send can't.
- Idempotency. Send the same request twice with the same
Idempotency-Keyand confirm one text goes out. Our post on idempotency keys and duplicate texts walks through it. - Number checks. Call
GET /v1/validate/:phoneon a few of your real lead numbers to see what validation returns. The number validation docs list what comes back. - Opt-out round trip. Text STOP from a test phone, then try to send to it. The send should be refused up front, and
GET /v1/opt-outs/:phoneshould show the contact. - Quiet hours. Send a one-to-one text to a number whose local time is outside the window. A dashboard or inbox text to one person is scheduled for when the window opens, however far off, and an API text is held only if the window opens within 6 hours. Otherwise the API answers 409 QUIET_HOURS_BLOCK, and your code needs a plan for that.
- Segment counts. Send one message with an emoji and see how it splits. A text with an emoji drops to 70 characters per segment, and each segment is billed.
Keep the costs small and the results honest
A full test pass costs very little. At $0.0075 per segment plus a $0.0045 carrier fee, a single-segment test text is a little over a cent, so 30 test sends run well under a dollar. That figure leaves out screening, which is extra if you've switched on scrub lists or number validation.
Write down what each test run proved. "Mock passed" means your code is shaped right. "Real send arrived" means the path works. Keep those two claims separate in your release notes, and you'll avoid the surprise of a green test suite and a quiet inbox on launch day. For the next step, the SMS API integration guide covers the build itself, and the API quickstart gets you to a first send.