Fax

Orbit’s Fax channel sends and receives T.38 / G.711 faxes via Telnyx Programmable Fax — the named exception to Orbit’s outbound-termination policy (voice and SMS exit only via the Devotel softswitch; fax/T.38 and MMS are the two channels permitted to terminate on Telnyx). Documents are delivered as PDF or TIFF; status updates flow through the same channel-agnostic webhook contract as other channels. Fax is on-success-charge: Orbit only bills your wallet when the carrier confirms a successful fax transmission. Failed attempts (busy, no-answer, line-quality) are NOT billed.

Send a fax

curl -X POST https://api.orbit.devotel.io/api/v1/messages/fax \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "media_url": "https://example.com/contract.pdf",
    "quality": "high",
    "status_callback": "https://example.com/webhooks/fax",
    "metadata": { "order_id": "ord_123" }
  }'

Request fields

Field	Type	Required	Notes
`to`	string	yes	Destination fax number in E.164 (`+<country><area><number>`). An invalid format is rejected with `INVALID_PHONE_NUMBER`.
`from`	string	yes	Fax-capable number owned by your org. Omit it and the send fails with `MISSING_REQUIRED_FIELD`.
`media_url`	string	yes	Publicly reachable URL of the document to send. HTTPS is the only scheme Orbit submits to the carrier — `http://` URLs are rejected at send time. The carrier fetches the document; Orbit does not re-host it.
`quality`	string	no	One of `normal` (default), `high`, or `very_high`. Higher values raise the scanning resolution of the transmitted pages: `high` improves legibility of small text and fine graphics, `very_high` is for artwork-grade originals. Higher quality also lengthens and slightly destabilizes the T.38 handshake on poor lines. Any other value is rejected by schema validation.
`status_callback`	string (URL)	no	Per-send DLR webhook URL. Your endpoint receives the delivery events for this message instead of the org default.
`status_callback_secret`	string	no	Signing secret paired with `status_callback` — required when the URL is set (a bare secret is rejected with `VALIDATION_ERROR`). The secret signs every delivery callback to this URL so you can verify the sender.
`status_callback_events`	string[]	no	Optional event filter paired with `status_callback` (a bare filter with no URL is rejected). Limits which delivery events reach your callback.
`metadata`	object (string→scalar)	no	Free-form string/number/boolean key-value bag stored on the message record. Stored as JSONB, so keep it small (a handful of correlation keys) — oversize metadata inflates the row and slows reads. Values are coerced to scalars.

Idempotency: every fax send carries a stable provider-side idempotency key (orbit-fax:<message-id>), so a retry of the same send — from your client or from Orbit’s queue worker — dedups at the carrier and does not bill twice. Re-sending the same payload is safe; you do not need to mint your own idempotency key.

Response

{
  "data": {
    "id": "msg_a1b2c3d4e5f6g7h8",
    "status": "queued",
    "channel": "fax"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

The returned id is the Orbit message ID — use it to poll status or match webhook events. The provider-side fax ID is attached asynchronously as external_id once the transmission is dispatched and is readable via GET /api/v1/fax/:id.

Receive an inbound fax

An inbound fax arrives as a Telnyx fax.received webhook on Orbit’s inbound endpoint. Orbit resolves the tenant from the recipient DID, writes a messages row with channel: "fax" and direction: "inbound", and then runs the per-DID routing config to deliver the fax downstream.

Routing a number’s inbound faxes

Routing is per-DID and lives on the number detail view (and its API pair):

GET /api/v1/numbers/:id/fax-routing
PUT /api/v1/numbers/:id/fax-routing

Config shape:

{
  "enabled": true,
  "forward_emails": ["ap-invoices@example.com"],
  "deliver_to_inbox": true,
  "archive_path": "acme/ap-invoices"
}

Field	Notes
`enabled`	Master switch. A DID that has never been configured reads back as disabled, and received faxes land only as message records.
`forward_emails`	Up to 20 email recipients. Each received fax’s PDF is forwarded as an attachment to every address (a media-fetch failure degrades to a link-only email rather than dropping the delivery).
`deliver_to_inbox`	When true, each received fax opens an inbox ticket with sender/recipient/media metadata attached.
`archive_path`	Optional free-form label (≤256 chars) attached to forwarded faxes and inbox tickets for sorting.

Because a deliverable inbound fax only requires an HTTPS media_url on the webhook payload, everything below applies when routing is enabled; without routing the only record of the fax is the message row.

Webhook payload

Telnyx delivers inbound faxes to Orbit with this shape (fields Orbit consumes):

{
  "data": {
    "event_type": "fax.received",
    "payload": {
      "fax_id": "9a8b7c6d5e4f3g2h",
      "connection_id": "fax-conn-…",
      "from": "+14155552671",
      "to": "+18005551234",
      "media_url": "https://media.telnyx.com/…/fax.pdf",
      "status": "received"
    }
  }
}

from is the sender’s ANI, to is your DID, and media_url is the PDF of the received pages. Orbit stores the PDF into secure storage when routing email/inbox delivery needs the bytes, and the mailbox/ticket carries the download link or a link-only pointer when the bytes could not be fetched at that moment.

Download URL lifetime: media_url points at the carrier’s media store. The URL is a presigned, expiring link at ingest time — your downstream consumer (the email forwarder or inbox ticket) must fetch it promptly. Orbit’s email forwarder fetches within a 15-second window when routing is enabled; a missed fetch degrades to a link-only email, and once the link is expired the message row keeps the record but not the document bytes. Do not re-share the URL beyond your recipient list.

status: "received" confirms the carrier accepted the fax. Orbit’s dedup marker keys on the provider fax_id, so a Telnyx retry of the same fax.received event creates only one message row.

Retention

The message record of an inbound fax is retained like every other message row (no special purge). The carrier-issued media_url, however, expires on the carrier’s schedule — treat the media copy forwarded to email/inbox (or fetched by your webhook consumer) as the durable artifact, and the message row as the audit record.

Capabilities

Outbound fax — PDF or TIFF input; the carrier converts the document to T.38 packets in real time.
Inbound fax — received as PDF with sender ANI, recipient DID, and a download URL POSTed to your webhook; per-DID routing forwards the PDF to email and/or opens an inbox ticket.
Quality — normal, high, or very_high to control transmission resolution.
Document size — PDF or TIFF up to 50 MB per outbound fax (the carrier’s hard media-size limit); multi-page documents are supported, with no separate page-count cap.
Delivery status — outcomes arrive on the channel-agnostic message.delivered / message.failed webhook events with channel: "fax" (there is no separate fax.* event to subscribe to). Each payload carries message_id, status, state_class, and is_terminal for reconciliation.
Per-tenant carrier connection — orgs can attach a dedicated Telnyx Fax application connection for compliance / data-residency (resolution: tenant-level fax_connection_id → platform default → legacy voice connection fallback).

Status lifecycle

queued → sending → sent → delivered (or failed) Every outbound fax moves through the states below. A fax is single-attempt: it is never retried once it reaches failed. The queue worker re-dispatches the same send only while it is still queued (e.g. on a transient provider 408), and the stable idempotency key dedups the carrier side.

State	Meaning
`queued`	Message accepted by the API and waiting for a carrier line / queue slot.
`sending`	The T.38 handshake with the destination fax machine is in progress.
`sent`	The carrier confirmed the transmission reached the end station (all pages transmitted).
`delivered`	The end station acknowledged receipt. Carriers ack at different points: some promote to `delivered` immediately after transmission, others only after the receiving fax machine confirms the handshake’s final page. For fax, `delivered` is the stronger confirmation — prefer it for “the customer has it” and treat `sent` as “carrier-completed”.
`failed`	Any failure at any point (busy, no answer, no fax tone, poor line quality, handshake rejection, or an internal error before dispatch). Terminal.

failed is terminal and sent is non-terminal: a fax that shows sent will still receive delivered or failed when the carrier finishes negotiating with the end station.

Errors

A failed API request returns the standard JSON error envelope whose error.code is one of the values below.

Code	HTTP	Cause	Fix
`INVALID_PHONE_NUMBER`	422	`to` is not a valid E.164 phone number.	Verify the format `+<country><area><number>`.
`MISSING_REQUIRED_FIELD`	422	`from` or `media_url` was omitted — both are required for an outbound fax.	Supply a valid `from` fax number and a `media_url` pointing at the PDF or TIFF to send.
`VALIDATION_ERROR`	422	Another request field failed validation — most commonly `status_callback_secret` or `status_callback_events` with no `status_callback`, or a `metadata` value that is not a scalar.	Check `error.details` for the offending `field` name (or the `issues` array for extension-field problems).
`MESSAGE_SEND_FAILED`	502	The carrier rejected the dispatch at send time (account state, connection misconfiguration, or a non-retryable provider error).	Check `details.provider_message` for the sanitized provider text; verify your Telnyx Fax application connection and retry.

Carrier passthrough errors

A fax that is accepted but cannot be delivered is reported asynchronously on the message.failed webhook with the record marked failed. When the carrier supplies a diagnostic, Orbit passes it through unchanged in the error_code and error_message fields — these carry the carrier’s own text, not a fixed Orbit enum, so the exact set of values depends on the upstream carrier. Common diagnostics:

Carrier diagnostic	Remediation
`busy` / `no_answer`	The destination line was occupied or did not pick up. Resend later; confirm the recipient number with the customer.
`no_fax_tone` / `no fax tone`	The number answered but did not present a fax handshake — often a voice line misrouted, or a recipient that expects a manual receive.
`poor_line_quality`	The carrier detected too much noise to complete T.38. Resend at a lower `quality` (which shortens the handshake) or at a different hour.
`handshake_rejected` / other	The receiving machine rejected the T.38 session. Check whether the recipient is fax-reachable at all (fax machines, e-fax gateways).

When no carrier detail is available, the record simply reaches failed with no further reason. Failed faxes are never billed.

Limits

Limit	Value
File size	50 MB per outbound fax (carrier hard media-size limit)
Document type	PDF or TIFF (single file per send — multi-attachment faxes are not supported)
Multi-page	Supported; no separate page-count cap
Inbound recipients	Up to 20 `forward_emails` per DID
URL scheme	HTTPS only for `media_url`
Rate limit	Shares the unified messaging send surface; reads (`GET /api/v1/fax*`) are on the standard authenticated-read lane. There is no separate fax-limit bucket.
Webhook retry	Inbound `fax.received` dedups on the provider `fax_id`; inbound email forwarding per recipient is idempotent under `inbound-fax:<message-id>:<recipient>`. Failed transmissions are reported once on `message.failed`.

quality: very_high lengthens the T.38 handshake; on lossy lines it can tip a long fax into poor_line_quality failure. For high-volume fax, default to high and fall back to normal on long documents to lossy destinations.

Dashboard walkthrough

Fax read surfaces (GET /api/v1/fax, GET /api/v1/fax/:id, GET /api/v1/fax/:id/status) and both inbound/outbound routing live in the dashboard under Numbers → (pick your DID) for routing, and Messages → Fax (or the Messages list filtered by channel) for transmission history.

To attach a dedicated carrier connection (per-tenant Telnyx Fax application), set the org’s fax_connection_id in tenant settings — the send pipeline resolves it before the platform default, so all subsequent sends for that org route through your assigned Telnyx Fax application. Resolution order is: tenant fax_connection_id → platform default → legacy voice connection (fallback that logs a deprecation warning). To view inbound faxes and set up routing:

Open Numbers and pick the DID that should receive faxes.
Open the Fax routing card on the number detail page.
Enable Fax routing, add up to 20 forwarding recipients, and optionally toggle Open an inbox ticket.
(Optional) Set an Archive label to sort forwarded faxes.

Until routing is enabled, inbound faxes land as message records only — they appear in Messages → Fax but are not delivered to an inbox or email.

Common patterns

Idempotent send with metadata — attach a correlation key you can match on later webhook events:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/fax \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "media_url": "https://example.com/invoice.pdf",
    "metadata": { "order_id": "ord_123", "customer_ref": "cust_9" }
  }'

Poll status when the webhook isn’t available — use the status endpoint (cached ~10 seconds per provider call) after the provider-side external_id is attached:

curl -H "X-API-Key: dv_live_sk_..." \
  https://api.orbit.devotel.io/api/v1/fax/msg_a1b2c3d4e5f6g7h8/status

The route returns 404 until the transmission has been dispatched (external_id is null before then), so poll the detail route first if you just got the send response. Handling carrier passthrough errors — match error_code on message.failed and branch like:

busy / no_answer     → schedule a re-send
no_fax_tone          → prompt to verify destination is a fax
poor_line_quality    → resend at lower quality
(any other, or none) → surface to your reconciliation as `failed` terminal

Webhook events — the message.delivered / message.failed payloads and the channel-agnostic event contract.
Error codes — the JSON error envelope and error_code catalog.
Message failed troubleshooting — general guidance on diagnoses that close into terminal failure.
Webhook security — how to verify status_callback signatures with your per-send status_callback_secret.

Pricing

Per-page on success only. International rates vary by destination. See the pricing page.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Send and receive faxes on Orbit fax numbers

Fax

Send a fax

Request fields

Response

Receive an inbound fax

Routing a number’s inbound faxes

Webhook payload

Retention

Capabilities

Status lifecycle

Errors

Carrier passthrough errors

Limits

Dashboard walkthrough

Common patterns

Pricing

​Fax

​Send a fax

​Request fields

​Response

​Receive an inbound fax

​Routing a number’s inbound faxes

​Webhook payload

​Retention

​Capabilities

​Status lifecycle

​Errors

​Carrier passthrough errors

​Limits

​Dashboard walkthrough

​Common patterns

​Related

​Pricing

Fax

Send a fax

Request fields

Response

Receive an inbound fax

Routing a number’s inbound faxes

Webhook payload

Retention

Capabilities

Status lifecycle

Errors

Carrier passthrough errors

Limits

Dashboard walkthrough

Common patterns

Related

Pricing