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.

Before you build file upload into your integration, it helps to know which formats mintfax accepts, how each one gets converted for transmission, and what to watch for. Fax is a black-and-white medium with fixed resolution, so not every document that looks good on screen will look good on paper at the other end.

​
Supported formats

mintfax accepts these file types on POST /fax via multipart/form-data:
FormatExtensionTypical use caseConversion notes
PDF.pdfInvoices, contracts, formsMost common format. Renders predictably. Best choice for most workflows.
TIFF.tiffScanned documents, fax archivesNative fax format. No conversion needed - most predictable output.
DOCX.docxWord documentsConverted server-side. Layout may shift if the document relies on fonts not available during rendering.
XLSX.xlsxSpreadsheetsConverted server-side. Wide sheets may be scaled or clipped. Keep columns narrow.
JPG.jpgPhotos, scanned pagesConverted to black-and-white. High-contrast images work best.
PNG.pngScreenshots, diagramsConverted to black-and-white. Transparent regions render as white.
HTML.htmlGenerated reports, templatesRendered server-side. Keep markup simple - external stylesheets and images are not fetched.
TXT.txtPlain text contentRendered in a monospace font. No formatting beyond line breaks.
All files are converted to fax-compatible TIFF for transmission. If you retrieve a sent fax image later via GET /fax/{id}/image, the response is always TIFF regardless of the original upload format.

​
Color and resolution

Fax is a black-and-white medium. Color content is converted to grayscale, then dithered to black-and-white for transmission. This means:
  • Photos lose most detail. A color photo of a building becomes a high-contrast blob. Avoid faxing photographs unless they are already high-contrast.
  • Charts and diagrams work well if they use solid fills and thick lines. Thin hairlines and subtle color distinctions may disappear.
  • Text renders clearly at both resolution levels.
mintfax supports two fax resolutions, negotiated automatically with the receiving machine:
ResolutionDPIBest for
Standard204 x 98Text documents, simple forms
Fine204 x 196Small text, detailed diagrams, barcodes
You do not choose the resolution - the sending and receiving machines negotiate the highest resolution both support. Most modern fax machines support fine resolution.

​
Size limits

Each file upload is limited to 10 MB. This is the raw file size, not the rendered page count. How many pages fit in 10 MB depends on the format and content:
  • A text-heavy PDF is typically 50-100 KB per page. You can fit 100+ pages under the limit.
  • A scanned PDF with embedded images might be 1-2 MB per page. You will hit the limit at 5-10 pages.
  • A high-resolution photograph could be several MB on its own.
If your workflow routinely generates large files, validate the file size before calling the API. There is no benefit to uploading a file only to receive a 422 back.

​
Sending a file

Files are uploaded via multipart/form-data on POST /fax: 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "to=+12125551234" \
  -F "file=@invoice.pdf"
The file field accepts any of the supported formats listed above. mintfax detects the format from the file content, not the extension.

​
What happens when things go wrong

All file-related errors return HTTP 422 with the validation_failed error code. The context.errors object tells you exactly what went wrong. File too large: 
{
  "error": "validation_failed",
  "message": "The file must not be greater than 10240 kilobytes.",
  "action": "fix_request",
  "docs": "https://mintfax.com/docs/errors/validation-failed",
  "context": {
    "errors": {
      "file": ["The file must not be greater than 10240 kilobytes."]
    }
  }
}
Unsupported format: 
{
  "error": "validation_failed",
  "message": "The file must be a supported document type.",
  "action": "fix_request",
  "docs": "https://mintfax.com/docs/errors/validation-failed",
  "context": {
    "errors": {
      "file": ["The file must be a supported document type."]
    }
  }
}
In both cases, fix the issue and resubmit. These are synchronous validation errors - you will get the response immediately, before any credits are held.

​
Best practices

  • Prefer PDF. It renders the most predictably across all fax machines. If you can generate a PDF instead of sending a DOCX, do that.
  • Validate before sending. Check file size and format on your side before making the API call. A quick client-side check saves a round trip.
  • Keep page count low for speed. A 2-page fax transmits in under a minute. A 50-page fax takes considerably longer and has more opportunities for a line drop mid-transmission.
  • Test with representative documents. Use the sandbox to send the same types of files your integration will handle in production. If your users upload scanned images, test with scanned images - not just clean PDFs.
  • Watch for font issues in DOCX/XLSX. Server-side rendering uses a standard font set. If your documents rely on custom or unusual fonts, the layout may shift. Convert to PDF first if exact layout matters.
  • Simplify HTML. The server-side renderer does not fetch external resources (stylesheets, images, fonts). Inline everything or switch to PDF.

​
What to do next

  • Quickstart - send your first test fax in the sandbox.
  • Error catalog - all error codes, HTTP statuses, and recommended actions.
  • Sandbox - magic numbers and simulated failure scenarios for integration testing.