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.14</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.