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.
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 | 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. |
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:
- Inserting a document as inline content (e.g., application/msword or application/pdf).
- 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"