Skip to main content

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.

​
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 land 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:
FactorImpact
Page countEach page is a separate T.30 transmission phase. Fewer pages = faster delivery.
File complexityDense images and complex layouts take longer to render. Simple PDFs render fastest.
Destination lineA clean line transmits quickly. Noise, poor connections, or old equipment slow it down.
Busy signalsIf 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/fax \
  -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:
EventWhat it tells you
fax.deliveredThe fax reached the recipient. Terminal state.
fax.failedAll retries exhausted. Terminal state.
fax.retry_scheduledA delivery attempt failed but retries remain. Still in flight.
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/fax \
  -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/fax", {
    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/fax/${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, sending, or retry_scheduled status, 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/fax/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, surface 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