Installation | Getting Started | Usage | Contributing | License
Send and receive faxes in Java with the InterFAX REST API.
Use of the library requires Java 11 or higher and can be done via one of the following approaches.
<dependency>
<groupId>net.interfax</groupId>
<artifactId>api-client</artifactId>
<version>0.17</version>
</dependency>Download the latest jar from the Maven central repository and place it in your application classpath.
To send a fax from a PDF file:
java.io.Filefile = newFile(absoluteFilePath);
InterFAXinterFAX = newDefaultInterFAXClient("username", "password");
APIResponseapiResponse = interFAX.sendFax(faxNumber, file);Client | Account | Outbound | Inbound | Documents
The client follows the 12-factor apps principle and can be either set directly or via environment variables.
// Initialize using parametersInterFAXinterFAX = newDefaultInterFAXClient("username", "password");
// Alternative 1: Initialize using environment variables// Ensure following env vars are initialized with values of your API credentials// * INTERFAX_USERNAME// * INTERFAX_PASSWORDInterFAXinterFAX = newDefaultInterFAXClient();
// Alternative 2: Initialize using yaml file// Create a file called `interfax-api-credentials.yaml` with the following contents, replacing the value of `username`// and `password` fields with those of your API credentials.// username: "api-username"// password: "api-password"InterFAXinterFAX = newDefaultInterFAXClient();All connections are established over HTTPS.
Determine the remaining faxing credits in your account
InterFAXinterFAX = newDefaultInterFAXClient();
Doublebalance = interFAX.getAccountCredits();More:documentation
Send | Get list | Get completed list | Get record | Get image | Cancel fax | Search | Hide fax
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 an absoluteFilePathjava.io.Filefile = newFile(absoluteFilePath);
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.sendFax(faxNumber, file);
// with an inputstreamInputStream[] inputStreams = {inputStream};
String[] mediaTypes = {"application/pdf"};
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.sendFax(faxNumber, inputStreams, mediaTypes);
// with a URLInterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.sendFax(faxNumber, "https://s3.aws.com/example/fax.html");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 APIResponse with the
statusCode and responseBody of the request submitted to InterFAX.
To send multiple files just pass in an array of files or inputstreams
// using FilespublicAPIResponsesendFax(finalStringfaxNumber, finalFile[] filesToSendAsFax) throwsIOException;
// using InputstreamspublicAPIResponsesendFax(finalStringfaxNumber,
finalInputStream[] streamsToSendAsFax,
finalStringmediaTypes[]) throwsIOException; All requests to send a fax can include the following Options:contact, postponeTime, retriesToPerform, csid, pageHeader, reference, pageSize, fitToPage, pageOrientation, resolution, rendering
set via SendFaxOptions class
Get a list of recent outbound faxes (which does not include batch faxes).
InterFAXinterFAX = newDefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList();Using additional Options:limit, lastId, sortOrder, userId
GetFaxListOptionsgetFaxListOptions = newGetFaxListOptions();
getFaxListOptions.setLimit(Optional.of(5));
InterFAXinterFAX = newDefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList(Optional.of(getFaxListOptions));More:documentation
Get details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).
InterFAXinterFAX = newDefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getCompletedFaxList(newString[]{"667915751", "667915471"});More:documentation
Retrieves information regarding a previously-submitted fax, including its current status.
InterFAXinterFAX = newDefaultInterFAXClient();
OutboundFaxStructureoutboundFaxStructure = interFAX.getOutboundFaxRecord("667915751");More:documentation
Retrieve the fax image (TIFF file) of a submitted fax.
InterFAXinterFAX = newDefaultInterFAXClient();
byte[] faxImage = interFAX.getOutboundFaxImage("667915751");More:documentation
Cancel a fax in progress.
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.cancelFax("279499862");More:documentation
Search for outbound faxes.
InterFAXinterFAX = newDefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList();Using additional Options:ids, reference, dateFrom, dateTo, status, userId, faxNumber, limit, offset
SearchFaxOptionssearchFaxOptions = newSearchFaxOptions();
searchFaxOptions.setLimit(Optional.of(3));
searchFaxOptions.setFaxNumber(Optional.of("+442084978672"));
InterFAXinterFAX = newDefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList(Optional.of(searchFaxOptions));More:documentation
Hide a fax from listing in queries (there is no way to unhide a fax).
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.hideFax("667915469");More:documentation
Get list | Get record | Get image | Get emails | Mark as read | Resend to email
Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).
InterFAXinterFAX = newDefaultInterFAXClient();
InboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList();Using additional Options:unreadOnly, limit, lastId, allUsers
GetInboundFaxListOptionsgetInboundFaxListOptions = newGetInboundFaxListOptions();
getInboundFaxListOptions.setAllUsers(Optional.of(true));
getInboundFaxListOptions.setUnreadOnly(Optional.of(true));
getInboundFaxListOptions.setLimit(Optional.of(3));
InterFAXinterFAX = newDefaultInterFAXClient();
InboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList(Optional.of(getInboundFaxListOptions));More:documentation
Retrieves a single fax's metadata (receive time, sender number, etc.).
InterFAXinterFAX = newDefaultInterFAXClient();
InboundFaxStructureinboundFaxStructure = interFAX.getInboundFaxRecord("292626603");More:documentation
Retrieves a single fax's image.
InterFAXinterFAX = newDefaultInterFAXClient();
byte[] faxImage = interFAX.getInboundFaxImage(292626603);More:documentation
Retrieve the list of email addresses to which a fax was forwarded.
InterFAXinterFAX = newDefaultInterFAXClient();
InboundFaxesEmailsStructureinboundFaxesEmailsStructure = interFAX.getInboundFaxForwardingEmails("1234567");More:documentation
Mark a transaction as read/unread.
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.markInboundFax("292626603", Optional.of(true));More:documentation
Resend an inbound fax to a specific email address.
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.resendInboundFax("292626603", Optional.of("someone@example.com"));More:documentation
Upload Document | Get list | Status | Get Upload Status | Cancel
Document uploads are useful for several situations:
- When your documents are larger than our System Limitations allow and you want to submit them in chunks.
- When you plan to reuse a document for multiple faxes.
- When you want a document to be available for use by other users in your account.
Upload a large file in 1 MB chunks
StringabsoluteFilePath = this.getClass().getClassLoader().getResource("A17_FlightPlan.pdf").getFile();
Filefile = newFile(absoluteFilePath);
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.uploadDocument(file);With additional options,
StringabsoluteFilePath = this.getClass().getClassLoader().getResource("A17_FlightPlan.pdf").getFile();
Filefile = newFile(absoluteFilePath);
InterFAXinterFAX = newDefaultInterFAXClient();
DocumentUploadSessionOptionsdocumentUploadSessionOptions = newDocumentUploadSessionOptions();
documentUploadSessionOptions.setName(Optional.of("overriddenname.pdf"));
documentUploadSessionOptions.setSize(Optional.of(Integer.toUnsignedLong(12345)));
documentUploadSessionOptions.setDisposition(Optional.of(Disposition.multiUse));
documentUploadSessionOptions.setSharing(Optional.of(Sharing.privateDoc));
APIResponseapiResponse = interFAX.uploadDocument(file, Optional.of(documentUploadSessionOptions));More:documentation - 1, 2
Get a list of previous document uploads which are currently available.
InterFAXinterFAX = newDefaultInterFAXClient();
UploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList();With additional Options:limit, offset
InterFAXinterFAX = newDefaultInterFAXClient();
GetUploadedDocumentsListOptionsgetUploadedDocumentsListOptions = newGetUploadedDocumentsListOptions();
getUploadedDocumentsListOptions.setLimit(Optional.of(5));
getUploadedDocumentsListOptions.setOffset(Optional.of(1));
UploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList(Optional.of(getUploadedDocumentsListOptions)); More:documentation
Get the current status of a specific document upload.
InterFAXinterFAX = newDefaultInterFAXClient();
UploadedDocumentStatusuploadedDocumentStatus = interFAX.getUploadedDocumentStatus("deca890355b44b42944970d9773962b5");More:documentation
Cancel a document upload and tear down the upload session, or delete a previous upload.
InterFAXinterFAX = newDefaultInterFAXClient();
APIResponseapiResponse = interFAX.cancelDocumentUploadSession("deca890355b44b42944970d9773962b5");More:documentation
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Test the changes you have made
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
Before submitting a contribution please ensure all tests pass.
The project is setup using maven and tests can be run using the following command:
$ mvn clean testThe project uses semver for versioning.
If a change is backwards compatible, it can be committed and pushed straight to master. Versioning is handled automatically by incrementing the minor version by 1 and released automatically by travisCI, using the release script.
For breaking changes / major releases, the version number needs to be manually updated in the project pom. Simply increment the major version by 1 and drop the minor version to 0. Example, if the version in the project pom is as follows:
<version>0.34-SNAPSHOT</version>A major change should update it to:
<version>1.0-SNAPSHOT</version>Once updated, committed and pushed to master, travisCI handles releasing the version to maven central.
This library is released under the MIT License.