Handle time-sensitive documents

Some faxes cannot wait. A prescription needs to reach the pharmacy before the patient leaves the office. A purchase order has to arrive before a supplier’s cutoff. A court filing is due by end of business. The fax will get there, but you need to minimize delivery time, know immediately when something goes wrong, and have a plan when it does. This guide covers what affects delivery speed, how to optimize for it, and how to build monitoring and fallback logic around urgent faxes.

What affects delivery time

Most faxes complete within 1-5 minutes. Four factors determine where in that range a given fax lands:

Factor	Impact
Page count	Each page is a separate T.30 transmission phase. Fewer pages = faster delivery.
File complexity	Dense images and complex layouts take longer to render. Simple PDFs render fastest.
Destination line	A clean line transmits quickly. Noise, poor connections, or old equipment slow it down.
Busy signals	If the recipient’s line is busy, the fax waits for a retry slot. You cannot skip this.

The analog PSTN leg is the bottleneck, not the API. mintfax queues and submits your fax within seconds. Everything after that depends on the phone network and the receiving machine. No API can make a fax machine answer faster or a phone line less noisy.

Optimize for speed

Three things you can control on your side: Keep documents short. If you are sending a 20-page contract but only the signature page is urgent, send the signature page first and the full document separately. Each page adds transmission time. Use PDF. mintfax accepts PDF, DOCX, XLSX, JPG, PNG, TIFF, HTML, and TXT (max 10 MB). PDF renders fastest because it requires no conversion. DOCX and HTML need server-side rendering before transmission, which adds a few seconds. Set an appropriate retry count. Retries are configurable from 0 to 10 (default 3). For truly urgent faxes, a lower retry count lets you fail fast and take manual action sooner. For faxes where delivery matters more than speed, keep the default or increase it.

# Send with 1 retry - fail fast so you can react
curl -X POST https://api.mintfax.com/v1/faxes \
  -H "Authorization: Bearer $MINTFAX_API_KEY" \
  -F "to=+12125551234" \
  -F "file=@prescription.pdf" \
  -F "retries=1"

Monitor delivery in real time

Subscribe to three webhook events to track urgent faxes:

Event	What it tells you
`fax.delivered`	The fax reached the recipient. Terminal state.
`fax.failed`	All attempts exhausted or a terminal error code returned. Terminal state.
`fax.sending`	A delivery attempt has started. Fires once per attempt, so retries are visible.

For urgent faxes, use the per-fax webhook_url override to route notifications to a dedicated handler instead of your default endpoint. This lets you process time-sensitive notifications on a separate queue with higher priority.

# Route this fax's webhooks to a dedicated urgent handler
curl -X POST https://api.mintfax.com/v1/faxes \
  -H "Authorization: Bearer $MINTFAX_API_KEY" \
  -F "to=+12125551234" \
  -F "file=@court-filing.pdf" \
  -F "retries=2" \
  -F "webhook_url=https://acme.com/webhooks/urgent-fax"

Build alerting around your threshold

Webhook events tell you when something happened. Alerting tells you when something has not happened yet. For time-sensitive faxes, you want to know if a fax has not reached a terminal state within your acceptable window. A simple pattern: when you submit an urgent fax, record the fax ID and a deadline. Run a periodic check (a cron job, a delayed queue job, or a scheduler) that flags any fax still in a non-terminal state past its deadline.

// When you send an urgent fax, schedule a deadline check
async function sendUrgentFax(to, filePath) {
  const res = await fetch("https://api.mintfax.com/v1/faxes", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MINTFAX_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      to,
      file_url: filePath,
      retries: 2,
      webhook_url: "https://acme.com/webhooks/urgent-fax",
    }),
  });

  const fax = await res.json();

  // Schedule a check 10 minutes from now
  await scheduleDeadlineCheck(fax.id, Date.now() + 10 * 60 * 1000);
  return fax;
}

// Deadline checker - runs periodically
async function checkDeadlines() {
  const overdue = await getOverdueFaxes(); // your DB query

  for (const entry of overdue) {
    const res = await fetch(
      `https://api.mintfax.com/v1/faxes/${entry.faxId}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.MINTFAX_API_KEY}`,
        },
      }
    );
    const fax = await res.json();

    if (fax.status !== "delivered" && fax.status !== "failed") {
      await alertOperator(fax); // page someone, send a Slack message, etc.
    }
  }
}

When the webhook fires with fax.delivered, clear the deadline entry. If the deadline checker finds a fax still in queued or sending status past your deadline, escalate.

Plan your fallback

When an urgent fax fails, you need a plan. Here are three options, in order of automation: 1. Resend via the API. If the failure was a busy signal or a temporary line issue, try again. Use POST /fax/{id}/resend to resubmit with the same parameters and a fresh retry cycle.

curl -X POST https://api.mintfax.com/v1/faxes/fax_01H7N9WXYZ/resend \
  -H "Authorization: Bearer $MINTFAX_API_KEY"

Use an idempotency key on the original send to prevent accidental duplicates if your own retry logic fires more than once. 2. Try an alternate number. If the recipient has a backup fax line, submit a new fax to that number. This is a new fax, not a resend, so it gets its own fax ID and retry cycle. 3. Alert a human. Some failures need a person. The recipient’s machine might be off, their line might be disconnected, or the number might be wrong. When automated retries are exhausted and alternate numbers have been tried, notify an operator who can call the recipient and confirm the number.

Set expectations

Fax is not email. The analog phone network is part of every fax delivery, and that leg introduces delays that no software can eliminate:

Busy lines require waiting and retrying. If a medical office receives dozens of faxes per hour, the line may be busy for minutes at a time.
Line quality varies. A noisy connection forces error correction (ECM) retransmissions that slow the process.
Receiving equipment matters. An old fax machine negotiates at 9600 bps. A modern FoIP gateway negotiates at 14400 bps. You cannot control what the recipient uses.

Build your application’s UX around this reality. Show users that the fax is in progress, show webhook-driven status updates, and set clear expectations about delivery windows. A promise of “delivered in under 30 seconds” will break. A promise of “you will know within minutes whether it worked” will hold.

What to do next

Webhooks - configure endpoints and per-fax overrides
Track delivery status - poll or stream fax status updates
Sandbox - simulate busy lines, failures, and retries with magic numbers
Errors - machine-readable error codes and next actions for failed faxes

Sending Faxes

Tracking Delivery

Going to Production

Integrations

Migration

Handle time-sensitive documents

What affects delivery time

Optimize for speed

Monitor delivery in real time

Build alerting around your threshold

Plan your fallback

Set expectations

What to do next

​What affects delivery time

​Optimize for speed

​Monitor delivery in real time

​Build alerting around your threshold

​Plan your fallback

​Set expectations

​What to do next

What affects delivery time

Optimize for speed

Monitor delivery in real time

Build alerting around your threshold

Plan your fallback

Set expectations

What to do next