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 files and their respoctive MIME types, see the helper method GET /outbound/help/mediatype.

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

Arguments

Name Type Mandatory Comments Default
faxNumber FaxNumber A single fax number, e.g: +1-212-3456789.

None, mandatory
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
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
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   Standard (optimize for black & white) or Fine (optimize for grayscale). Determines the rendering mode. Standard is recommended for textual, black & white documents, while Fine is better for grayscale text and for images.  

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:

Copy 
POST /outbound/faxes HTTP/1.1
Host: rest-sl.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 limitations on total file size, maximum page count, etc.). For example:

Copy 
POST /outbound/faxes HTTP/1.1
Host: rest-sl.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:

  • Inserting a document as inline content (e.g., application/msword or application/pdf).

  • Pointing to an external URL.

These are detailed below.

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

{content goes here}

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:

Copy 
POST /outbound/faxes HTTP/1.1
Host: rest-sl.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:

Copy 
POST /outbound/faxes HTTP/1.1
Host: rest-sl.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--

Multiple documents/parts may be submitted, including a mix of inline 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-sl.interfax.net/outbound/faxes/854759652.

Sample calls

Raw HTTP

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

cURL

Send a quick PDF fax

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

Send a simple plain text fax

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

Send a quick HTML fax

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

Faxing multiple documents

Copy 
curl "https://rest-sl.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"