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.

mintfax uses a prepaid credit system. You purchase credit packages, and credits are consumed per page when faxes are delivered. Each environment has its own independent balance - credits are not shared or poolable between environments.

​
Purchasing Credits

Buy credit packages from the dashboard under the environment you want to fund. Each live environment must be funded separately. Sandbox environments come with a dummy balance pre-loaded on creation.

​
Per-Page Pricing

Credits are deducted per page transmitted. A 3-page fax costs 3x the per-page rate. The per-page rate depends on the destination country and your pricing tier.

​
Hold, Capture, Release

When you submit a fax, credits move through a three-step lifecycle:
  1. Hold - a credit hold is placed immediately on submission, reserving the estimated cost based on page count. The held amount is deducted from available and added to held.
  2. Capture - when the fax is delivered successfully, the hold is captured as a permanent charge. The held amount is removed from held.
  3. Release - if delivery permanently fails, the hold is released back to your available balance. You are never charged for failed deliveries.
Submit fax         ->  available decreases, held increases
Delivery succeeds  ->  held decreases (captured as charge)
Delivery fails     ->  held decreases, available increases (released)

​
Checking Your Balance

Query GET /account/balance to see your current credit state: 
curl https://api.mintfax.com/v1/account/balance \
  -H "Authorization: Bearer fx_test_abc123..."

{
  "available": 4550,
  "held": 450
}
FieldDescription
availableCredits available for new faxes, in cents. Holds are already deducted from this value.
heldCredits reserved for faxes currently in flight. Returns to available on failure, removed permanently on success.
A held value of 0 means no faxes are in flight. A non-zero held means one or more faxes are queued or being transmitted, and the reserved credits will either be captured or released once each fax reaches a terminal state.

​
Insufficient Balance

If available is too low to cover the estimated cost of a fax, the API returns 402 with insufficient_balance: 
{
  "error": "insufficient_balance",
  "message": "Insufficient balance to submit fax",
  "action": "top_up_balance"
}
Purchase additional credits for the environment, then retry. In sandbox, you can trigger this deliberately by exhausting the dummy balance - see Sandbox - Balance Testing.