Quickstart

Create a sandbox account and send your first sandbox fax

This guide walks through creating a sandbox account and sending a sandbox fax. Every step is a single curl command with a predictable response.

If you are an AI coding agent, ai-agents.md is a denser reference written for you.

Step 1: Register

curl -X POST https://api.mintfax.com/v1/account/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Account", "email": "[e-mail]"}'

Response:

{
  "email": "[e-mail]",
  "message": "Activation code sent. Valid for 15 minutes.",
  "expires_in": 900
}

Check your email for a 6-digit activation code.

Step 2: Verify and Get Your API Key

curl -X POST https://api.mintfax.com/v1/account/register/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "code": "482901"}'

Response:

{
  "account": { "id": "acct_4HGhJ7K2pNm9XqL3VtR8Wz", "name": "Test Account" },
  "user": { "id": "u9a8b7c6-...", "email": "[e-mail]" },
  "environment": { "id": "env_2BcD3eF4gH5iJ6kL7mN8oP", "name": "Sandbox", "type": "sandbox" },
  "api_key": "mfx_test_abc123def456...",
  "api_key_account": "mfx_acct_qpr456stv789..."
}

Save both keys. They are only shown once. api_key is an environment key for sending faxes in your sandbox environment; api_key_account (the mfx_acct_ key) is an account-management key for account-level operations like reading pooled balances or managing environments. See Keys for the full breakdown of the three key kinds.

Step 3: Send a Test Fax

Use a sandbox number. Sandbox faxes are not delivered to real fax machines.

curl -X POST https://api.mintfax.com/v1/faxes \
  -H "Authorization: Bearer mfx_test_abc123def456..." \
  -F "to=[phone]" \
  -F "file=@document.pdf"

Response:

{
  "id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
  "status": "queued",
  "to": "[phone]",
  "created_at": "2026-01-15T10:30:00Z"
}

Save the fax id for the next step.

Step 4: Check Fax Status

curl https://api.mintfax.com/v1/faxes/fax_8aZqRm4yT3vK7pNxJ2bH9c \
  -H "Authorization: Bearer mfx_test_abc123def456..."

Response (after processing):

{
  "id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
  "status": "delivered",
  "to": "[phone]",
  "pages": 1,
  "retries_remaining": 3,
  "submitted_at": "2026-01-15T10:30:01Z",
  "completed_at": "2026-01-15T10:30:05Z",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:05Z"
}

In sandbox mode, sandbox numbers resolve to simulated outcomes within seconds.

Step 5: Check Balance

Use your environment key against /environment/balance to read the current environment’s balance.

curl https://api.mintfax.com/v1/environment/balance \
  -H "Authorization: Bearer mfx_test_abc123def456..."

Response:

{
  "type": "sandbox",
  "available": 9994,
  "held": 0,
  "auto_top_up": {
    "enabled": false,
    "threshold_pct": 20,
    "package_id": null
  }
}

Amounts are in cents. The sandbox pool is seeded on account registration so you can start sending immediately. Each sandbox fax holds and captures credits the same way live faxes do, so you can exercise insufficient-funds and low-balance flows without spending real money. Auto-top-up is configurable per balance row in the dashboard.

(You can also call GET /v1/account/balance with your mfx_acct_ key to read both the live and sandbox balances at once. See Credits for the full account-pool model.)

Next Steps

• Keys - the three key kinds (account, environment, ingest) and when to use each
• Credits - account-pool model, asymmetric balance reads, auto-top-up
• Activation - go live by making your first credit purchase
• Environments - sandbox vs live isolation and routing
• Authentication - key management and rotation
• Error Catalog - every error code and how to handle it
• Webhooks - get notified on delivery instead of polling
• Sandbox - sandbox numbers for simulating different outcomes