A fax API that behaves like the rest of your stack.

export FAX_API=https://api.faxdev.com
export FAX_API_KEY=bfx_test_...     # bfx_test_ = sandbox: never dials, never bills
export ACCOUNT_ID=8a1f5c2e-3b7d-4e0a-9c61-2f4d8b7e1a90

# 1. Upload the document (raw body, up to 20 MiB)
curl -sS -X POST "$FAX_API/v1/accounts/$ACCOUNT_ID/uploads" \
  -H "Authorization: Bearer $FAX_API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "Idempotency-Key: upload-invoice-1042" \
  --data-binary @invoice-1042.pdf
# -> { "content_ref": "3f9b2d71-6c4e-4a8b-b0d2-7e5a1c9f8d36", ... }

# 2. Send it
curl -sS -X POST "$FAX_API/v1/accounts/$ACCOUNT_ID/faxes" \
  -H "Authorization: Bearer $FAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-invoice-1042" \
  -d '{
        "to": "+13125550142",
        "content_ref": "3f9b2d71-6c4e-4a8b-b0d2-7e5a1c9f8d36",
        "quality": "fine",
        "client_reference": "invoice-1042",
        "cover": { "enabled": true, "line1": "Invoice 1042", "line2": "Attn: Accounts payable" }
      }'

# 3. Follow it
curl -sS "$FAX_API/v1/accounts/$ACCOUNT_ID/faxes/c0e7a4b2-91d5-4f3e-8a26-5b1c9d0e7f43" \
  -H "Authorization: Bearer $FAX_API_KEY"

# pip install requests
import os, time, requests

API = os.environ["FAX_API"]            # https://api.faxdev.com
KEY = os.environ["FAX_API_KEY"]        # bfx_test_... = sandbox
ACCOUNT = os.environ["ACCOUNT_ID"]
auth = {"Authorization": f"Bearer {KEY}"}
base = f"{API}/v1/accounts/{ACCOUNT}"

# 1. Upload the document
with open("invoice-1042.pdf", "rb") as f:
    up = requests.post(f"{base}/uploads", data=f, timeout=60, headers={
        **auth, "Content-Type": "application/pdf", "Idempotency-Key": "upload-invoice-1042"})
up.raise_for_status()

# 2. Send it (reuse the same Idempotency-Key if you retry)
res = requests.post(f"{base}/faxes", timeout=30,
    headers={**auth, "Idempotency-Key": "send-invoice-1042"},
    json={"to": "+13125550142", "content_ref": up.json()["content_ref"],
          "client_reference": "invoice-1042"})
res.raise_for_status()
fax = res.json()

# 3. Poll until it finishes (or wait for the webhook)
DONE = {"succeeded", "failed", "cancelled", "expired", "rejected"}
while fax["status"] not in DONE:
    time.sleep(5)
    fax = requests.get(fax["links"]["self"], headers=auth, timeout=30).json()
print(fax["status"], fax["pages_delivered"], fax["caller_id_delivery"])

// Node 18+ (global fetch), ES modules
import { readFile } from "node:fs/promises";

const { FAX_API, FAX_API_KEY, ACCOUNT_ID } = process.env; // bfx_test_... = sandbox
const base = `${FAX_API}/v1/accounts/${ACCOUNT_ID}`;
const auth = { Authorization: `Bearer ${FAX_API_KEY}` };

// 1. Upload the document
const up = await fetch(`${base}/uploads`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/pdf", "Idempotency-Key": "upload-invoice-1042" },
  body: await readFile("invoice-1042.pdf"),
}).then((r) => r.json());

// 2. Send it (reuse the same Idempotency-Key if you retry)
let fax = await fetch(`${base}/faxes`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json", "Idempotency-Key": "send-invoice-1042" },
  body: JSON.stringify({ to: "+13125550142", content_ref: up.content_ref, client_reference: "invoice-1042" }),
}).then((r) => r.json());

// 3. Poll until it finishes (or wait for the webhook)
const done = new Set(["succeeded", "failed", "cancelled", "expired", "rejected"]);
while (!done.has(fax.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  fax = await fetch(fax.links.self, { headers: auth }).then((r) => r.json());
}
console.log(fax.status, fax.pages_delivered, fax.caller_id_delivery);

HTTP/1.1 202 Accepted
{
  "id": "c0e7a4b2-91d5-4f3e-8a26-5b1c9d0e7f43",
  "status": "queued",
  "direction": "outbound",
  "to": "+13125550142",
  "from": "+14155550100",
  "did_id": "5d2c8e1a-7b4f-4c9d-a3e6-0f1b2c3d4e5f",
  "caller_id_delivery": null,
  "pages": null,
  "pages_delivered": null,
  "retail_cents": null,
  "sandbox": true,
  "read_at": null,
  "failure_class": null,
  "reject_reason": null,
  "client_reference": "invoice-1042",
  "created_at": "2026-10-27T14:04:05Z",
  "completed_at": null,
  "links": {
    "self": "https://api.faxdev.com/v1/accounts/8a1f5c2e-3b7d-4e0a-9c61-2f4d8b7e1a90/faxes/c0e7a4b2-91d5-4f3e-8a26-5b1c9d0e7f43",
    "attempts": "https://api.faxdev.com/v1/accounts/8a1f5c2e-3b7d-4e0a-9c61-2f4d8b7e1a90/faxes/c0e7a4b2-91d5-4f3e-8a26-5b1c9d0e7f43/attempts",
    "document": null
  }
}

HTTP/1.1 201 Created
{
  "content_ref": "3f9b2d71-6c4e-4a8b-b0d2-7e5a1c9f8d36",
  "content_type": "application/pdf",
  "bytes": 48213,
  "sha256": "9f2c4e...b71a",
  "expires_at": "2026-10-27T15:04:05Z"
}

// Node 18+ / Express: verify before you parse. Use the raw body bytes.
import crypto from "node:crypto";

export function verifyFaxWebhook(rawBody /* Buffer */, headers, secret /* "whsec_..." */) {
  const ts = headers["fax-timestamp"];
  const sigHeader = headers["fax-signature"];
  if (!ts || !sigHeader) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;      // reject skew over 5 minutes
  const expected = crypto.createHmac("sha256", secret)
    .update(`${ts}.`).update(rawBody).digest("hex");
  // After a secret rotation the header carries two comma-separated signatures for one hour.
  return sigHeader.split(",").some((s) => {
    const a = Buffer.from(s.trim(), "hex"), b = Buffer.from(expected, "hex");
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

# Python 3: same check. Cache f"{ts}.{signature}" for 5 minutes to drop replays.
import hashlib, hmac, time

def verify_fax_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
    h = {k.lower(): v for k, v in headers.items()}
    ts, sig_header = h.get("fax-timestamp"), h.get("fax-signature")
    if not ts or not sig_header or abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s.strip()) for s in sig_header.split(","))

{
  "mcpServers": {
    "fax": {
      "type": "http",
      "url": "https://api.faxdev.com/mcp",
      "headers": { "Authorization": "Bearer bfx_live_..." }
    }
  }
}

claude mcp add --transport http fax https://api.faxdev.com/mcp \
  --header "Authorization: Bearer bfx_live_..."