Send fax

Submit a fax to a single destination number.

The submitted document needs to be of a supported file type. For a list of supported MIME types, see the helper method GET /outbound/help/mediatype.

POST /outbound/faxes?faxNumber={faxnumber}[&contact={string}&postponeTime={datetime}&retriesToPerform={number}&csid={string}&pageHeader={string}&reference={string}&replyAddress={email}&pageSize={a4|letter|legal|b4}&fitToPage={scale|noscale}&pageOrientation={portrait|landscape}&resolution={fine|standard}&rendering={greyscale|bw}]

Arguments

Name (bold if mandatory) Type Comments Default value on POST
faxNumber FaxNumber A single fax number, e.g: +1-212-3456789. None, mandatory value
contact String A name or other reference. The entered string will appear: (1) for reference in the outbound queue; (2) in the outbound fax header, if headers are configured; and (3) in subsequent queries of the fax object. Null
postponeTime DateTime Time to schedule the transmission. No postponement
retriesToPerform Number Number of transmission attempts to perform, in case of fax transmission failure. Taken from control panel settings
csid String (up to 20 characters) Sender CSID. Taken from control panel settings
pageHeader String The fax header text to insert at the top of the page. Enter a string template to send a fax with a dynamically-populated header. For placeholder documentation, see your online settings under Preferences -> Outgoing -> Header Properties. For example, in the string To: {To} From: {From} Pages: {TotalPages} the placeholders {To}, {From}, and {Pages} will be populated by their respective values.
Enter N to override any control panel settings.
Taken from control panel settings
reference String (up to 60 characters) Provide your internal ID to a document. This parameter can be obtained by status query, but is not included in the transmitted fax message. Null
replyAddress Email E-mail address to which feedback messages will be sent. Taken from control panel settings
pageSize String a4, letter, legal, or b4. Taken from control panel settings
fitToPage String scale or noscale. Scale (enlarge or reduce) an image file to the given page size. Taken from control panel settings
pageOrientation String portrait or landscape. Taken from control panel settings
resolution String standard or fine. Documents rendered as fine may be more readable but take longer to transmit (and may therefore be more costly). Taken from control panel settings
rendering String greyscale or bw. Determines the rendering mode. bw is recommended for textual, black & white documents, while greyscale is better for greyscale text and for images. Taken from control panel settings

Request content

Faxing a single document

When faxing a single document the system accepts any one of the approaches to submitting content detailed below, submitted as a single content element (that is, not multipart), for example:


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/msword
 
{binary content goes here}

Faxing multiple documents

When faxing more than one document, the system accepts any one of the approaches to submitting content detailed below, where each document to be faxed is a single content part of multipart content. Any number of documents may be attached (subject to system-wide limitations on total file size, maximum page count, etc.). For example:


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Content-Type: multipart/mixed; boundary=265001916915724
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

--265001916915724
Content-Type: application/pdf

{content 1 goes here}

--265001916915724
Content-Type: application/msword

{content 2 goes here}

--265001916915724--

Approaches to submitting content

InterFAX accepts several ways of submitting documents for sending:

  1. Inserting a document as inline content (e.g., application/msword or application/pdf).
  2. Pointing to a previously uploaded document by using custom headers.
  3. Pointing to an external URL.

These are detailed below.

Inserting a document as inline content


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Content-Type: application/msword
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{content goes here}

Pointing to a previously-uploaded document

This is done by using a standard Content-Location header, which provides the resource location of a previously-uploaded document (e.g., https://rest.interfax.net/outbound/documents/6a58b45c8). To clarify, in this case no content is actually provided, only headers are supplied. Note that there is no need to supply a Content-Type header as this was already supplied at upload time.


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Location: https://rest.interfax.net/outbound/documents/6a58b45c8
Content-Length: 0

This approach can mixed with other approaches, as for example when submitting multiple documents for faxing:


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Content-Type: multipart/mixed; boundary=265001916915724
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

--265001916915724
Content-Type: application/pdf

{content 1 goes here}

--265001916915724

Content-Location: https://rest.interfax.net/outbound/documents/6a58b45c8

--265001916915724--

Pointing to an external URL

Content to be faxed may also reside on an external URL, as for example if you wish to fax content that is dynamically generated by your web server (the content type is assumed to be text/html). The InterFAX service will contact this URL and fax the HTML content that appears at the URL. For example:


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Location: https://www.example.com/invoice?invoiceid=12345
Content-Length: 0

This approach can mixed with other approaches, as for example when submitting multiple documents for faxing:


POST /outbound/faxes HTTP/1.1
Host: rest.interfax.net
Content-Type: multipart/mixed; boundary=265001916915724
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

--265001916915724
Content-Type: application/pdf

{content 1 goes here}

--265001916915724
Content-Location: https://www.example.com/invoice?invoiceid=12345

--265001916915724--

Submitting multiple parts
Multiple documents/parts may be submitted, including a mix of inline documents, uploaded documents. and external URLs. The document order in the outgoing fax will be the same as the document order within the HTTP content area.

Response

If successful, a 201 Created status is returned and the HTTP Location header contains the URI of the newly-created fax resource, e.g. Location: https://rest.interfax.net/outbound/faxes/854759652.

Samples

[tabs: samples]


POST /outbound/faxes?faxNumber=+97237604736 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Host: rest.interfax.net
Location: https://rest.interfax.net/outbound/faxes/278910468

Send a quick PDF fax


curl "https://rest.interfax.net/outbound/faxes?faxNumber=0012129876543" ^
    -u username:password ^
    --data-binary "@dailyrates.pdf" ^
    -H "Content-Type: application/pdf"

Send a simple plain text fax


curl "https://rest.interfax.net/outbound/faxes?faxNumber=+97237604736" ^
    -u username:password ^
    --data-ascii "@sampledoc.txt" ^
    -H "Content-Type: text/plain"

Send a quick HTML fax

curl "https://rest.interfax.net/outbound/faxes?faxNumber=+97237604736" ^
    -u username:password ^
    --data "@sampledoc.html" ^
    -H "Content-Type: text/html"

Fax a previously-uploaded document


curl "https://rest.interfax.net/outbound/faxes?faxNumber=+97237604736" ^
    -u username:password ^
    -H "Content-Location: https://rest.interfax.net/outbound/faxes/278920138"

Faxing multiple documents


curl "https://rest.interfax.net/outbound/faxes?faxNumber=0097298643137" ^
    -u username:password ^
    -H "Content-Type: multipart/mixed" ^
    -F "file1=@sampledoc.doc;type=application/msword" ^
    -F "file2=@sampledoc.pdf;type=application/pdf"

Contact us today

Talk to a member of our team about the benefits InterFAX can bring to your organization's communications processes.

Contact us today