{"id":23279968,"url":"https://github.com/interfax/interfax-nodejs","last_synced_at":"2025-07-30T06:09:26.312Z","repository":{"id":57238499,"uuid":"65286938","full_name":"interfax/interfax-nodejs","owner":"interfax","description":"Fax send and receive in Node.js / Javascript with the InterFAX REST API","archived":false,"fork":false,"pushed_at":"2023-11-30T18:42:08.000Z","size":65,"stargazers_count":8,"open_issues_count":8,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-06-29T01:42:32.910Z","etag":null,"topics":["fax","fax-api","hipaa","inbound","interfax","interfax-api","library","node","online-fax","outbound","receive","sdk","send"],"latest_commit_sha":null,"homepage":"https://www.interfax.net/en/dev/nodejs","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interfax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-09T10:39:21.000Z","updated_at":"2024-12-20T22:54:10.000Z","dependencies_parsed_at":"2023-11-30T19:45:58.236Z","dependency_job_id":null,"html_url":"https://github.com/interfax/interfax-nodejs","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/interfax/interfax-nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interfax","download_url":"https://codeload.github.com/interfax/interfax-nodejs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-nodejs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267820869,"owners_count":24149293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fax","fax-api","hipaa","inbound","interfax","interfax-api","library","node","online-fax","outbound","receive","sdk","send"],"created_at":"2024-12-19T23:19:55.510Z","updated_at":"2025-07-30T06:09:26.237Z","avatar_url":"https://github.com/interfax.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# InterFAX Node Library\n\n[![Module Version](https://badge.fury.io/js/interfax.svg)](https://badge.fury.io/js/interfax) [![Build Status](https://travis-ci.org/interfax/interfax-nodejs.svg?branch=master)](https://travis-ci.org/interfax/interfax-nodejs)\n\n[Installation](#installation) | [Getting Started](#getting-started) | [Contributing](#contributing) | [License](#license)\n\nSend and receive faxes in Node / Javascript with the [InterFAX](https://www.interfax.net/en/dev) REST API.\n\n## Installation\n\nThis library requires Node 4+ and can be installed via NPM.\n\n```sh\nnpm install interfax --save\n```\n\nThis 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.\n\n## Getting started\n\nAll our API calls support Promises to handle asynchronous callbacks. For example to send a fax from a PDF file:\n\n```js\nvar InterFAX = require('interfax');\n// or: import InterFAX from 'interfax';\nvar interfax = new InterFAX();\n\ninterfax.deliver({\n  faxNumber : '+11111111112',\n  file : 'folder/fax.pdf'\n}).then(fax =\u003e {\n  return interfax.outbound.find(fax.id);\n  //=\u003e find the fax we just created\n}).then(fax =\u003e {\n  console.log(fax.status);\n  //=\u003e the status of the fax we just sent\n})\n.catch(error =\u003e {\n  console.log(error);\n  //=\u003e an error object\n});\n```\n\nAlternatively we also support callbacks instead of promises.\n\n```js\ninterfax.deliver({\n  faxNumber : '+11111111112',\n  file : 'folder/fax.pdf'\n}, function(error, response) {\n  if (error) {\n    console.log(error);\n    //=\u003e an error object\n  } else {\n    console.log(response.id);\n    //=\u003e the ID of the Fax just created\n  }\n});\n```\n\n# Usage\n\n[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents) | [Files](#files)\n\n## Client\n\nThe client follows the [12-factor](http://12factor.net/config) apps principle and can be either set directly or via environment variables.\n\n```js\nvar InterFAX = require('interfax');\n\n// Initialize using parameters\nvar interfax = new InterFAX({\n  username: '...',\n  password: '...'\n});\n\n// Alternative: Initialize using\n// environment variables\n// * INTERFAX_USERNAME\n// * INTERFAX_PASSWORD\nvar interfax = new InterFAX();\n```\n\nAll connections are established over HTTPS. To debug the API calls, simply provide a second parameter to the initializer:\n\n\n```js\nvar InterFAX = require('interfax');\nvar interfax = new InterFAX({\n  username: '...',\n  password: '...'\n}, true); // passing true enables debugging mode\n```\n\n## Account\n\n### Balance\n\n`interfax.account.balance(callback);`\n\nDetermine the remaining faxing credits in your account.\n\n```js\ninterfax.account.balance()\n  .then(console.log); //=\u003e 9.86\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/3001)\n\n## Outbound\n\n[Send](#send-fax) | [Get list](#get-outbound-fax-list) | [Get completed list](#get-completed-fax-list) | [Get record](#get-outbound-fax-record) | [Get image](#get-outbound-fax-image) | [Cancel fax](#cancel-a-fax) | [Search](#search-fax-list)\n\n### Send fax\n\n`.outbound.deliver(options, callback);`\n\nSubmit a fax to a single destination number.\n\nThere are a few ways to send a fax. One way is to directly provide a file path or url.\n\n```js\n// with a path\ninterfax.outbound.deliver({\n  faxNumber: '+11111111112',\n  file: 'folder/fax.txt'\n}).then(fax =\u003e {\n  console.log(fax) //=\u003e fax object\n});\n\n// or with a URL\ninterfax.outbound.deliver({\n  faxNumber: '+11111111112',\n  file: 'https://s3.aws.com/example/fax.html'\n}).then(...);\n```\n\nInterFAX supports over 20 file types including HTML, PDF, TXT, Word, and many more. For a full list see the [Supported File Types](https://www.interfax.net/en/help/supported_file_types) documentation.\n\nThe 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.\n\n```js\ninterfax.outbound.deliver({\n  faxNumber: '+11111111112',\n  file: 'folder/fax.txt'\n}).then(fax =\u003e {\n  return interfax.outbound.cancel(fax.id);\n}).then(success =\u003e {\n  //=\u003e now the fax is cancelled\n});;\n```\n\nAdditionally you can create a [`File`](#files) with binary data and pass this in as well.\n\n```js\nvar data = fs.readFileSync('fax.pdf');\ninterfax.files.create(data, {mimeType: 'application/pdf'})\n  .then(function(file) {\n    interfax.outbound.deliver({\n      faxNumber: \"+11111111112\",\n      file: file\n    });\n  });\n```\n\nTo send multiple files just pass in an array of strings and [`File`](#files) objects.\n\n```js\ninterfax.outbound.deliver({\n  faxNumber: \"+11111111112\",\n  files: ['file://fax.pdf', 'https://s3.aws.com/example/fax.html']\n}).then(...);\n```\n\nUnder the hood every path and string is turned into a  [`File`](#files) object. For more information see [the documentation](#files) for this class.\n\nAdditionally this API will automatically detect large files and upload them in chunks using the [Documents API](#documents).\n\n**Options:** [`contact`, `postponeTime`, `retriesToPerform`, `csid`, `pageHeader`, `reference`, `pageSize`, `fitToPage`, `pageOrientation`, `resolution`, `rendering`](https://www.interfax.net/en/dev/rest/reference/2918)\n\n**Alias**: `interfax.deliver`\n\n---\n\n### Get outbound fax list\n\n`interfax.outbound.all(options, callback);`\n\nGet a list of recent outbound faxes (which does not include batch faxes).\n\n```js\ninterfax.outbound.all({\n  limit: 5\n}).then(faxes =\u003e {\n  console.log(faxes); //=\u003e an array of fax objects\n});\n```\n\n**Options:** [`limit`, `lastId`, `sortOrder`, `userId`](https://www.interfax.net/en/dev/rest/reference/2920)\n\n---\n\n### Get completed fax list\n\n`interfax.outbound.completed(array_of_ids, callback);`\n\nGet details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).\n\n```js\ninterfax.outbound.completed([123, 234])\n  .then(faxes =\u003e {\n    console.log(faxes); //=\u003e an array of fax objects\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2972)\n\n----\n\n### Get outbound fax record\n\n`interfax.outbound.find(fax_id, callback);`\n\nRetrieves information regarding a previously-submitted fax, including its current status.\n\n```js\ninterfax.outbound.find(123456)\n  .then(fax =\u003e {\n    console.log(fax); //=\u003e fax object\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2921)\n\n---\n\n### Get outbound fax image\n\n`interfax.outbound.image(fax_id, callback);`\n\nRetrieve the fax image (TIFF or PDF file) of a submitted fax.\n\n```js\ninterfax.outbound.image(123456)\n  .then(image =\u003e {\n    console.log(image.dataBuffer); //=\u003e TIFF/PDF image data\n    image.save(`path/to/file.${image.extension}`); //=\u003e saves image to file\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2941)\n\n----\n\n### Cancel a fax\n\n`interfax.outbound.cancel(fax_id, callback);`\n\nCancel a fax in progress.\n\n```js\ninterfax.outbound.cancel(123456)\n  .then(fax =\u003e {\n    console.log(fax); //=\u003e fax object\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2939)\n\n----\n\n### Search fax list\n\n`interfax.outbound.search(options, callback);`\n\nSearch for outbound faxes.\n\n```js\ninterfax.outbound.search({\n  faxNumber: '+1230002305555'\n}).then(faxes =\u003e {\n  console.log(faxes); //=\u003e an array of fax objects\n});\n```\n\n**Options:** [`ids`, `reference`, `dateFrom`, `dateTo`, `status`, `userId`, `faxNumber`, `limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2959)\n\n## Inbound\n\n[Get list](#get-inbound-fax-list) | [Get record](#get-inbound-fax-record) | [Get image](#get-inbound-fax-image) | [Get emails](#get-forwarding-emails) | [Mark as read](#mark-as-readunread) | [Resend to email](#resend-inbound-fax)\n\n### Get inbound fax list\n\n`interfax.inbound.all(options, callback);`\n\nRetrieves a user's list of inbound faxes. (Sort order is always in descending ID).\n\n```js\ninterfax.inbound.all({\n  limit: 5\n}).then(faxes =\u003e {\n  console.log(faxes); //=\u003e an array of fax objects\n});\n```\n\n**Options:** [`unreadOnly`, `limit`, `lastId`, `allUsers`](https://www.interfax.net/en/dev/rest/reference/2935)\n\n---\n\n### Get inbound fax record\n\n`interfax.inbound.find(fax_id, callback);`\n\nRetrieves a single fax's metadata (receive time, sender number, etc.).\n\n```js\ninterfax.inbound.find(123456)\n  .then(fax =\u003e {\n    console.log(fax); //=\u003e fax object\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2938)\n\n---\n\n### Get inbound fax image\n\n`interfax.inbound.image(fax_id, callback);`\n\nRetrieves a single fax's image.\n\n```js\ninterfax.inbound.image(123456)\n  .then(image =\u003e {\n    console.log(image.dataBuffer); //=\u003e TIFF or PDF image data\n    image.save(`path/to/file.${image.extension}`); //=\u003e saves image to file\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2937)\n\n---\n\n### Get forwarding emails\n\n`interfax.inbound.emails(fax_id, callback);`\n\nRetrieve the list of email addresses to which a fax was forwarded.\n\n```js\ninterfax.inbound.emails(123456)\n  .then(emails =\u003e {\n    console.log(emails); //=\u003e a list of email objects\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2930)\n\n---\n\n### Mark as read/unread\n\n`interfax.inbound.mark(fax_id, is_read, callback);`\n\nMark a transaction as read/unread.\n\n```js\n// mark as read\ninterfax.inbound.mark(123456, true)\n  .then((success) =\u003e {\n    console.log(success); // boolean\n  });\n\n// mark as unread\ninterfax.inbound.mark(123456, false)\n  .then((success) =\u003e {\n    console.log(success); // boolean\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2936)\n\n### Resend inbound fax\n\n`interfax.inbound.resend(fax_id, to_email, callback);`\n\nResend an inbound fax to a specific email address.\n\n```js\n// resend to the email(s) to which the fax was previously forwarded\ninterfax.inbound.resend(123456)\n  .then((success) =\u003e {\n    console.log(success); // boolean\n  });\n\n// resend to a specific address\ninterfax.inbound.resend(123456, 'test@example.com')\n  .then((success) =\u003e {\n    console.log(success); // boolean\n  });\n=\u003e true\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2929)\n\n---\n\n## Documents\n\n[Create](#create-document) | [Upload chunk](#upload-chunk) | [Get list](#get-document-list) | [Status](#get-document-status) | [Cancel](#cancel-document)\n\nDocuments 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`](#send-fax) method will automatically detect large files and upload them in chunks as documents.\n\nIf you do wish to do this yourself the following example shows how you could upload a file in 500 byte chunks:\n\n```js\nvar fs = require('fs');\n\nvar upload = function(cursor = 0, document, data) {\n  if (cursor \u003e= data.length) { return };\n  var chunk = data.slice(cursor, cursor+500);\n  var next_cursor = cursor+Buffer.byteLength(chunk);\n\n  interfax.documents.upload(document.id, cursor, next_cursor-1, chunk)\n    .then(() =\u003e { upload(next_cursor, document, data); });\n}\n\nfs.readFile('tests/test.pdf', function(err, data){\n  interfax.documents.create('test.pdf', Buffer.byteLength(data))\n    .then(document =\u003e { upload(0, document, data); });\n});\n```\n\n### Create Documents\n\n`interfax.documents.create(name, size, options, callback);`\n\nCreate a document upload session, allowing you to upload large files in chunks.\n\n```js\ninterfax.documents.create('large_file.pdf', 231234)\n  .then(document =\u003e {\n    console.log(document.id); // the ID of the document created\n  });\n```\n\n**Options:** [`disposition`, `sharing`](https://www.interfax.net/en/dev/rest/reference/2967)\n\n---\n\n### Upload chunk\n\n`interfax.documents.upload(id, range_start, range_end, chunk, callback);`\n\nUpload a chunk to an existing document upload session.\n\n```js\ninterfax.documents.upload(123456, 0, 999, \"....binary-data....\")\n  .then(document =\u003e {\n    console.log(document);\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2966)\n\n---\n\n### Get document list\n\n`interfax.documents.all(options, callback);`\n\nGet a list of previous document uploads which are currently available.\n\n```js\ninterfax.documents.all({\n  offset: 10\n}).then(documents =\u003e {\n  console.log(documents); //=\u003e a list of documents\n});\n```\n\n**Options:** [`limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2968)\n\n---\n\n### Get document status\n\n`interfax.documents.find(document_id, callback);`\n\nGet the current status of a specific document upload.\n\n```js\ninterfax.documents.find(123456)\n  .then(document =\u003e {\n    console.log(document); //=\u003e a document object\n  });\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2965)\n\n---\n\n### Cancel document\n\n`interfax.documents.cancel(document_id, callback);`\n\nCancel a document upload and tear down the upload session, or delete a previous upload.\n\n```js\ninterfax.documents.cancel(123456)\n  .then(success =\u003e {\n    console.log(success); //=\u003e boolean\n  })\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2964)\n\n---\n\n## Files\n\nThis 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](#documents) API.\n\nIt is most useful for sending binary data to the `.deliver` method.\n\n```js\ninterfax.files.create('....binary data.....', { mimeType: 'application/pdf' })\n  .then(file =\u003e {\n    console.log(file.header); //=\u003e 'Content-Type: application/pdf'\n    console.log(file.body);   //=\u003e ....binary data.....\n    interfax.outbound.deliver(faxNumber: '+1111111111112', file: file);\n  });\n```\n\nAdditionally it can be used to turn a URL or path into a valid object as well, though the `.deliver` method does this conversion automatically.\n\n```js\n// a file by path\ninterfax.files.create('foo/bar.pdf');\n\n// a file by url\ninterfax.files.create('https://foo.com/bar.html');\n```\n\n## Contributing\n\n 1. **Fork** the repo on GitHub\n 2. **Clone** the project to your own machine\n 3. **Commit** changes to your own branch\n 4. **Push** your work back up to your fork\n 5. Submit a **Pull request** so that we can review your changes\n\n## License\n\nThis library is released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterfax%2Finterfax-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-nodejs/lists"}