Faxing built for AI agents.

1. Quote (reserves cost for 600s)

POST /api/v1/agent/fax/quote
Authorization: Bearer sk_...
Content-Type: application/json

{"to": "+18005551234", "estimated_pages": 3}

→ 200 OK
{
  "quote_id": 42,
  "to": "+18005551234",
  "estimated_pages": 3,
  "cost_cents": 21,
  "reserved_balance_cents": 0,
  "billing_method": "subscription",
  "balance_cents_after": 5000,
  "expires_at": "2026-05-25T17:42:00+00:00"
}

2. Send (uploads the PDF)

POST /api/v1/agent/fax/42/send
Authorization: Bearer sk_...
Idempotency-Key: agent-trace-9f3e
Content-Type: multipart/form-data; boundary=...

file=@invoice.pdf

→ 202 Accepted
{
  "id": 8801,
  "direction": "outbound",
  "status": "sending",
  "to_number": "+18005551234",
  "page_count": 3,
  "cost_cents": 21,
  "balance_cents": 5000,
  "telnyx_fax_id": "...",
  "created_at": "..."
}

3. Webhook receipt (signed)

POST https://your-app.example.com/securelyfax-webhook
X-SecurelyFax-Timestamp: 1748192520
X-SecurelyFax-Signature: sha256=<hex>
X-SecurelyFax-Event: fax.delivered
Content-Type: application/json

{
  "event": "fax.delivered",
  "fax_id": 8801,
  "direction": "outbound",
  "status": "delivered",
  "to": "+18005551234",
  "pages": 3,
  "cost_cents": 21,
  "balance_cents": 5000,
  "completed_at": "..."
}

Verify with HMAC-SHA256 over {timestamp}.{raw_body} using your webhook signing secret:

import hmac, hashlib

def verify(secret, timestamp, body, signature_header):
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)