Installation | Getting Started | Contributing | License
Send and receive faxes in Node / Javascript with the InterFAX REST API.
This library requires Node 4+ and can be installed via NPM.
npm install interfax --saveThis module is written in ES6 and is transpiled to ES5 for backwards compatibility. While all documentation below is written in ES6 this module works equally as well in ES5 projects.
All our API calls support Promises to handle asynchronous callbacks. For example to send a fax from a PDF file:
var InterFAX = require('interfax');
// or: import InterFAX from 'interfax';
var interfax = new InterFAX();
interfax.deliver({
faxNumber : '+11111111112',
file : 'folder/fax.pdf'
}).then(fax => {
return interfax.outbound.find(fax.id);
//=> find the fax we just created
}).then(fax => {
console.log(fax.status);
//=> the status of the fax we just sent
})
.catch(error => {
console.log(error);
//=> an error object
});Alternatively we also support callbacks instead of promises.
interfax.deliver({
faxNumber : '+11111111112',
file : 'folder/fax.pdf'
}, function(error, response) {
if (error) {
console.log(error);
//=> an error object
} else {
console.log(response.id);
//=> the ID of the Fax just created
}
});Client | Account | Outbound | Inbound | Documents | Files
The client follows the 12-factor apps principle and can be either set directly or via environment variables.
var InterFAX = require('interfax');
// Initialize using parameters
var interfax = new InterFAX({
username: '...',
password: '...'
});
// Alternative: Initialize using
// environment variables
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD
var interfax = new InterFAX();All connections are established over HTTPS. To debug the API calls, simply provide a second parameter to the initializer:
var InterFAX = require('interfax');
var interfax = new InterFAX({
username: '...',
password: '...'
}, true); // passing true enables debugging modeinterfax.account.balance(callback);
Determine the remaining faxing credits in your account.
interfax.account.balance()
.then(console.log); //=> 9.86More: documentation
Send | Get list | Get completed list | Get record | Get image | Cancel fax | Search
.outbound.deliver(options, callback);
Submit a fax to a single destination number.
There are a few ways to send a fax. One way is to directly provide a file path or url.
// with a path
interfax.outbound.deliver({
faxNumber: '+11111111112',
file: 'folder/fax.txt'
}).then(fax => {
console.log(fax) //=> fax object
});
// or with a URL
interfax.outbound.deliver({
faxNumber: '+11111111112',
file: 'https://s3.aws.com/example/fax.html'
}).then(...);InterFAX supports over 20 file types including HTML, PDF, TXT, Word, and many more. For a full list see the Supported File Types documentation.
The returned object is a plain object with just an id. You can use this ID to load more information, get the image, or cancel the sending of the fax.
interfax.outbound.deliver({
faxNumber: '+11111111112',
file: 'folder/fax.txt'
}).then(fax => {
return interfax.outbound.cancel(fax.id);
}).then(success => {
//=> now the fax is cancelled
});;Additionally you can create a File with binary data and pass this in as well.
var data = fs.readFileSync('fax.pdf');
interfax.files.create(data, {mimeType: 'application/pdf'})
.then(function(file) {
interfax.outbound.deliver({
faxNumber: "+11111111112",
file: file
});
});To send multiple files just pass in an array of strings and File objects.
interfax.outbound.deliver({
faxNumber: "+11111111112",
files: ['file://fax.pdf', 'https://s3.aws.com/example/fax.html']
}).then(...);Under the hood every path and string is turned into a File object. For more information see the documentation for this class.
Additionally this API will automatically detect large files and upload them in chunks using the Documents API.
Alias: interfax.deliver
interfax.outbound.all(options, callback);
Get a list of recent outbound faxes (which does not include batch faxes).
interfax.outbound.all({
limit: 5
}).then(faxes => {
console.log(faxes); //=> an array of fax objects
});Options: limit, lastId, sortOrder, userId
interfax.outbound.completed(array_of_ids, callback);
Get details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).
interfax.outbound.completed([123, 234])
.then(faxes => {
console.log(faxes); //=> an array of fax objects
});More: documentation
interfax.outbound.find(fax_id, callback);
Retrieves information regarding a previously-submitted fax, including its current status.
interfax.outbound.find(123456)
.then(fax => {
console.log(fax); //=> fax object
});More: documentation
interfax.outbound.image(fax_id, callback);
Retrieve the fax image (TIFF or PDF file) of a submitted fax.
interfax.outbound.image(123456)
.then(image => {
console.log(image.dataBuffer); //=> TIFF/PDF image data
image.save(`path/to/file.${image.extension}`); //=> saves image to file
});More: documentation
interfax.outbound.cancel(fax_id, callback);
Cancel a fax in progress.
interfax.outbound.cancel(123456)
.then(fax => {
console.log(fax); //=> fax object
});More: documentation
interfax.outbound.search(options, callback);
Search for outbound faxes.
interfax.outbound.search({
faxNumber: '+1230002305555'
}).then(faxes => {
console.log(faxes); //=> an array of fax objects
});Options: ids, reference, dateFrom, dateTo, status, userId, faxNumber, limit, offset
Get list | Get record | Get image | Get emails | Mark as read | Resend to email
interfax.inbound.all(options, callback);
Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).
interfax.inbound.all({
limit: 5
}).then(faxes => {
console.log(faxes); //=> an array of fax objects
});Options: unreadOnly, limit, lastId, allUsers
interfax.inbound.find(fax_id, callback);
Retrieves a single fax's metadata (receive time, sender number, etc.).
interfax.inbound.find(123456)
.then(fax => {
console.log(fax); //=> fax object
});More: documentation
interfax.inbound.image(fax_id, callback);
Retrieves a single fax's image.
interfax.inbound.image(123456)
.then(image => {
console.log(image.dataBuffer); //=> TIFF or PDF image data
image.save(`path/to/file.${image.extension}`); //=> saves image to file
});More: documentation
interfax.inbound.emails(fax_id, callback);
Retrieve the list of email addresses to which a fax was forwarded.
interfax.inbound.emails(123456)
.then(emails => {
console.log(emails); //=> a list of email objects
});More: documentation
interfax.inbound.mark(fax_id, is_read, callback);
Mark a transaction as read/unread.
// mark as read
interfax.inbound.mark(123456, true)
.then((success) => {
console.log(success); // boolean
});
// mark as unread
interfax.inbound.mark(123456, false)
.then((success) => {
console.log(success); // boolean
});More: documentation
interfax.inbound.resend(fax_id, to_email, callback);
Resend an inbound fax to a specific email address.
// resend to the email(s) to which the fax was previously forwarded
interfax.inbound.resend(123456)
.then((success) => {
console.log(success); // boolean
});
// resend to a specific address
interfax.inbound.resend(123456, '[email protected]')
.then((success) => {
console.log(success); // boolean
});
=> trueMore: documentation
Create | Upload chunk | Get list | Status | Cancel
Documents allow for uploading of large files up to 20MB in 200kb chunks. In general you do no need to use this API yourself as the outbound.deliver method will automatically detect large files and upload them in chunks as documents.
If you do wish to do this yourself the following example shows how you could upload a file in 500 byte chunks:
var fs = require('fs');
var upload = function(cursor = 0, document, data) {
if (cursor >= data.length) { return };
var chunk = data.slice(cursor, cursor+500);
var next_cursor = cursor+Buffer.byteLength(chunk);
interfax.documents.upload(document.id, cursor, next_cursor-1, chunk)
.then(() => { upload(next_cursor, document, data); });
}
fs.readFile('tests/test.pdf', function(err, data){
interfax.documents.create('test.pdf', Buffer.byteLength(data))
.then(document => { upload(0, document, data); });
});interfax.documents.create(name, size, options, callback);
Create a document upload session, allowing you to upload large files in chunks.
interfax.documents.create('large_file.pdf', 231234)
.then(document => {
console.log(document.id); // the ID of the document created
});Options: disposition, sharing
interfax.documents.upload(id, range_start, range_end, chunk, callback);
Upload a chunk to an existing document upload session.
interfax.documents.upload(123456, 0, 999, "....binary-data....")
.then(document => {
console.log(document);
});More: documentation
interfax.documents.all(options, callback);
Get a list of previous document uploads which are currently available.
interfax.documents.all({
offset: 10
}).then(documents => {
console.log(documents); //=> a list of documents
});Options: limit, offset
interfax.documents.find(document_id, callback);
Get the current status of a specific document upload.
interfax.documents.find(123456)
.then(document => {
console.log(document); //=> a document object
});More: documentation
interfax.documents.cancel(document_id, callback);
Cancel a document upload and tear down the upload session, or delete a previous upload.
interfax.documents.cancel(123456)
.then(success => {
console.log(success); //=> boolean
})More: documentation
This class is used by interfax.outbound.deliver to turn every URL, path and binary data into a uniform format, ready to be sent out to the InterFAX API. Under the hood it automatically uploads large files in chunks using the Documents API.
It is most useful for sending binary data to the .deliver method.
interfax.files.create('....binary data.....', { mimeType: 'application/pdf' })
.then(file => {
console.log(file.header); //=> 'Content-Type: application/pdf'
console.log(file.body); //=> ....binary data.....
interfax.outbound.deliver(faxNumber: '+1111111111112', file: file);
});Additionally it can be used to turn a URL or path into a valid object as well, though the .deliver method does this conversion automatically.
// a file by path
interfax.files.create('foo/bar.pdf');
// a file by url
interfax.files.create('https://foo.com/bar.html');- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
This library is released under the MIT License.