Sandbox
Updated
A test key (ffa_test_...) sends only to the sandbox. No carrier, no cost, nothing leaves the box. The outcome is decided by the destination number or by a scenario you select. Every state a real fax can end in can be rehearsed, including the ones you hope never to see.
Destinations
| Destination | Scenario | What happens |
|---|---|---|
+15550000001 | delivered | every page on the first attempt, evidence on the attempt |
+15550000002 | busy_then_delivered | busy on attempt 1, delivered on attempt 2 |
+15550000003 | partial | the call drops after 3 pages (N minus 1 on a short fax). partial, failure_code partial_delivery. Those pages charged, the rest released. A fax of one page in all, the cover sheet counted, has no page to keep. It ends failed with failure_code partial_delivery, nothing sent and nothing charged |
+15550000004 | no_answer | nobody answers on any of the 3 bounded attempts. failed, failure_code no_answer |
+15550000005 | unknown | the provider accepts the fax and never reports. unknown after the deadline, failure_code callback_missing, hold kept |
+15550000006 | provider_timeout | the provider does not answer the send call. unknown, failure_code provider_timeout |
+15550000007 | invalid_number | rejected at once. failed, no retry |
any other +1 number | delivered | the default |
A number outside +1 on one of the published routes is quoted and delivered the same way, at $0 on the sandbox. A number on no route, or on an excluded one, is refused with unsupported_destination.
Number orders
These outcomes apply to POST /v1/number-orders with a test key that carries the scope number:buy. The default API key does not, so tick it when you create the key. Fax-send destinations above have separate outcomes.
| Number | Order outcome | Test hold |
|---|---|---|
+15550000008 | HTTP 201, status failed, error Sandbox carrier refused this number order. | 2000000 micro held and released |
The refusal number appears in US local inventory. It stays orderable after each refusal. Use a new Idempotency-Key for each rehearsal. Reusing it returns the same order. The hold uses test credit. No live money is charged.
How do I select a scenario?
curl -s $FFA/sandbox/scenarios -H "Authorization: Bearer $FAXFORAGENTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scenario": "partial", "destination": "+12025550100"}'That destination behaves that way for 24 hours. A second choice for the same destination replaces the first, so the list shows one fixture per destination and that one applies. Without destination it applies to every send of the organization that has no more specific fixture. GET /v1/sandbox/scenarios lists the catalog, the table above and the active fixtures. With the CLI: faxforagents sandbox scenario partial --to +12025550100. A live key is refused on these routes with sandbox_only.
How fast is the sandbox, and what does it cost?
The sandbox answers the send call at once, so one worker pass takes a job from queued to its outcome. Retries are scheduled after 60 seconds. The unknown deadline is 600 seconds. Both use the worker defaults shared with production. Sandbox pages cost $0.000, and so does an extraction on the sandbox engine. Every test organization starts with a seeded wallet of $100.00 test credit. The hold, capture and release path runs exactly as it will with real money. GET /v1/balance with a test API key shows that wallet.
Inbound and reset
POST /v1/sandbox/inbound-faxes creates a synthetic inbox item and a fax.received event with the live shape. DELETE /v1/sandbox/data removes the organization's test faxes, attempts, events, deliveries, quotes, documents, uploads, synthetic inbox items and fixtures. It brings the test wallet back to the seed with one balancing ledger entry.
Webhooks
Sandbox sends fire the same events with the same signatures as live ones: fax.queued, fax.started, fax.delivered, fax.partially_delivered, fax.failed, fax.outcome_unknown. A receiver can be finished end to end before the first live page.
From the blog
Start in the sandbox. It is free.
A test API key reaches the sandbox only. Every outcome can be rehearsed there before a wallet is funded.