Send a fax with Python

Outcome

You will send a fax to a sandbox magic number, poll for its status, receive a webhook event, and verify the signature. Everything runs against the sandbox. No real faxes are sent, and no real card is charged; the sandbox uses simulated credits on the same hold, capture, and release path as live.

Prerequisites

A mintfax sandbox API key (mfx_test_...). Sign up here if you do not have one.
Python 3.9 or later.
A PDF file to fax. Any single-page PDF works.
A publicly reachable URL for webhooks, or a tunnel tool such as ngrok.

Install the two libraries this guide uses:

pip install requests standardwebhooks

requests is the HTTP client used throughout this guide. The Standard Webhooks library handles signature verification for you. There is no official mintfax Python SDK; the API is plain REST and works with any HTTP client.

Step 1: Send a fax

Post a fax to the sandbox success number +15005550001. This number always delivers on the first attempt. Create send_fax.py:

import uuid
import requests

API_KEY = "mfx_test_4eC39HqLyjWDarjtT1zdp7dc"
BASE_URL = "https://api.mintfax.com/v1"

with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/faxes",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        data={"to": "+15005550001"},
        files={"file": ("document.pdf", f, "application/pdf")},
    )

response.raise_for_status()
fax = response.json()
print(fax)
# {"id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA", "status": "queued", "to": "+15005550001", ...}

Run it:

python send_fax.py

Verify: The response status is 201 and the status field is queued. Save the returned id for the next step. The Idempotency-Key header makes this request safe to retry. If the network drops and you re-run the same script with the same key, mintfax returns the original response without sending a duplicate fax. Keys expire after 24 hours. See Idempotency keys for the full contract.

Async variant with httpx

If your application is async, swap requests for httpx:

import asyncio
import uuid
import httpx

API_KEY = "mfx_test_4eC39HqLyjWDarjtT1zdp7dc"
BASE_URL = "https://api.mintfax.com/v1"

async def send_fax():
    async with httpx.AsyncClient() as client, open("document.pdf", "rb") as f:
        response = await client.post(
            f"{BASE_URL}/faxes",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            data={"to": "+15005550001"},
            files={"file": ("document.pdf", f, "application/pdf")},
        )
        response.raise_for_status()
        return response.json()

fax = asyncio.run(send_fax())
print(fax)

The request shape is identical. Only the client changes.

Step 2: Check fax status

Poll GET /v1/faxes/{id} until the fax reaches a terminal state (delivered or failed). Create check_status.py:

import sys
import time
import requests

API_KEY = "mfx_test_4eC39HqLyjWDarjtT1zdp7dc"
BASE_URL = "https://api.mintfax.com/v1"
FAX_ID = sys.argv[1]

for attempt in range(30):
    response = requests.get(
        f"{BASE_URL}/faxes/{FAX_ID}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    response.raise_for_status()
    fax = response.json()
    print(f"{fax['status']} (attempt {attempt + 1})")

    if fax["status"] in ("delivered", "failed"):
        print(fax)
        break

    time.sleep(2)
else:
    print("Timed out waiting for terminal state.")

Run it with the fax ID from step 1:

python check_status.py fax_01H7N9WXYZ8VC2QPK5MTRDE3FA

Verify: The fax reaches delivered and the loop exits.

Step 3: Receive a webhook event

mintfax sends a fax.delivered or fax.failed event to your webhook URL when a fax reaches a terminal state. mintfax follows the Standard Webhooks specification, so the reference library handles signature verification for you. Create webhook_server.py:

from flask import Flask, request, abort
from standardwebhooks import Webhook

SIGNING_SECRET = "whsec_3JzE9rYNm2VbQ8P6KxLf1WdGa4Tc"

app = Flask(__name__)
wh = Webhook(SIGNING_SECRET)

@app.route("/webhooks/mintfax", methods=["POST"])
def webhook():
    raw_body = request.get_data()  # bytes, before any parsing
    headers = {
        "webhook-id": request.headers["webhook-id"],
        "webhook-timestamp": request.headers["webhook-timestamp"],
        "webhook-signature": request.headers["webhook-signature"],
    }

    try:
        event = wh.verify(raw_body, headers)
    except Exception:
        abort(400, "Invalid signature")

    print(f"Received {event['type']} for {event['data']['object']['id']}")
    print(event)
    return "", 200

if __name__ == "__main__":
    app.run(port=4242)

Start the server, then expose it with ngrok (or any tunnel):

python webhook_server.py &
ngrok http 4242

Copy the ngrok HTTPS URL and register it as your environment’s webhook endpoint in the mintfax dashboard or via the API. Send another fax (step 1). The event is sent when the fax reaches a terminal state. Verify: The console prints Received fax.delivered for fax_... and the signature check passes. The signature is computed over the raw request bytes as HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}. Verifying a re-serialized JSON body will fail because whitespace and key order change the byte stream. The Standard Webhooks library handles this, along with constant-time comparison and the 5-minute timestamp tolerance. See Verify webhook signatures for what the library does and how to rotate secrets without dropping deliveries.

Step 4: Handle errors

Swap the destination number in send_fax.py to trigger different outcomes:

Number	Behavior
`+15005550001`	Always delivers on first attempt
`+15005550002`	Returns busy on every attempt; terminates `failed`
`+15005550004`	Fails first attempt, delivers on retry
`+15005550005`	Fails per attempt with `LINE_QUALITY`; terminates `failed`
`+15005550008`	Fails on attempt 1 with `INVALID_NUMBER`; no retries

The fax record’s error_code and error_message fields tell you what went wrong and whether a retry makes sense. Rejection-kind scenarios (+15005550006 for insufficient balance, +15005550099 for validation failure) fail the API call itself with a 402 or 422 envelope before any fax record is created. See the Error catalog for every error code and its recommended action. The Sandbox guide lists all magic numbers and the scenarios they simulate. For network errors, timeouts, and HTTP 500 or 503 responses, retry with exponential backoff and reuse the same Idempotency-Key so a mintfax-side accept during a client-side timeout does not produce a duplicate fax. The Idempotency keys guide covers backoff, jitter, and which status codes are safe to retry.

Verify

You have now:

Sent a fax with POST /v1/faxes and an idempotency key.
Polled for status until delivery.
Received a webhook event and verified its signature.
Triggered error scenarios with sandbox magic numbers.

Everything above ran in the sandbox. To send real faxes, swap your sandbox key for a live key (mfx_live_...), purchase credits, and use a real fax number as the destination.

What to do next

Verify webhook signatures - the full signing contract, secret rotation, and reference libraries in other languages.
Idempotency keys - key scope, TTL, replay headers, and retry patterns with backoff and jitter.
Error catalog - every error code, when it fires, and the recommended action.
Sandbox - magic numbers, simulated failures, and sandbox-live parity.

Overview

Sending Faxes

Tracking Delivery

Going to Production

Integrations

Migration

Send a fax with Python

Outcome

Prerequisites

Step 1: Send a fax

Async variant with httpx

Step 2: Check fax status

Step 3: Receive a webhook event

Step 4: Handle errors

Verify

What to do next

​Outcome

​Prerequisites

​Step 1: Send a fax

​Async variant with httpx

​Step 2: Check fax status

​Step 3: Receive a webhook event

​Step 4: Handle errors

​Verify

​What to do next

Outcome

Prerequisites

Step 1: Send a fax

Async variant with httpx

Step 2: Check fax status

Step 3: Receive a webhook event

Step 4: Handle errors

Verify

What to do next