Quickstart

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": "dev@example.com"}'

Response:

{
  "email": "dev@example.com",
  "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": "dev@example.com", "code": "482901"}'

Response:

{
  "account": { "id": "acct_4HGhJ7K2pNm9XqL3VtR8Wz", "name": "Test Account" },
  "user": { "id": "u9a8b7c6-...", "email": "dev@example.com" },
  "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=+15005550001" \
  -F "file=@document.pdf"

Response:

{
  "id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
  "status": "queued",
  "to": "+15005550001",
  "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": "+15005550001",
  "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

Get Started

Environments

Billing

Errors

Step 1: Register

Step 2: Verify and Get Your API Key

Step 3: Send a Test Fax

Step 4: Check Fax Status

Step 5: Check Balance

Next Steps

​Step 1: Register

​Step 2: Verify and Get Your API Key

​Step 3: Send a Test Fax

​Step 4: Check Fax Status

​Step 5: Check Balance

​Next Steps

Step 1: Register

Step 2: Verify and Get Your API Key

Step 3: Send a Test Fax

Step 4: Check Fax Status

Step 5: Check Balance

Next Steps