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:

One of your numbers that will be used as a source number
The recipient’s fax number(s)
The document(s) you want to send
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

Meanings for status on fax records and the list-faxes status filter.

Status	Description
success	The fax was successfully sent.
partially_sent	The first pages were transmitted, but the call dropped due to connection issues.
partially_received	The first pages were received, but the call dropped due to connection issues.
in_progress	The fax is currently being received ; you can retrieve some pages via the API, or wait for the final status.
insufficient_credit	Not enough credit to send or receive pages. Add credit or wait for plan reset.
failed	Generic error. Retry, and contact support if the issue persists.
failed_internal_process_error	Generic error. Retry, and contact support if the issue persists.
failed_user_busy	The destination was busy. Wait and retry.
failed_no_answer	No answer at the destination. Retry when you know the recipient is available.
failed_unallocated_number	Invalid number. Check the number, including country and area codes.
failed_office_converter_issue	Failed to convert Microsoft Office document. Recreate and resubmit the file.
failed_separate_file_pages_issue	File conversion issue. Check if all pages in the source file(s) are valid.
failed_render_header_issue	File conversion issue. Check if all pages in the source file(s) are valid.
failed_invalid_number_format	Invalid number format. Check the number, including country and area codes.
failed_mimetype_not_supported	Unsupported file type.
failed_destination_not_supported	Number is a special service number or not supported by your plan.
failed_image_preparation	File conversion issue. Check if all pages in the source file(s) are valid.
failed_to_send	System was busy. Try again later.
failed_origination_unknown	Call could not be originated due to an unexpected telephony response. Retry later; if it persists, contact support and include the fax ID.
failed_no_origination	The call could not be originated. Retry later.
failed_no_user_response	No response from the destination during call setup. Retry when the recipient is available.
failed_call_rejected	The destination rejected the call. The number may be blocked.
failed_exchange_routing_error	Carrier routing error during call setup. Retry later.
failed_no_route_destination	No route to the destination. Check the number, including country and area codes.
failed_normal_circuit_congestion	The network was congested. Retry later.
failed_recovery_on_timer_expire	Call setup timed out. Retry later.
failed_requested_chan_unavail	No channel was available to place the call. Retry later.
failed_network_out_of_order	Network outage during call setup. Retry later.
failed_destination_out_of_order	The destination appears out of service. Retry later; if it persists, contact the recipient.
failed_normal_temporary_failure	Temporary network issue. Retry immediately.
failed_unknown_converter_issue	File conversion failed. Check if the file is password-protected.
failed_normal_clearing	Destination was busy. Wait and retry.
failed_convert_to_tiff_issue	File conversion issue. Check if all pages in the source file(s) are valid.
failed_fs_2 / failed_fs_3	The call was established, but there was no fax machine responding to the call. Check the number and retry.
failed_fs_8 / failed_fs_9	Fax 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_32	The 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_39	The remote fax disconnected unexpectedly or hung up before the transmission completed. Retry later; if the issue persists, contact the recipient.
failed_fs_48	Remote fax machine disconnected after the same message was sent multiple times unsuccessfully. Some pages may have been transmitted.
failed_fs_49	Remote 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

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

Schema

comment

string

required

Free-form comment

cost_details

object

required

Show child attributes

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

See Fax Error Statuses for the full list and meanings.

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_origination_unknown,

failed_no_origination,

failed_no_user_response,

failed_call_rejected,

failed_exchange_routing_error,

failed_no_route_destination,

failed_normal_circuit_congestion,

failed_recovery_on_timer_expire,

failed_requested_chan_unavail,

failed_network_out_of_order,

failed_destination_out_of_order,

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

string

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

cover_page

object

Fax cover page

Show child attributes

Get Started

MCP

Concepts

SDKs

API Reference

Definition

Key Concepts

Receiving a Fax

Sending a Fax

File Formats

Cover Pages

Fax Status

Rate limits

Retries

Fax Error Statuses

Best Practices

Schema

​Definition

​Key Concepts

​Receiving a Fax

​Sending a Fax

​File Formats

​Cover Pages

​Fax Status

​Rate limits

​Retries

​Fax Error Statuses

​Best Practices

​Schema

Definition

Key Concepts

Receiving a Fax

Sending a Fax

File Formats

Cover Pages

Fax Status

Rate limits

Retries

Fax Error Statuses

Best Practices

Schema