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). Those pages charged, the rest released |
+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.
How do I select a scenario?
curl -s $FFA/sandbox/scenarios -H "Authorization: Bearer $FFA_KEY" \
-H "Content-Type: application/json" \
-d '{"scenario": "partial", "destination": "+12025550100"}'That destination behaves that way for 24 hours. 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: ffa 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 and the unknown deadline is 600 seconds, as in production. Sandbox pages cost $0.000. 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.