Outbound fax workflow

The Fax channel page covers the channel’s request fields, error codes, and limits. This guide is the send-side walkthrough: from a document URL to a delivered fax, including how billing, receipts, and retries behave along the way. The receive side is covered separately in Inbound fax routing. You will:

Understand how the channel terminates
Understand the on-success-charge model
Send a fax
Consume delivery receipts and handle failures
Choose the right document format and quality

Prerequisites

A fax-capable number on your account (see Buy numbers). The from field on every send must be one of your numbers.
An API key from Settings → API Keys (a dv_live_sk_… live key).
A publicly reachable HTTPS URL for the document you are sending. The carrier fetches it directly — Orbit does not re-host it — so the URL must resolve from the public internet, and http:// is rejected at send time.
A public HTTPS endpoint if you want per-send delivery callbacks (status_callback). Without one, outcome events reach your tenant-wide event bus subscribers anyway.

1. How outbound fax terminates

Outreach channels on Orbit are terminated deliberately. Voice calls and SMS exit only via the Devotel wholesale softswitch. Fax (T.38/G.711) and MMS are the two named exceptions: fax transmissions terminate on Telnyx Programmable Fax. When you send a fax, Orbit dispatches your document to the Telnyx fax connection resolved for your org — a tenant-assigned connection if you attached one in tenant settings, otherwise the platform default. That split matters operationally in two places:

Billing is on Telnyx carrier confirmations (section 2), not on the softswitch call detail records your voice traffic generates.
Failure diagnostics come from the carrier’s own vocabulary — busy, no answer, no fax tone, poor line quality — and Orbit passes them through unchanged (section 4).

If your org needs a dedicated Telnyx Fax application (compliance, data residency), set the tenant’s fax_connection_id in tenant settings; all subsequent sends resolve that connection before the platform default.

2. The on-success-charge model

A fax is only billed when the carrier confirms successful transmission. If the attempt fails — busy, no answer, no fax tone, poor line quality, handshake rejection, or an internal error before dispatch — your wallet is not charged for it. The mechanics:

Accepted — POST /api/v1/messages/fax validates and records the message. Nothing is billed at this point.
Transmitting — the carrier runs the T.38 handshake and transmits pages. Still nothing billed.
Carrier verdict — when the carrier confirms the transmission succeeded, the charge is applied and the message moves to delivered. Any path ending in failed is free.

A side effect worth knowing: the balance ledger for a fax settles asynchronously. The send response shows no charge yet; the wallet deduction appears when the carrier’s success confirmation lands, alongside the delivered event. The per-send idempotency key (orbit-fax:<message-id>) dedups at the carrier, so a client retry or a queue-worker re-dispatch of the same message record can never double-bill you.

3. Send a fax

Sending goes through the unified Messaging API at POST /api/v1/messages/fax:

curl -X POST https://api.orbit.devotel.io/api/v1/messages/fax \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "media_url": "https://files.example.com/contracts/acme-4821.pdf",
    "quality": "high",
    "status_callback": "https://www.example.com/webhooks/fax",
    "status_callback_secret": "my-per-send-signing-secret",
    "metadata": { "contract_id": "ct_4821", "customer_ref": "cust_9" }
  }'

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// No typed fax helper in the Node SDK — reach the channel endpoint
// through the generic request escape hatch.
const message = await orbit.request<{
  data: { id: string; status: string };
}>('POST', '/messages/fax', {
  to: '+14155552671',
  from: '+18005551234',
  media_url: 'https://files.example.com/contracts/acme-4821.pdf',
  quality: 'high',
  status_callback: 'https://www.example.com/webhooks/fax',
  status_callback_secret: 'my-per-send-signing-secret',
  metadata: { contract_id: 'ct_4821', customer_ref: 'cust_9' },
});

console.log(message.data.id);      // msg_a1b2c3d4e5f6g7h8
console.log(message.data.status);  // 'queued'

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# No typed fax helper in the Python SDK — the generic request escape
# hatch carries the full field set.
message = client.request(
    "POST",
    "/messages/fax",
    json_body={
        "to": "+14155552671",
        "from": "+18005551234",
        "media_url": "https://files.example.com/contracts/acme-4821.pdf",
        "quality": "high",
        "status_callback": "https://www.example.com/webhooks/fax",
        "status_callback_secret": "my-per-send-signing-secret",
        "metadata": {"contract_id": "ct_4821", "customer_ref": "cust_9"},
    },
)

print(message["data"]["id"])       # msg_a1b2c3d4e5f6g7h8
print(message["data"]["status"])   # 'queued'

The response:

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

The returned data.id is the Orbit message ID you correlate on — webhook events carry the same message_id, so no provider-side mapping is needed. The provider fax ID attaches asynchronously as external_id and is readable via GET /api/v1/fax/:id. Validation errors surface at send time, not after: an invalid E.164 to returns 422 INVALID_PHONE_NUMBER, a missing from or media_url returns 422 MISSING_REQUIRED_FIELD, and an orphaned status_callback_secret (set with no status_callback URL) returns 422 VALIDATION_ERROR. The full field table and error catalogue are on the Fax channel page.

status_callback is a per-send override. When you set it, delivery events for this message POST to that URL instead of only the tenant event bus. Pair it with status_callback_secret — the secret signs every callback to the URL, and Webhook security shows the verification recipe.

4. Delivery receipts and failure handling

An outbound fax moves queued → sending → sent → delivered (or failed). Each transition emits a channel-agnostic event — message.delivered or message.failed with channel: "fax" (there is no separate fax.* event stream). The event payload carries message_id, status, state_class, and is_terminal. Subscribe per the events catalogue. Two terminal-read differences from SMS semantics:

sent is non-terminal for fax. The carrier has completed transmission to the end station, but the receiving fax machine may still be confirming the final pages. Treat sent as “carrier-completed” and wait for delivered before telling a customer “they have it.”
failed is single-attempt. Orbit never retries a fax that has reached failed; re-sending is your call. The queue worker only re-dispatches a message that is still queued (e.g. a transient provider 408), and the carrier idempotency key prevents any duplicate transmission from that re-dispatch.

Failure-handling recipe

Match error_code on message.failed events — the values are the carrier’s own diagnostics, passed through unchanged:

async function onMessageFailed(event) {
  const { message_id, channel, error_code } = event.data;
  if (channel !== 'fax') return;

  switch (error_code) {
    case 'busy':
    case 'no_answer':
      // Destination line occupied or unanswered — schedule a re-send
      // after a delay; the recipient's fax line may be busy.
      await scheduleResend(message_id, { afterMinutes: 15 });
      break;
    case 'no_fax_tone':
      // The number answered as a voice line — confirm the destination
      // actually terminates a fax machine before re-sending.
      await flagDestinationForReview(message_id);
      break;
    case 'poor_line_quality':
      // Resend at a lower quality setting — a shorter T.38 handshake
      // survives noisier lines.
      await scheduleResend(message_id, { quality: 'normal' });
      break;
    default:
      // Carrier gave no diagnostic, or an internal error — surface to
      // reconciliation; the attempt was not billed.
      await recordTerminalFailure(message_id, error_code);
  }
}

Whichever consumer you build:

Verify the X-Orbit-Signature header and reject deliveries older than five minutes (Webhook security).
Return 2xx quickly; only 2xx counts as delivered, and retries continue for anything else.
Deduplicate on the event data.id — delivery is at-least-once.

If webhooks are unavailable, poll GET /api/v1/fax/:id/status (cached about 10 seconds) — note it returns 404 until the transmission has been dispatched, so poll GET /api/v1/fax/:id for the record first if you just got the send response.

5. PDF vs TIFF and picking a quality

The carrier accepts PDF or TIFF, single file, up to 50 MB. Multi-page documents are supported with no separate page-count cap.

PDF is the right default for everything business-generated: contracts, invoices, forms, letterheads. Text stays crisp at every resolution and file sizes are small.
TIFF is for faxes composed of scanned image pages — a scanned wet-signature or a photographed document. If your source is a scan, TIFF avoids a lossy image-through-PDF round trip, but a generated PDF still beats TIFF on size and handshaking stability.

The quality field trades resolution against handshake length:

Value	Behavior
`normal` (default)	Shortest T.38 handshake; most tolerant of lossy lines. Fine for plain text documents.
`high`	Better legibility for small text and fine graphics. The right default for documents with tables or signatures.
`very_high`	Artwork-grade resolution. Lengthens the handshake and can tip a long fax into `poor_line_quality` on bad lines — use it only when the detail is genuinely needed.

Practical rule: start at high, and on a poor_line_quality failure re-send at normal — the workflow in section 4 already encodes that fallback.

Next steps

Fax channel — field reference, status lifecycle, error codes, and limits
Inbound fax routing — the receive side: per-DID routing to email and the inbox
Webhook consumer — reliable endpoint design
Webhook security — signature verification recipes (org and per-send secrets)
Message failed troubleshooting — general failure diagnosis

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Outbound fax: send a document end to end

Outbound fax workflow

Prerequisites

1. How outbound fax terminates

2. The on-success-charge model

3. Send a fax

4. Delivery receipts and failure handling

Failure-handling recipe

5. PDF vs TIFF and picking a quality

Next steps

​Outbound fax workflow

​Prerequisites

​1. How outbound fax terminates

​2. The on-success-charge model

​3. Send a fax

​4. Delivery receipts and failure handling

​Failure-handling recipe

​5. PDF vs TIFF and picking a quality

​Next steps

Outbound fax workflow

Prerequisites

1. How outbound fax terminates

2. The on-success-charge model

3. Send a fax

4. Delivery receipts and failure handling

Failure-handling recipe

5. PDF vs TIFF and picking a quality

Next steps