> ## 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.

# 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.

<Info>If you are an AI coding agent, [ai-agents.md](ai-agents.md) is a denser reference written for you.</Info>

## Step 1: Register

```bash theme={null}
curl -X POST https://api.mintfax.com/v1/account/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Account", "email": "dev@example.com"}'
```

Response:

```json theme={null}
{
  "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

```bash theme={null}
curl -X POST https://api.mintfax.com/v1/account/register/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "code": "482901"}'
```

Response:

```json theme={null}
{
  "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](/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.

```bash theme={null}
curl -X POST https://api.mintfax.com/v1/faxes \
  -H "Authorization: Bearer mfx_test_abc123def456..." \
  -F "to=+15005550001" \
  -F "file=@document.pdf"
```

Response:

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.mintfax.com/v1/faxes/fax_8aZqRm4yT3vK7pNxJ2bH9c \
  -H "Authorization: Bearer mfx_test_abc123def456..."
```

Response (after processing):

```json theme={null}
{
  "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.

```bash theme={null}
curl https://api.mintfax.com/v1/environment/balance \
  -H "Authorization: Bearer mfx_test_abc123def456..."
```

Response:

```json theme={null}
{
  "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](/credits) for the full account-pool model.)

## Next Steps

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