{"id":23613717,"url":"https://github.com/interfax/interfax-ruby","last_synced_at":"2025-05-12T21:45:37.190Z","repository":{"id":1065649,"uuid":"902833","full_name":"interfax/interfax-ruby","owner":"interfax","description":"Fax send and receive in Ruby with the InterFAX REST API","archived":false,"fork":false,"pushed_at":"2022-03-29T22:51:02.000Z","size":120,"stargazers_count":17,"open_issues_count":2,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-21T03:10:18.240Z","etag":null,"topics":["fax","fax-api","hipaa","inbound","interfax","interfax-api","library","online-fax","outbound","receive","ruby","sdk","send"],"latest_commit_sha":null,"homepage":"https://www.interfax.net/en/dev/ruby","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"defunctzombie/form-serialize","license":"mit","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}},"created_at":"2010-09-11T02:40:16.000Z","updated_at":"2024-07-12T09:05:24.000Z","dependencies_parsed_at":"2022-07-15T06:47:25.432Z","dependency_job_id":null,"html_url":"https://github.com/interfax/interfax-ruby","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interfax","download_url":"https://codeload.github.com/interfax/interfax-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253829660,"owners_count":21970956,"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","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","online-fax","outbound","receive","ruby","sdk","send"],"created_at":"2024-12-27T17:19:17.636Z","updated_at":"2025-05-12T21:45:37.160Z","avatar_url":"https://github.com/interfax.png","language":"Ruby","readme":"# InterFAX Ruby Gem\n\n[![Gem Version](https://badge.fury.io/rb/interfax.svg)](https://badge.fury.io/rb/interfax) [![Build Status](https://travis-ci.org/interfax/interfax-ruby.svg?branch=master)](https://travis-ci.org/interfax/interfax-ruby)\n\n[Installation](#installation) | [Getting Started](#getting-started) | [Contributing](#contributing) | [Usage](#usage) | [License](#license)\n\nSend and receive faxes in Ruby with the [InterFAX](https://www.interfax.net/en/dev) REST API.\n\n## Installation\n\nThis gem requires Ruby 2.1+. You can install install it directly or via bundler.\n\n```ruby\ngem 'interfax'\n```\n\n## Getting started\n\nTo send a fax from a PDF file:\n\n```ruby\nrequire 'interfax'\n\ninterfax = InterFAX::Client.new(username: 'username', password: 'password')\nfax = interfax.deliver(faxNumber: \"+11111111112\", file: 'folder/fax.pdf')\nfax = fax.reload # resync with API to get latest status\nfax.status # Success if 0. Pending if \u003c 0. Error if \u003e 0\n```\n\n# Usage\n\n[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents) | [Helper Classes](#helper-classes)\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```ruby\n# Initialize using parameters\ninterfax = InterFAX::Client.new(username: '...', password: '...')\n\n# Alternative: Initialize using environment variables\n# * INTERFAX_USERNAME\n# * INTERFAX_PASSWORD\ninterfax = InterFAX::Client.new\n```\n\nAll connections are established over HTTPS.\n\n## Account\n\n### Balance\n\nDetermine the remaining faxing credits in your account.\n\n```ruby\ninterfax.account.balance\n=\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 = {})`\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```ruby\n# with a path\ninterfax.outbound.deliver(faxNumber: \"+11111111112\", file: 'folder/fax.txt')\n# with a URL\ninterfax.outbound.deliver(faxNumber: \"+11111111112\", file: 'https://s3.aws.com/example/fax.html')\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 `InterFAX::Outbound::Fax` with just an `id`. You can use this object to load more information, get the image, or cancel the sending of the fax.\n\n```rb\nfax = interfax.outbound.deliver(faxNumber: \"+11111111112\", file: 'file://fax.pdf')\nfax = fax.reload # Reload fax, allowing you to inspect the status and more\n\nfax.id        # the ID of the fax that can be used in some of the other API calls\nfax.image     # returns an image representing the fax sent to the faxNumber\nfax.cancel    # cancel the sending of the fax\n```\n\nAlternatively you can create an [`InterFAX::File`](#interfaxfile) with binary data and pass this in as well.\n\n```ruby\ndata = File.open('file://fax.pdf').read\nfile = interfax.files.create(data, mime_type: 'application/pdf')\ninterfax.outbound.deliver(faxNumber: \"+11111111112\", file: file)\n```\n\nTo send multiple files just pass in an array strings and [`InterFAX::File`](#interfaxfile) objects.\n\n```rb\ninterfax.outbound.deliver(faxNumber: \"+11111111112\", files: ['file://fax.pdf', 'https://s3.aws.com/example/fax.html'])\n```\n\nUnder the hood every path and string is turned into a  [InterFAX::File](#interfaxfile) object. For more information see [the documentation](#interfaxfile) for this class.\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 = {})`\n\nGet a list of recent outbound faxes (which does not include batch faxes).\n\n```ruby\ninterfax.outbound.all\n=\u003e [#\u003cInterFAX::Outbound::Fax\u003e, ...]\ninterfax.outbound.all(limit: 1)\n=\u003e [#\u003cInterFAX::Outbound::Fax\u003e]\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)`\n\nGet details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).\n\n```ruby\ninterfax.outbound.completed(123, 234)\n=\u003e [#\u003cInterFAX::Outbound::Fax\u003e, ...]\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)`\n\nRetrieves information regarding a previously-submitted fax, including its current status.\n\n```ruby\ninterfax.outbound.find(123456)\n=\u003e #\u003cInterFAX::Outbound::Fax\u003e\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)`\n\nRetrieve the fax image (TIFF file) of a submitted fax.\n\n```ruby\nimage = interfax.outbound.image(123456)\n=\u003e #\u003cInterFAX::Image\u003e\nimage.data\n=\u003e # \"....binary data....\"\nimage.save('fax.tiff')\n=\u003e # saves image to file\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)`\n\nCancel a fax in progress.\n\n```ruby\ninterfax.outbound.cancel(123456)\n=\u003e true\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 = {})`\n\nSearch for outbound faxes.\n\n```ruby\ninterfax.outbound.search(faxNumber: '+1230002305555')\n=\u003e [#\u003cInterFAX::Outbound::Fax\u003e, ...]\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 = {})`\n\nRetrieves a user's list of inbound faxes. (Sort order is always in descending ID).\n\n```ruby\ninterfax.inbound.all\n=\u003e [#\u003cInterFAX::Inbound::Fax\u003e, ...]\ninterfax.inbound.all(limit: 1)\n=\u003e [#\u003cInterFAX::Inbound::Fax\u003e]\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)`\n\nRetrieves a single fax's metadata (receive time, sender number, etc.).\n\n```ruby\ninterfax.inbound.find(123456)\n=\u003e #\u003cInterFAX::Inbound::Fax\u003e\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)`\n\nRetrieves a single fax's image. This can be a PDF or a TIFF file.\n\n```ruby\nimage = interfax.inbound.image(123456)\n=\u003e #\u003cInterFAX::Image\u003e\nimage.data\n=\u003e # \"....binary data....\"\nimage.save(\"path/to/fax.#{image.extension}\")\n=\u003e # saves image to file\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)`\n\nRetrieve the list of email addresses to which a fax was forwarded.\n\n```ruby\ninterfax.inbound.email(123456)\n=\u003e [#\u003cInterFAX::Email\u003e]\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, read: is_read)`\n\nMark a transaction as read/unread.\n\n```ruby\ninterfax.inbound.mark(123456, read: true) # mark read\n=\u003e true\ninterfax.inbound.mark(123456, read: false) # mark unread\n=\u003e true\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2936)\n\n---\n\n### Resend inbound fax\n\n`interfax.inbound.resend(fax_id, email: to_email)`\n\nResend an inbound fax to a specific email address.\n\n```ruby\n# resend to the email(s) to which the fax was previously forwarded\ninterfax.inbound.resend(123456)\n=\u003e true\n# resend to a specific address\ninterfax.inbound.resend(123456, email: 'test@example.com')\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\nDocument allow for uploading of large files up to 20MB in 200kb chunks. The [`InterFAX::File`](#interfaxfile) format automatically uses this if needed but a sample implementation would look as followed.\n\n```ruby\nfile = File.open('test.pdf', 'rb')\n\ndocument = interfax.documents.create('test.pdf', file.size)\n\ncursor = 0\nwhile !file.eof?\n  chunk = file.read(500)\n  next_cursor = cursor + chunk.length\n  document.upload(cursor, next_cursor-1, chunk)\n  cursor = next_cursor\nend\n```\n\n### Create Documents\n\n`interfax.documents.create(name, size, options = {})`\n\nCreate a document upload session, allowing you to upload large files in chunks.\n\n```ruby\ninterfax.documents.create('large_file.pdf', '231234')\n=\u003e #\u003cInterFAX::Document uri=\"https://rest.interfax.net/outbound/documents/123456\"\u003e\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)`\n\nUpload a chunk to an existing document upload session.\n\n```ruby\ninterfax.documents.upload(123456, 0, 999, \"....binary-data....\")\n=\u003e true\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 = {})`\n\nGet a list of previous document uploads which are currently available.\n\n```ruby\ninterfax.documents.all\n=\u003e #[#\u003cInterFAX::Document\u003e, ...]\ninterfax.documents.all(offset: 10)\n=\u003e #[#\u003cInterFAX::Document\u003e, ...]\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(id)`\n\nGet the current status of a specific document upload.\n\n```ruby\ninterfax.documents.find(123456)\n=\u003e #\u003cInterFAX::Document ... \u003e\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(id)`\n\nCancel a document upload and tear down the upload session, or delete a previous upload.\n\n```ruby\ninterfax.documents.cancel(123456)\n=\u003e true\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2964)\n\n---\n\n## Helper Classes\n\n### InterFAX::Outbound::Fax\n\nThe `InterFAX::Outbound::Fax` is returned in most Outbound APIs. As a convenience the following methods are available.\n\n```rb\nfax = interfax.outbound.find(123)\nfax = fax.reload # Loads or reloads object\nfax.cancel # Cancels the fax\nfax.image # Returns a `InterFAX::Image` for this fax\nfax.attributes # Returns a plain hash with all the attributes\n```\n\n### InterFAX::Inbound::Fax\n\nThe `InterFAX::Inbound::Fax` is returned in some of the Inbound APIs. As a convenience the following methods are available.\n\n```rb\nfax = interfax.inbound.find(123)\nfax = fax.reload # Loads or reloads object\nfax.mark(true) # Marks the fax as read/unread\nfax.resend(email) # Resend the fax to a specific email address.\nfax.image # Returns a `InterFAX::Image` for this fax\nfax.emails # Returns a list of InterFAX::ForwardingEmail objects that the fax was forwarded on to\nfax.attributes # Returns a plain hash with all the attributes\n```\n\n### InterFAX::Image\n\nA lightweight wrapper around the image data for a sent or received fax. Provides the following convenience methods.\n\n```rb\nimage = interfax.outbound.image(123)\nimage.data # Returns the raw binary data for the TIFF image.\nimage.save('folder/fax.tiff') # Saves the TIFF to the path provided\n```\n\n### InterFAX::File\n\nThis class is used by `interfax.outbound.deliver` and `interfax.files` to turn every URL, path and binary data into a uniform format, ready to be sent out to the InterFAX API.\n\nIt is most useful for sending binary data to the `.deliver` method.\n\n```rb\n# binary data\nfile = InterFAX::File.new(interfax, '....binary data.....', mime_type: 'application/pdf')\n=\u003e #\u003cInterFAX::File\u003e\n\n# Alternatively\nfile = interfax.files.create('....binary data.....', mime_type: 'application/pdf')\nfile.header\n=\u003e \"Content-Type: application/pdf\"\nfile.body\n=\u003e '....binary data.....'\n\ninterfax.outbound.deliver(faxNumber: '+1111111111112', file: file)\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```rb\n# a file by path\nfile = interfax.files.create('foo/bar.pdf')\nfile.header #=\u003e \"Content-Type: application/pdf\"\nfile.body #=\u003e '....binary data.....'\n\n# a file by url\nfile = interfax.files.create('https://foo.com/bar.html')\nfile.header #=\u003e \"Content-Location: https://foo.com/bar.html\"\nfile.body #=\u003e nil\n```\n\n### InterFAX::ForwardingEmail\n\nA light wrapper around [the response](https://www.interfax.net/en/dev/rest/reference/2930) received by asking for the forwarded emails for a fax.\n\n```ruby\nfax = interfax.inbound.find(123)\nemail = fax.emails.first\nemail.emailAddress # An email address to which forwarding of the fax was attempted.\nemail.messageStatus # 0 = OK; number smaller than zero = in progress; number greater than zero = error.\nemail.completionTime # Completion timestamp.\n```\n\n### InterFAX::Document\n\nThe `InterFAX::Document` is returned in most of the Document APIs. As a convenience the following methods are available.\n\n```ruby\ndocument = interfax.documents.find(123)\ndocument = document.reload # Loads or reloads object\ndocument.upload(0, 999, '.....binary data....' # Maps to the interfax.documents.upload method\ndocument.cancel # Maps to the interfax.documents.upload method\ndocument.id  # Extracts the ID from the URI (the API does not return the ID)\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. **Test** the changes you have made\n 5. **Push** your work back up to your fork\n 6. Submit a **Pull request** so that we can review your changes\n\n### Testing\n\nBefore submitting a contribution please ensure all tests pass.\n\n```sh\nbundle install # install dependencies\nrake spec # run all tests\n```\n\n### Configuring a custom host\n\nIt might be necessary to specifyc a different host for testing purposes. To\nachieve this, specify the `host` parameter or `INTERFAX_HOST` environment\nvariable.\n\n\n```ruby\ninterfax = InterFAX::Client.new(\n  username: '...',\n  password: '...',\n  host: 'test.domain.com'\n)\n```\n\n## License\n\nThis library is released under the [MIT License](LICENSE).\n\n## Credits\n\nMany thanks go to [Sascha Brink] (https://github.com/sbrink) for building the pre 1.0 version of this gem and supporting it for so many years.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterfax%2Finterfax-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-ruby/lists"}