Skip to main content
Fax

​
Definition

A Fax is a document that you want to send to one or more recipients using the Fax.Plus system. Faxes can be in various formats such as PDF, Word, Excel, and other common file types.

​
Key Concepts

​
Receiving a Fax

Fax.Plus can receive faxes on your behalf. In the default setup, faxes are delivered as fully received documents once the transmission is complete, with all pages included in a single file.
If you have a use case where you need to start processing pages as soon as they arrive, a fax streaming option (page‑by‑page delivery) is available on demand. Contact us to discuss enabling it for your account.

​
Sending a Fax

When sending a fax, you typically need to provide:
  1. One of your numbers that will be used as a source number
  2. The recipient’s fax number(s)
  3. The document(s) you want to send
  4. Any additional options (e.g., cover page, scheduling)
Each source number is subject to rate limiting based on your subscription. If you need to send more concurrent faxes than a single number allows, you can load‑balance by providing a comma‑separated list of allowed numbers in the from field. The platform will pick one per destination. See the Send a fax endpoint for details.
You can upload up to 10 different files per fax, regardless of the number of pages in each file. The maximum total file size is 150 MB. You can include up to 4000 destinations in a single fax request; for larger fan‑out jobs, split your recipients into multiple faxes. If you exceed these limits:
  • The API returns 413 Payload Too Large when the total size of all files in a fax exceeds 150 MB.
  • The API returns 400 Bad Request with an error code of too_many_files when more than 10 files are provided.
  • The API returns 400 Bad Request with an error code of too_many_destinations when the to list contains more than 4000 destinations.

​
File Formats

Fax.Plus supports a wide range of file formats, including:
  • Documents: DOC, DOCX, PDF, TXT, RTF
  • Images: JPG, PNG, TIFF
  • Spreadsheets: XLS, XLSX
Received faxes are available for download through the API in PDF and TIFF formats (depending on the endpoint and requested content type).

​
Cover Pages

You can optionally add a fax cover page when sending a fax. A cover page can include:
  • The sender and recipient names
  • A subject
  • A short message or note
You can also replace the default Fax.Plus logo in the upper‑right corner of the cover page with your account’s company logo. If no company logo is configured on the account, this flag is silently ignored. To learn how to configure cover sheets and upload your logo in the web app, see the “How can I add a cover sheet to my fax?” help article.

​
Fax Status

After sending a fax, you can track its status. The status indicates whether the fax was successfully sent, is still in progress, or encountered an error. You can use webhooks to receive real-time updates on fax transmission status.

​
Rate limits

Faxing is a comparatively slow operation: a single page typically takes around 30–60 seconds to transmit. Because of this, the Fax.Plus API does not enforce strict per-endpoint quotas under normal, reasonable usage. However, we do monitor for clearly abusive or unreasonable traffic patterns (for example, polling status every few hundred milliseconds or sending dozens of requests per second). In such cases we may start rate-limiting or throttling requests to protect the platform. Recommendations:
  • Design your integration around the natural pace of faxing (batch sends are fine, but avoid very tight polling loops).
  • Prefer webhooks for status updates instead of frequent polling of fax or outbox endpoints.
  • Ensure your files are not corrupted or password-protected before sending.
  • If you expect a large migration or unusually high one-time load, contact us so we can plan capacity together.

​
Retries

Retries are configured per submission when sending a fax. For a detailed view of the retry options available in the request payload, check the Send a fax API reference.
  • count: Number of tries to send the fax. Allowed range: 0–3.
  • delay: Delay in seconds between two retries. Allowed range: 0–180.
By default, when a retry happens the fax is resent starting from page 1. If you enable the “partially sent retry” option, retries resume from where the previous attempt stopped instead of starting over. When using partially sent retries, make sure the remote side can accept “chunked” submissions: from their perspective, the retransmitted pages may look like a separate fax.

​
Fax Error Statuses

Fax.Plus uses a variety of error status codes to indicate the current state of a fax. Here are the possible statuses and their meanings:
StatusDescription
successThe fax was successfully sent.
partially_sentThe first pages were transmitted, but the call dropped due to connection issues.
partially_receivedThe first pages were received, but the call dropped due to connection issues.
in_progressThe fax is currently being received ; you can retrieve some pages via the API, or wait for the final status.
insufficient_creditNot enough credit to send or receive pages. Add credit or wait for plan reset.
failedGeneric error. Retry, and contact support if the issue persists.
failed_internal_process_errorGeneric error. Retry, and contact support if the issue persists.
failed_user_busyThe destination was busy. Wait and retry.
failed_no_answerNo answer at the destination. Retry when you know the recipient is available.
failed_unallocated_numberInvalid number. Check the number, including country and area codes.
failed_office_converter_issueFailed to convert Microsoft Office document. Recreate and resubmit the file.
failed_separate_file_pages_issueFile conversion issue. Check if all pages in the source file(s) are valid.
failed_render_header_issueFile conversion issue. Check if all pages in the source file(s) are valid.
failed_invalid_number_formatInvalid number format. Check the number, including country and area codes.
failed_mimetype_not_supportedUnsupported file type.
failed_destination_not_supportedNumber is a special service number or not supported by your plan.
failed_image_preparationFile conversion issue. Check if all pages in the source file(s) are valid.
failed_to_sendSystem was busy. Try again later.
failed_normal_temporary_failureTemporary network issue. Retry immediately.
failed_unknown_converter_issueFile conversion failed. Check if the file is password-protected.
failed_normal_clearingDestination was busy. Wait and retry.
failed_convert_to_tiff_issueFile conversion issue. Check if all pages in the source file(s) are valid.
failed_fs_2 / failed_fs_3The call was established, but there was no fax machine responding to the call. Check the number and retry.
failed_fs_8 / failed_fs_9Fax protocol incompatibility between the two endpoints. Check that the recipient is using a standard fax machine or service, and retry.
failed_fs_31 / failed_fs_32The remote fax stopped responding during the call (for example, due to line issues or device lockups). Retry later; if the issue persists, contact the recipient.
failed_fs_35 / failed_fs_39The remote fax disconnected unexpectedly or hung up before the transmission completed. Retry later; if the issue persists, contact the recipient.
failed_fs_48Remote fax machine disconnected after the same message was sent multiple times unsuccessfully. Some pages may have been transmitted.
failed_fs_49Remote fax machine disconnected unexpectedly. Some pages may have been transmitted.
failed_fs_*Fax communication error (for example, line quality, timeouts, or other low-level fax protocol issues). Retry later; if the issue persists, contact support and include the fax ID.

​
Best Practices

  1. File Preparation: Ensure your files are not corrupted or password-protected before sending.
  2. Number Verification: Double-check fax numbers, including country and area codes.
  3. Retry Strategy: For temporary failures, implement a retry mechanism with appropriate intervals.

​
Schema

​
comment
string
required

Free-form comment

​
cost_details
object
required
​
id
string
required

Fax ID

​
owner_id
string
required

User ID of the fax owner

​
pages
integer
required

Number of pages in the fax

Required range: x >= 0
​
status
enum<string>
required

Fax status. Some failure codes use failed_fs_* values which represent low-level fax transport issues (for example, fax protocol incompatibility, the remote endpoint stopping responding, or remote disconnections). In particular: failed_fs_8/failed_fs_9 indicate protocol incompatibility; failed_fs_31/failed_fs_32 indicate that the remote stopped responding; failed_fs_35/failed_fs_39 indicate that the remote disconnected.

Available options:
success,
partially_sent,
partially_received,
in_progress,
insufficient_credit,
failed,
failed_internal_process_error,
failed_user_busy,
failed_no_answer,
failed_unallocated_number,
failed_office_converter_issue,
failed_separate_file_pages_issue,
failed_render_header_issue,
failed_invalid_number_format,
failed_mimetype_not_supported,
failed_destination_not_supported,
failed_image_preparation,
failed_to_send,
failed_normal_temporary_failure,
failed_unknown_converter_issue,
failed_normal_clearing,
failed_convert_to_tiff_issue,
failed_fs_2,
failed_fs_3,
failed_fs_8,
failed_fs_9,
failed_fs_31,
failed_fs_32,
failed_fs_35,
failed_fs_39,
failed_fs_48,
failed_fs_49
​
cost
integer

Fax cost in the user currency

Required range: x >= 0
​
description
string
​
direction
enum<string>

Fax direction

Available options:
outgoing,
incoming
​
duration
integer

Fax transmission duration in seconds

Required range: x >= 0
​
file
string

Fax file ID for the getFile handle

​
file_name
string

Human-readable file name

​
from
string

Sender number. Might be a userId for faxes sent or received with free accounts

​
header
string
​
is_read
boolean
​
is_spam
boolean

True if the fax is marked as spam

​
last_update
string
​
max_retry
integer

Maximum number of retries

Required range: 0 <= x <= 3
​
retry_delay
integer

Delay between two retries

Required range: 0 <= x <= 180
​
scheduled_time
string
​
start_time
string

Time at which faxing session started. Format: YYYY-MM-DD HH:mm:ss

​
submit_time
string

Time when the fax was submitted for sending. For outgoing faxes only

​
to
string

Fax destination number. Might be a userId for faxes sent or received with free accounts

​
cover_page
object

Fax cover page