Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Use sandbox API keys and magic fax numbers to test every outcome your integration needs to handle. No real faxes are sent, and no real credits are spent.

​
Prerequisites

  • A mintfax account. A sandbox workspace is created automatically when you register.
  • A sandbox API key (prefixed fx_test_). Create additional keys from the dashboard or via the API.

​
How the sandbox works

The sandbox is a separate environment, not a mode toggle. Your sandbox workspace has its own API keys, fax records, balance, and webhook endpoints. Activity in the sandbox never touches your live workspace. The reverse is also true. Sandbox API keys start with fx_test_. Live keys start with fx_live_. The prefix tells mintfax which environment to use. Nothing else to configure. Credits work the same way in both environments. When you send a sandbox fax, mintfax places a hold on your sandbox balance, captures it on delivery, and releases it on failure. The only difference: no real money changes hands, and no fax reaches a machine.

​
Magic fax numbers

Sandbox faxes must be sent to magic numbers in the +1 (500) 555-XXXX range. Each number produces a deterministic outcome, so you can exercise every code path in your integration.
NumberScenarioBehavior
+15005550001SuccessAlways succeeds on first attempt
+15005550002BusyReturns busy on every attempt
+15005550003No answerRings out without pickup
+15005550004Transient failureFails first attempt, succeeds on retry
+15005550005Permanent failureAlways fails permanently
+15005550006Insufficient balanceReturns insufficient_balance error before send
+15005550099Validation failureReturns validation error (invalid number format)
Sending to a number outside this range returns a validation error telling you to use a magic number.

​
Step 1: Send a fax to the success number

Submit a fax to +15005550001 with your sandbox API key. 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123def456" \
  -F "to=+15005550001" \
  -F "file=@document.pdf"
The response includes a fax ID and a queued status. mintfax places a credit hold on your sandbox balance at this point. 
{
  "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
  "status": "queued",
  "to": "+15005550001"
}
Verify: poll GET /v1/fax/{id} until status reaches delivered. The hold is captured and your sandbox balance decreases by the per-page cost.

​
Step 2: Simulate a failure

Send a fax to +15005550002 to simulate a busy line. 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123def456" \
  -F "to=+15005550002" \
  -F "file=@document.pdf"
Poll the fax status: 
curl https://api.mintfax.com/v1/fax/fax_01H7N9WXYZ8VC2QPK5MTRDE3FA \
  -H "Authorization: Bearer fx_test_abc123def456"

{
  "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
  "status": "failed",
  "to": "+15005550002",
  "error": "fax_busy",
  "message": "Destination busy"
}
The credit hold is released back to your sandbox balance on failure. Verify: call GET /v1/account/balance and confirm the balance returned to its previous value.

​
Step 3: Test retry behavior

+15005550004 fails on the first attempt, then succeeds on retry. Use it to confirm your integration handles transient failures. 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123def456" \
  -F "to=+15005550004" \
  -F "file=@document.pdf"
If you have a webhook endpoint registered, you will receive a fax.failed event, then fax.retry_scheduled, then fax.delivered as the fax progresses. This is the same event sequence a transient carrier failure produces in live. Verify: the final fax status should be delivered.

​
Step 4: Test insufficient balance

Send to +15005550006 to trigger an insufficient_balance error. This number rejects the fax before submission regardless of your actual sandbox balance, so you can test the error path without draining credits first. 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123def456" \
  -F "to=+15005550006" \
  -F "file=@document.pdf"

{
  "error": "insufficient_balance",
  "message": "Insufficient balance to submit fax",
  "action": "top_up_balance",
  "docs": "/docs/errors#insufficient-balance"
}
The response is HTTP 402. Your integration should handle this by prompting a balance top-up or alerting the operator. See the error catalog for the full list of error codes and recommended actions. Verify: no fax record was created and your balance is unchanged.

​
Step 5: Test validation errors

Send to +15005550099 to receive a validation error. This is what happens when a fax number fails format validation. 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123def456" \
  -F "to=+15005550099" \
  -F "file=@document.pdf"
The response is HTTP 422 with field-level error details. Verify: confirm your integration surfaces the validation error to the caller.

​
Sandbox balance

Every sandbox workspace starts with a simulated credit balance. Credits are consumed the same way as in live: hold on submit, capture on delivery, release on failure. No real money is involved. You can also trigger the insufficient_balance error organically by exhausting your sandbox balance with enough faxes, then submitting one more. Top up sandbox credits from the dashboard or via the API. Auto top-up works in the sandbox too. If you have it enabled, it fires at the configured threshold the same way it does in live.

​
What the sandbox does not do

Sandbox faxes never reach a real fax machine, and your payment method is never charged. Sandbox credit consumption is simulated. GET /v1/fax/{id}/image returns 404 for sandbox faxes. The sandbox exercises status transitions, webhooks, and balance behavior, but does not render fax images.

​
Writing integration tests

Magic numbers are deterministic. You can write automated tests against them without mocks or carrier dependencies. A minimal test suite covers four paths:
  1. Happy path. Send to +15005550001, poll until delivered, assert the balance decreased.
  2. Failure handling. Send to +15005550005, poll until failed, assert the hold was released.
  3. Retry recovery. Send to +15005550004, poll until delivered, assert the fax recovered after a transient failure.
  4. Balance guard. Send to +15005550006, assert HTTP 402 and the insufficient_balance error code.
Each test runs against the sandbox with your fx_test_ key. No cost, no external dependencies.

​
Verify

After working through the steps above, you have exercised success, busy failure, transient retry, insufficient balance, and validation error paths. That covers the outcomes most integrations need.

​
What to do next

  • Error catalog for the full list of error codes, HTTP statuses, and recommended actions.
  • Glossary for definitions of sandbox, workspace, E.164, and other terms used on this page.