mintfax lets your application send faxes and track their delivery through a REST API. This overview explains requests, delivery events, and testing, with links to the relevant guides.
API basics
- REST over JSON. One base URL,
https://api.mintfax.com. Multipart on POST /v1/faxes for file upload; JSON everywhere else.
- Bearer token auth. One header,
Authorization: Bearer mfx_test_... for sandbox or mfx_live_... for production. No OAuth, no JWT rotation, no signed request scheme. See Authentication.
- Endpoints.
POST /v1/faxes submits a fax. GET /v1/faxes/{id} returns the current status. GET /v1/events replays the event stream. POST /webhooks registers a delivery endpoint. The endpoint list is in API reference and in the machine-readable openapi.json.
- Sandbox access. After you register, your sandbox environment accepts
POST /v1/faxes with a sandbox key. See Quickstart to send your first simulated fax.
Sending a fax
POST /v1/faxes accepts a multipart body: a to field in E.164 format (leading + and country code), a file attachment up to 10 MB, and an optional Idempotency-Key header. mintfax accepts PDF, DOCX, XLSX, JPG, PNG, TIFF, HTML, and plain text; the full list and per-format notes are in File types.
The response returns immediately with a fax_<ULID> identifier and a status of queued. The fax then transitions through submitted, in_progress, and terminates at delivered or failed. Poll GET /v1/faxes/{id} for the current state, or subscribe to webhooks for status updates.
You can send international faxes through the same API. Numbers must use E.164 format. See International for formatting and destination guidance.
Receiving events
mintfax delivers state changes over webhooks. The event types are fax.queued, fax.sending, fax.delivered, fax.failed, balance.low, and balance.topup. Every payload follows the Standard Webhooks specification and carries three headers: webhook-id, webhook-timestamp, and webhook-signature. The signature is HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body}, keyed by the per-endpoint secret shown once at creation.
Every event is also readable through GET /v1/events and GET /v1/events/{id}, byte-for-byte identical to what was delivered to your endpoint. If you miss a webhook, retrieve the event through the API. If an event arrives twice, use its id to avoid processing it again.
For webhook details, see Webhooks. For verification examples in several languages, see Verify requests.
Included features
Every paid tier includes the features below.
- Signed webhooks. Standard Webhooks signature scheme, per-endpoint secret, atomic rotation via
POST /webhooks/{webhook}/rotate-secret. See Verify requests.
- Idempotency keys. Optional
Idempotency-Key header on POST /v1/faxes. Duplicate requests with the same key return the cached response; the same key with a different body returns 409 idempotency_key_reuse. Keys expire after 24 hours. See Idempotency.
- Automatic retries and error codes. Automatic retries with backoff of 1m / 3m / 5m / 5m, default 3 attempts, configurable per fax via
max_attempts in the range 1-5. Every terminal outcome resolves to one of 10 stable, mintfax-owned error codes (busy, no_answer, line_quality, carrier_busy, network_error, timeout, internal_error, invalid_number, bad_destination, no_route); carrier identity is never exposed. See Errors.
- Sandbox testing. Sandbox and live expose the same API contract, with three documented differences (top-ups are simulated, faxes route to a deterministic simulator, live requires a first credit purchase to activate). Sandbox test numbers produce repeatable outcomes like
busy or no_answer for testing. See Sandbox and Sandbox scenarios.
- A self-serve BAA. mintfax operates under a BAA at every paid tier. You can review and sign the agreement in the dashboard, then download the signed PDF. mintfax keeps a record of the acceptance. See HIPAA.
See the pricing page for per-page rates and tiers.
Statuses and troubleshooting
- Fax statuses:
queued → submitted → in_progress → delivered or failed.
- Every response carries an
X-Request-Id. Errors include the same value as request_id in the JSON envelope, so you can include it when asking support to investigate.
- Error responses are structured. Each response includes an
error code, a human-readable message, an action hint for the caller, and a docs URL that points to the error’s page.
- Attempt records. The fax record’s
attempts[] array records every send attempt with carrier-side outcome and timing. fax.sending webhooks fire once per attempt, so a fax that retries twice emits three fax.sending events. Per-attempt webhook delivery logs are available through GET /webhooks/attempts and can be retried through POST /webhooks/attempts/{attempt}/retry.
Service limits
- Outbound only. mintfax sends faxes; it does not receive them. No inbound numbers, no fax-to-email, no port-in.
- No official SDK packages. REST/JSON with an OpenAPI 3.1 spec and curl examples throughout the docs. Node integration notes are in Node.
- US region storage. Data is stored in a single US region; the DPA requires advance notice of regional changes.
Where to go next
- Quickstart - register an account, send your first simulated fax.
- API reference - every endpoint, request shape, and response schema.
- Webhooks - event types, delivery guarantees, signature verification.
- Errors - every error code with cause and next action.
- HIPAA - the compliance boundary, the BAA click-through, and what mintfax’s commitments cover.
- Build faxing into your SaaS product - multi-tenant patterns, credential management, per-customer webhook routing.
- Compare mintfax to other fax APIs - comparisons with Sinch, Telnyx, Documo, and eFax Developer.
- For startups and For healthtech - guides for startup and healthcare integrations.
Last modified on August 12, 2026
