Installation | Getting Started | Usage | Contributing | License
Send and receive faxes in Java with the InterFAX REST API.
Use of the library requires Java 8 or higher and can be done via one of the following approaches.
<dependency>
<groupId>net.interfax</groupId>
<artifactId>api-client</artifactId>
<version>0.12</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.File file = new File(absoluteFilePath);
InterFAX interFAX = new DefaultInterFAXClient("username", "password");
APIResponse apiResponse = 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 parameters
InterFAX interFAX = new DefaultInterFAXClient("username", "password");
// Alternative 1: Initialize using environment variables
// Ensure following env vars are initialized with values of your API credentials
// * INTERFAX_USERNAME
// * INTERFAX_PASSWORD
InterFAX interFAX = new DefaultInterFAXClient();
// 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"
InterFAX interFAX = new DefaultInterFAXClient();All connections are established over HTTPS.
Determine the remaining faxing credits in your account
InterFAX interFAX = new DefaultInterFAXClient();
Double balance = 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 absoluteFilePath
java.io.File file = new File(absoluteFilePath);
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.sendFax(faxNumber, file);
// with an inputstream
InputStream[] inputStreams = {inputStream};
String[] mediaTypes = {"application/pdf"};
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.sendFax(faxNumber, inputStreams, mediaTypes);
// with a URL
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = 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 Files
public APIResponse sendFax(final String faxNumber,
final File[] filesToSendAsFax)
throws IOException;
// using Inputstreams
public APIResponse sendFax(final String faxNumber,
final InputStream[] streamsToSendAsFax,
final String mediaTypes[]) throws IOException; 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).
InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getFaxList();Using additional Options: limit, lastId, sortOrder, userId
GetFaxListOptions getFaxListOptions = new GetFaxListOptions();
getFaxListOptions.setLimit(Optional.of(5));
InterFAX interFAX = new DefaultInterFAXClient();
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).
InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.getCompletedFaxList(new String[]{"667915751", "667915471"});More: documentation
Retrieves information regarding a previously-submitted fax, including its current status.
InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure outboundFaxStructure = interFAX.getOutboundFaxRecord("667915751");More: documentation
Retrieve the fax image (TIFF file) of a submitted fax.
InterFAX interFAX = new DefaultInterFAXClient();
byte[] faxImage = interFAX.getOutboundFaxImage("667915751");More: documentation
Cancel a fax in progress.
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.cancelFax("279499862");More: documentation
Search for outbound faxes.
InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList();Using additional Options: ids, reference, dateFrom, dateTo, status, userId, faxNumber, limit, offset
SearchFaxOptions searchFaxOptions = new SearchFaxOptions();
searchFaxOptions.setLimit(Optional.of(3));
searchFaxOptions.setFaxNumber(Optional.of("+442084978672"));
InterFAX interFAX = new DefaultInterFAXClient();
OutboundFaxStructure[] outboundFaxStructures = interFAX.searchFaxList(Optional.of(searchFaxOptions));More: documentation
Hide a fax from listing in queries (there is no way to unhide a fax).
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = 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).
InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList();Using additional Options: unreadOnly, limit, lastId, allUsers
GetInboundFaxListOptions getInboundFaxListOptions = new GetInboundFaxListOptions();
getInboundFaxListOptions.setAllUsers(Optional.of(true));
getInboundFaxListOptions.setUnreadOnly(Optional.of(true));
getInboundFaxListOptions.setLimit(Optional.of(3));
InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxStructure[] inboundFaxStructures = interFAX.getInboundFaxList(Optional.of(getInboundFaxListOptions));More: documentation
Retrieves a single fax's metadata (receive time, sender number, etc.).
InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxStructure inboundFaxStructure = interFAX.getInboundFaxRecord("292626603");More: documentation
Retrieves a single fax's image.
InterFAX interFAX = new DefaultInterFAXClient();
byte[] faxImage = interFAX.getInboundFaxImage(292626603);More: documentation
Retrieve the list of email addresses to which a fax was forwarded.
InterFAX interFAX = new DefaultInterFAXClient();
InboundFaxesEmailsStructure inboundFaxesEmailsStructure = interFAX.getInboundFaxForwardingEmails("1234567");More: documentation
Mark a transaction as read/unread.
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.markInboundFax("292626603", Optional.of(true));More: documentation
Resend an inbound fax to a specific email address.
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.resendInboundFax("292626603", Optional.of("[email protected]"));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
String absoluteFilePath = this.getClass().getClassLoader().getResource("A17_FlightPlan.pdf").getFile();
File file = new File(absoluteFilePath);
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = interFAX.uploadDocument(file);With additional options,
String absoluteFilePath = this.getClass().getClassLoader().getResource("A17_FlightPlan.pdf").getFile();
File file = new File(absoluteFilePath);
InterFAX interFAX = new DefaultInterFAXClient();
DocumentUploadSessionOptions documentUploadSessionOptions = new DocumentUploadSessionOptions();
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));
APIResponse apiResponse = interFAX.uploadDocument(file, Optional.of(documentUploadSessionOptions));More: documentation - 1, 2
Get a list of previous document uploads which are currently available.
InterFAX interFAX = new DefaultInterFAXClient();
UploadedDocumentStatus[] uploadedDocumentStatuses = interFAX.getUploadedDocumentsList();With additional Options: limit, offset
InterFAX interFAX = new DefaultInterFAXClient();
GetUploadedDocumentsListOptions getUploadedDocumentsListOptions = new GetUploadedDocumentsListOptions();
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.
InterFAX interFAX = new DefaultInterFAXClient();
UploadedDocumentStatus uploadedDocumentStatus = interFAX.getUploadedDocumentStatus("deca890355b44b42944970d9773962b5");More: documentation
Cancel a document upload and tear down the upload session, or delete a previous upload.
InterFAX interFAX = new DefaultInterFAXClient();
APIResponse apiResponse = 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.