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.

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 (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
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 A4LetterLegal, 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. 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 contentdetailed below, submitted as a single content element (that is, not multipart), for example:


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-wide limitations on total file size, maximum page count, etc.). For example:


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:

  1. Inserting a document as inline content (e.g., application/msword or application/pdf).
  2. Pointing to an external URL.

These are detailed below.

Inserting a document as inline content


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

{content goes here}

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-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:


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

Submitting multiple parts
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.

Samples

Raw HTTP


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


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


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

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

Faxing multiple documents


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"