Documentation Index
Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
How fax works
What it is
Fax transmission is a decades-old protocol for sending page images over phone lines. At its core, two machines negotiate capabilities, compress a page into a bitstream, transmit it, confirm receipt, and hang up. The process is governed by the T.30 recommendation from the ITU-T, which defines every phase of a fax call. When you send a fax through mintfax, the carrier handles the T.30 session on your behalf, but the protocol’s phases directly determine the statuses, errors, and timing you observe through the API.Why it matters
Understanding the protocol removes the mystery from fax delivery. When a fax fails, the failure has a specific cause rooted in a specific protocol phase - a busy signal during call setup, a capability mismatch during negotiation, a line error during page transmission. The mintfax API exposes these causes through T.30 diagnostic codes in theerror_code and error_message fields of a fax record. Knowing what those phases are helps you write better error handling, build smarter retry logic, and diagnose delivery problems without guessing.
How it works
The T.30 call lifecycle
A T.30 fax session has five phases. They always happen in the same order. Phase A - Call setup. The sending machine dials the recipient’s number. The recipient answers and emits a CED tone (a 2100 Hz tone that signals “this is a fax machine”). This is a standard phone call at this point - analog signaling over the public switched telephone network (PSTN). If the line is busy, no one answers, or a human picks up instead of a fax machine, the session ends here. In the mintfax API, a fax that fails during call setup moves tofailed with an error code indicating the specific cause (busy, no answer, no fax tone detected).
Phase B - Capability negotiation. Once both sides confirm they are fax machines, the receiver sends a DIS frame (Digital Identification Signal) that advertises its capabilities: supported resolutions, encoding methods, page widths, and whether it supports ECM (error correction mode). The sender evaluates this against its own capabilities, picks the best mutually supported options, and responds with a DCS frame (Digital Command Signal) that locks in the session parameters. This negotiation determines the resolution (standard 204x98 dpi or fine 204x196 dpi), the compression encoding, and whether ECM will be used. If the two machines cannot agree on any compatible settings, the session fails here.
Phase C - Training and page transmission. Before sending page data, the sender transmits a short training sequence - a known bit pattern that lets the receiver calibrate its modem to the line conditions and confirm it can decode at the negotiated speed. If training fails, the sender may fall back to a slower speed and try again.
Once training succeeds, the sender transmits the page image as a compressed bitstream. The page has already been encoded using one of several compression schemes:
- MH (Modified Huffman) - the baseline encoding required by all fax machines. It compresses each scan line independently using run-length encoding. Simple and universal, but the least efficient.
- MR (Modified READ) - compresses each line relative to the previous line, achieving better ratios for pages where adjacent lines are similar (which is most pages of text).
- MMR (Modified Modified READ) - a further refinement of MR that removes some redundancy overhead. Requires ECM because a single bit error can corrupt all subsequent lines.
- JBIG - a more modern compression standard that achieves significantly better ratios, especially for halftone images and photographs. Supported by newer machines but not universal.
- MCF (Message Confirmation) - the page was received successfully.
- RTN (Retrain Negative) - the page had errors and should be retransmitted after retraining at a lower speed.
- RTP (Retrain Positive) - the page was accepted, but line quality has degraded and the sender should retrain before continuing.
delivered.
How fax travels over IP networks
Traditional fax runs over analog phone lines, but most modern phone infrastructure is digital. This creates a problem: fax modulation is sensitive to the compression and packet loss that IP networks introduce. Two approaches handle this. G.711 pass-through treats the fax signal as ordinary audio. The fax tones are encoded into a G.711 audio stream and carried across the IP network the same way a voice call would be. This works, but it is fragile - any jitter, packet loss, or transcoding along the path can corrupt the fax signal. G.711 pass-through is a fallback, not a preferred path. T.38 is a protocol designed specifically for fax over IP (FoIP). Instead of carrying the raw fax audio, T.38 gateways decode the T.30 signals at the network edge, extract the actual fax data (pages, control signals, negotiation frames), and relay them as structured T.38 packets across the IP network. A T.38 gateway on the other end reconstructs the T.30 session for delivery to the receiving fax machine. Because T.38 carries data rather than audio, it is far more tolerant of IP network conditions. T.38 also includes redundancy mechanisms - each packet can carry copies of previous packets to compensate for loss without retransmission. Carriers typically prefer T.38 when both endpoints support it and fall back to G.711 pass-through when they do not. From the mintfax API’s perspective, the transport method is invisible - you see the same statuses and error codes regardless of whether the carrier used T.38 or G.711.How the protocol maps to the mintfax API
When you submit a fax viaPOST /fax, mintfax returns a 201 response with a fax ID and a status of queued. From that point, the fax moves through statuses that reflect the protocol lifecycle:
| Status | What is happening |
|---|---|
queued | The fax is accepted and waiting to be picked up for carrier submission. |
submitted | The fax has been sent to the carrier. The carrier is initiating the T.30 call (Phase A). |
in_progress | The carrier has established a connection. Negotiation, training, and page transmission are underway. |
delivered | All pages were transmitted and confirmed (MCF received for each). Session teardown is complete. |
failed | The fax could not be delivered. The error_code field carries the T.30 diagnostic code. |
error_code and error_message fields on the fax record, giving you protocol-level detail for every failure. This is the information you need to decide whether a retry is worthwhile: a busy signal suggests trying again in a few minutes, while an incompatible-machine error will fail every time.
You can test your error handling logic without waiting for real protocol failures. The mintfax sandbox provides magic test numbers that simulate specific outcomes - +15005550001 always delivers, +15005550002 returns a busy signal, +15005550005 produces a permanent failure. See the sandbox documentation for the full test number matrix.
For faxes sent to international destinations, the same protocol lifecycle applies. T.30 is a global standard, and the statuses and error codes you receive are consistent regardless of the destination country.
Related reading
- Glossary - definitions for T.30, T.38, ECM, FoIP, and other fax terminology
- Sandbox - test fax delivery with magic numbers that simulate protocol outcomes
- International dialing - E.164 formatting and country-specific considerations