{"id":23613712,"url":"https://github.com/interfax/interfax-java","last_synced_at":"2025-05-12T21:43:22.447Z","repository":{"id":50035313,"uuid":"66478786","full_name":"interfax/interfax-java","owner":"interfax","description":"Fax send and receive in Java with the InterFAX REST API","archived":false,"fork":false,"pushed_at":"2023-05-03T16:16:47.000Z","size":19155,"stargazers_count":5,"open_issues_count":12,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-01T03:51:13.631Z","etag":null,"topics":["fax","fax-image","hipaa","inbound","interfax","interfax-api","java","library","online-fax","outbound","receive","sdk","send"],"latest_commit_sha":null,"homepage":"https://www.interfax.net/en/dev/java","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interfax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-24T16:02:31.000Z","updated_at":"2023-07-20T19:54:34.000Z","dependencies_parsed_at":"2022-08-24T05:31:46.091Z","dependency_job_id":null,"html_url":"https://github.com/interfax/interfax-java","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interfax%2Finterfax-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interfax","download_url":"https://codeload.github.com/interfax/interfax-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253828438,"owners_count":21970702,"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-image","hipaa","inbound","interfax","interfax-api","java","library","online-fax","outbound","receive","sdk","send"],"created_at":"2024-12-27T17:19:15.993Z","updated_at":"2025-05-12T21:43:22.417Z","avatar_url":"https://github.com/interfax.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InterFAX Java Library\n\n[![Build Status](https://travis-ci.org/interfax/interfax-java.svg?branch=master)](https://travis-ci.org/interfax/interfax-java) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.interfax/api-client/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.interfax/api-client)\n\n[Installation](#installation) | [Getting Started](#getting-started) | [Usage](#usage) | [Contributing](#contributing) | [License](#license)\n\nSend and receive faxes in Java with the [InterFAX](https://www.interfax.net/en/dev) REST API.\n\n## Installation\n\nUse of the library requires Java 11 or higher and can be done via one of the following approaches. \n\n### Include as maven dependency\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003enet.interfax\u003c/groupId\u003e\n  \u003cartifactId\u003eapi-client\u003c/artifactId\u003e\n  \u003cversion\u003e0.17\u003c/version\u003e\n\u003c/dependency\u003e\n```\n    \n### Download jar and include in application classpath\n\nDownload the latest jar from the [Maven central repository](http://search.maven.org/#search%7Cga%7C1%7Cnet.interfax.api-client)\nand place it in your application classpath. \n\n## Getting started\n\nTo send a fax from a PDF file:\n\n```java\njava.io.File file = new File(absoluteFilePath);\nInterFAX interFAX = new DefaultInterFAXClient(\"username\", \"password\");\nAPIResponse apiResponse = interFAX.sendFax(faxNumber, file);\n```\n\n## Usage\n\n[Client](#client) | [Account](#account) | [Outbound](#outbound) | [Inbound](#inbound) | [Documents](#documents)\n\n## Client\n\nThe client follows the [12-factor](http://12factor.net/config) apps principle and can be either set directly or via \nenvironment variables.\n\n```java\n// Initialize using parameters\nInterFAX interFAX = new DefaultInterFAXClient(\"username\", \"password\");\n\n// Alternative 1: Initialize using environment variables\n// Ensure following env vars are initialized with values of your API credentials\n// * INTERFAX_USERNAME\n// * INTERFAX_PASSWORD\nInterFAX interFAX = new DefaultInterFAXClient();\n\n// Alternative 2: Initialize using yaml file\n// Create a file called `interfax-api-credentials.yaml` with the following contents, replacing the value of `username`\n// and `password` fields with those of your API credentials.\n//   username: \"api-username\"\n//   password: \"api-password\"\nInterFAX interFAX = new DefaultInterFAXClient();\n```\n\nAll connections are established over HTTPS.\n\n## Account\n\n### Credit balance\n\nDetermine the remaining faxing credits in your account\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nDouble balance = interFAX.getAccountCredits();\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) | [Hide fax](#hide-fax)\n\n### Send Fax\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```java\n// with an absoluteFilePath\njava.io.File file = new File(absoluteFilePath);\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.sendFax(faxNumber, file);\n\n// with an inputstream\nInputStream[] inputStreams = {inputStream};\nString[] mediaTypes = {\"application/pdf\"};\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.sendFax(faxNumber, inputStreams, mediaTypes);\n\n// with a URL\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.sendFax(faxNumber, \"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 \n[Supported File Types](https://www.interfax.net/en/help/supported_file_types) documentation.\n\nThe returned object is a [`APIResponse`](src/main/java/net/interfax/rest/client/domain/APIResponse.java) with the \n`statusCode` and `responseBody` of the request submitted to InterFAX.\n\nTo send multiple files just pass in an array of files or inputstreams\n```java\n// using Files\npublic APIResponse sendFax(final String faxNumber, \n                           final File[] filesToSendAsFax) \n                           throws IOException;\n                           \n// using Inputstreams\npublic APIResponse sendFax(final String faxNumber,\n                           final InputStream[] streamsToSendAsFax,\n                           final String mediaTypes[]) throws IOException;                           \n```\n\nAll requests to send a fax can include the following **Options:** [`contact`, `postponeTime`, `retriesToPerform`, `csid`, `pageHeader`, `reference`, `pageSize`, `fitToPage`, `pageOrientation`, `resolution`, `rendering`](https://www.interfax.net/en/dev/rest/reference/2918)\nset via [`SendFaxOptions`](src/main/java/net/interfax/rest/client/domain/SendFaxOptions.java) class                                                                                                                                                    \n\n---\n\n### Get Outbound Fax List\n                              \nGet a list of recent outbound faxes (which does not include batch faxes).\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nOutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList();\n```\n\nUsing additional **Options:** [`limit`, `lastId`, `sortOrder`, `userId`](https://www.interfax.net/en/dev/rest/reference/2920)\n\n```java    \nGetFaxListOptions getFaxListOptions = new GetFaxListOptions();\ngetFaxListOptions.setLimit(Optional.of(5));\n\nInterFAX interFAX = new DefaultInterFAXClient();\nOutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList(Optional.of(getFaxListOptions));\n```\n    \n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2920)\n\n---\n\n### Get Completed Fax List\n\nGet details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are \nignored).\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nOutboundFaxStructure[] outboundFaxStructures = interFAX.getCompletedFaxList(new String[]{\"667915751\", \"667915471\"});\n```\n    \n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2972)\n \n---\n \n### Get Outbound Fax Record\n    \nRetrieves information regarding a previously-submitted fax, including its current status.\n\n```java    \nInterFAX interFAX = new DefaultInterFAXClient();\nOutboundFaxStructure outboundFaxStructure = interFAX.getOutboundFaxRecord(\"667915751\");\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2921)    \n\n---\n\n### Get Outbound Fax Image\n    \nRetrieve the fax image (TIFF file) of a submitted fax.\n\n```java    \nInterFAX interFAX = new DefaultInterFAXClient();\nbyte[] faxImage = interFAX.getOutboundFaxImage(\"667915751\");\n```\n    \n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2941)    \n\n---\n\n### Cancel a Fax\n    \nCancel a fax in progress.\n    \n```java    \nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.cancelFax(\"279499862\");\n```\n        \n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2939)    \n\n---\n\n### Search Fax List\n\nSearch for outbound faxes.\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nOutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList();\n```\n\nUsing additional **Options:** [`ids`, `reference`, `dateFrom`, `dateTo`, `status`, `userId`, `faxNumber`, `limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2959)\n\n```java\nSearchFaxOptions searchFaxOptions = new SearchFaxOptions();\nsearchFaxOptions.setLimit(Optional.of(3));\nsearchFaxOptions.setFaxNumber(Optional.of(\"+442084978672\"));\nInterFAX interFAX = new DefaultInterFAXClient();\nOutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList(Optional.of(searchFaxOptions));\n```    \n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2959)    \n\n---\n\n### Hide Fax\n\nHide a fax from listing in queries (there is no way to unhide a fax).\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.hideFax(\"667915469\");\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2940)\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\nRetrieves a user's list of inbound faxes. (Sort order is always in descending ID).\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nInboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList();\n```\n    \nUsing additional **Options:** [`unreadOnly`, `limit`, `lastId`, `allUsers`](https://www.interfax.net/en/dev/rest/reference/2935)\n    \n```java\nGetInboundFaxListOptions getInboundFaxListOptions = new GetInboundFaxListOptions();\ngetInboundFaxListOptions.setAllUsers(Optional.of(true));\ngetInboundFaxListOptions.setUnreadOnly(Optional.of(true));\ngetInboundFaxListOptions.setLimit(Optional.of(3));\nInterFAX interFAX = new DefaultInterFAXClient();\nInboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList(Optional.of(getInboundFaxListOptions));\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2935)\n\n---\n\n### Get Inbound Fax Record\n\nRetrieves a single fax's metadata (receive time, sender number, etc.).\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nInboundFaxStructure inboundFaxStructure = interFAX.getInboundFaxRecord(\"292626603\");\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2938)\n\n---\n\n### Get Inbound Fax Image\n\nRetrieves a single fax's image.\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nbyte[] faxImage = interFAX.getInboundFaxImage(292626603);\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2937)   \n\n---\n\n### Get Forwarding Emails\n \nRetrieve the list of email addresses to which a fax was forwarded.\n\n```java \nInterFAX interFAX = new DefaultInterFAXClient();\nInboundFaxesEmailsStructure inboundFaxesEmailsStructure = interFAX.getInboundFaxForwardingEmails(\"1234567\");\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2930)\n\n---\n\n### Mark As Read/Unread\n\nMark a transaction as read/unread.\n```java     \nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.markInboundFax(\"292626603\", Optional.of(true));\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2936)\n\n---\n\n### Resend Inbound Fax\n\nResend an inbound fax to a specific email address.\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.resendInboundFax(\"292626603\", Optional.of(\"someone@example.com\"));\n```\n    \n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2929)\n\n## Documents\n\n[Upload Document](#upload-document) | [Get list](#get-document-list) | [Status](#get-document-status) | [Get Upload Status](Get-upload-status) | [Cancel](#cancel-document)\n\nDocument uploads are useful for several situations:\n\n* When your documents are larger than our [System Limitations](https://www.interfax.net/en/help/limitations) \nallow and you want to submit them in chunks.\n* When you plan to reuse a document for multiple faxes.\n* When you want a document to be available for use by other users in \nyour account.\n\n### Upload Document\n\nUpload a large file in 1 MB chunks\n\n```java\nString absoluteFilePath = this.getClass().getClassLoader().getResource(\"A17_FlightPlan.pdf\").getFile();\nFile file = new File(absoluteFilePath);\n\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.uploadDocument(file);\n```\n    \nWith additional options,\n\n```java\nString absoluteFilePath = this.getClass().getClassLoader().getResource(\"A17_FlightPlan.pdf\").getFile();\nFile file = new File(absoluteFilePath);\n\nInterFAX interFAX = new DefaultInterFAXClient();\nDocumentUploadSessionOptions documentUploadSessionOptions = new DocumentUploadSessionOptions();\ndocumentUploadSessionOptions.setName(Optional.of(\"overriddenname.pdf\"));\ndocumentUploadSessionOptions.setSize(Optional.of(Integer.toUnsignedLong(12345)));\ndocumentUploadSessionOptions.setDisposition(Optional.of(Disposition.multiUse));\ndocumentUploadSessionOptions.setSharing(Optional.of(Sharing.privateDoc));\nAPIResponse apiResponse = interFAX.uploadDocument(file, Optional.of(documentUploadSessionOptions));\n```\n\n**More:** [documentation - 1](https://www.interfax.net/en/dev/rest/reference/2967), [2](https://www.interfax.net/en/dev/rest/reference/2966)\n\n---\n\n### Get Document List\n\nGet a list of previous document uploads which are currently available.\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nUploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList();\n```\n    \nWith additional **Options:** [`limit`, `offset`](https://www.interfax.net/en/dev/rest/reference/2968)\n\n```java    \nInterFAX interFAX = new DefaultInterFAXClient();\nGetUploadedDocumentsListOptions getUploadedDocumentsListOptions = new GetUploadedDocumentsListOptions();\ngetUploadedDocumentsListOptions.setLimit(Optional.of(5));\ngetUploadedDocumentsListOptions.setOffset(Optional.of(1));\nUploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList(Optional.of(getUploadedDocumentsListOptions));    \n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2968)\n\n---\n\n### Get Upload Status\n\nGet the current status of a specific document upload.\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nUploadedDocumentStatus uploadedDocumentStatus = interFAX.getUploadedDocumentStatus(\"deca890355b44b42944970d9773962b5\");\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2965)    \n\n---\n\n### Cancel Document\n\nCancel a document upload and tear down the upload session, or delete a previous upload.\n\n```java\nInterFAX interFAX = new DefaultInterFAXClient();\nAPIResponse apiResponse = interFAX.cancelDocumentUploadSession(\"deca890355b44b42944970d9773962b5\");\n```\n\n**More:** [documentation](https://www.interfax.net/en/dev/rest/reference/2964)       \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   \nThe project is setup using maven and tests can be run using the \nfollowing command:\n\n```shell\n$ mvn clean test\n```\n     \n### Releasing\n    \n#### Versioning\n\nThe project uses [semver](http://semver.org/) for versioning. \n\n##### Minor Releases\n\nIf a change is backwards compatible, it can be committed and pushed straight to master. Versioning is handled \nautomatically by incrementing the **minor version** by 1 and released automatically by travisCI, using the \n[release script](scripts/release.sh).\n\n##### Major Releases\n\nFor breaking changes / major releases, the version number needs to be manually updated in the [project pom](pom.xml). \nSimply **increment the major version by 1** and **drop the minor version to 0**. Example, if the version in the project\npom is as follows:\n\n```xml\n\u003cversion\u003e0.34-SNAPSHOT\u003c/version\u003e\n```\n\nA major change should update it to:\n\n```xml\n\u003cversion\u003e1.0-SNAPSHOT\u003c/version\u003e\n```\n\nOnce updated, committed and pushed to master, travisCI handles releasing the version to maven central. \n    \n## License\n\nThis library is released under the [MIT License](LICENCE).    \n        \n    \n         \n         \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterfax%2Finterfax-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterfax%2Finterfax-java/lists"}