Installation | Getting Started | Running Tests | Contributing | License
Send and receive faxes in CLI Languages with the InterFAX REST API.
(examples are in C#)
This library targets .NET Standard 2.0/.NET 4.6.1+ and is installed via NuGet:
Install-Package InterFAX.Api -Version 3.1.5
For a full list of supported platforms see the .NET Standard reference documentation.
The legacy PCL format package targetting .NET 4.5.2 is available as version 1.X.X:
Install-Package InterFAX.Api -Version 1.0.5
Warning: If building with VS2015, the NuGet package manager must be updated to v3.6+ in order to recognise .NET Standard packages within the IDE (download). If required, the updated package manager will additionally prompt and link to install an updated .NET standard runtime.
(Advanced) For use with the PCI compliant InterFAX API, select the InterFAX_PCI root during initialization (See Client)
Client | Account | Outbound | Inbound | Documents
Credentials are set through environment variables, or passed as parameters directly during initialization. Credentials passed as parameters take precedence over those set in the environment.
using InterFAX.Api;
// | Initialize using parameters
var interfax = new FaxClient(username: "...", password: "...");
// | Initialize using Environment variables
// key : string
// INTERFAX_USERNAME : InterFax Username
// INTERFAX_PASSWORD : InterFax Password
var interfax = new FaxClient();
// Initialize with a specific InterFAX API Endpoint (EG PCI Compliant)
// InterFAX_Default: https://www.interfax.net/en-us/dev/rest/reference
// InterFAX_PCI: https://www.interfax.net/en-us/dev/rest_pci/reference
var interfax = new FaxClient(apiRoot: FaxClient.ApiRoot.InterFAX_PCI);
// Locale specific endpoints for data-sovereignty
// InterFAX_US_PCI: USA
var interfax = new FaxClient(apiRoot: FaxClient.ApiRoot.InterFAX_US_PCI);
// InterFAX_CA_PCI: Canada
var interfax = new FaxClient(apiRoot: FaxClient.ApiRoot.InterFAX_CA_PCI);Use of configurationManager was removed in 2.0.0, due to conversion to .NET Standard.
All connections are established over HTTPS.
Client must support TLS 1.1+ as of June 30th 2018 (See TLS 1.0 End of Life)
async Task<decimal> GetBalance();
Determine the remaining faxing credits in your account.
var interfax = new FaxClient();
var balance = await interfax.Account.GetBalance();
Console.WriteLine($"Account balance is {balance}"); //=> Account balance is 9.86More: documentation
Send | Get list | Get completed list | Get record | Get image stream | Cancel fax | Search
async Task<int> SendFax(IFaxDocument faxDocument, SendOptions options)
async Task<int> SendFax(List<IFaxDocument> faxDocuments, SendOptions options)
Submit a fax to a single destination number. Returns the messageId of the fax.
For small documents, there are a few ways to send a fax. You can directly provide a file path, a file stream or a url, which can be a web page anywhere or a link to a previously uploaded document resource (see Documents).
var options = new SendOptions { FaxNumber = "+11111111112"};
// with a path
var fileDocument = interfax.Documents.BuildFaxDocument(@".\folder\fax.txt");
var messageId = await interfax.Outbound.SendFax(fileDocument, options);
// with a stream
// NB : the caller is responsible for opening and closing the stream.
using (var fileStream = File.OpenRead(@".\folder\fax.txt"))
{
var fileDocument = interfax.Documents.BuildFaxDocument("fax.txt", fileStream);
var messageId = await interfax.Outbound.SendFax(fileDocument, options);
}
// with a byte array
byte[] file = ...
var urlDocument = interfax.Documents.BuildFaxDocument(file, ".pdf"));
var messageId = await interfax.Outbound.SendFax(urlDocument, options);
// with a URL
var urlDocument = interfax.Documents.BuildFaxDocument(new Uri("https://s3.aws.com/example/fax.html"));
var messageId = await interfax.Outbound.SendFax(urlDocument, options);
// or a combination
var documents = new List<IFaxDocument> { fileDocument, urlDocument };
var messageId = await interfax.Outbound.SendFax(documents, options)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 supported types are mapped to media types in the file SupportedMediaTypes.json - this can be modified by hand.
The returned object is the Id of the fax. Use this Id to load more information, get the image, or cancel the sending of the fax.
var result = await interfax.CancelFax(messageId);
// result in this case is just "OK".async Task<IEnumerable<OutboundFaxSummary>> GetList(Outbound.ListOptions options = null);
Get a list of recent outbound faxes (which does not include batch faxes).
var faxes = await interfax.Outbound.GetList();Outbound.ListOptions: Limit, LastId, SortOrder, UserId
async Task<IEnumerable<OutboundFaxSummary>> GetCompleted(params int[] ids)
Get details for a subset of completed faxes from a submitted list. (Submitted id's which have not completed are ignored).
var completed = await interfax.Outbound.GetCompleted(1, 2, 3);More: documentation
async Task<OutboundFaxSummary> GetFaxRecord(Int64 id);
Retrieves information regarding a previously-submitted fax, including its current status.
var fax = interfax.Outbound.GetFaxRecord(123456)More: documentation
async Task<Stream> GetFaxImageStream(Int64 id);
Retrieve the fax image stream (TIFF file) of a submitted fax.
using (var imageStream = await _interfax.Outbound.GetFaxImageStream(662208217))
{
using (var fileStream = File.Create(@".\image.tiff"))
{
InterFAX.Utils.CopyStream(imageStream, fileStream);
}
}More: documentation
async Task<string> CancelFax(Int64 id)
Cancel a fax in progress.
var result = interfax.Outbound.CancelFax(123456)
// => OKMore: documentation
async Task<IEnumerable<OutboundFax>> SearchFaxes(SearchOptions searchOptions)
Search for outbound faxes.
var faxes = await interfax.Outbound.Search(new SearchOptions {
faxNumber = '+1230002305555'
});Options: Ids, Reference, DateFrom, DateTo, Status, UserId, FaxNumber, Limit, Offset
Get list | Get record | Get image stream | Get emails | Mark as read | Resend to email
async Task<IEnumerable<InboundFax>> GetList(ListOptions listOptions = null)
Retrieves a user's list of inbound faxes. (Sort order is always in descending ID).
var faxes = await interfax.Inbound.GetList(new ListOptions { UnreadOnly = true });Options: UnreadOnly, Limit, LastId, AllUsers
async Task<InboundFax> GetFaxRecord(Int64 id)
Retrieves a single fax's metadata (receive time, sender number, etc.).
var fax = await interfax.Inbound.GetFaxRecord(123456);More: documentation
async Task<Stream> GetFaxImageStream(Int64 id)
Retrieves a single fax's image.
using (var imageStream = await _interfax.Inbound.GetFaxImageStream(291704306))
{
using (var fileStream = File.Create(@".\image.tiff"))
{
Utils.CopyStream(imageStream, fileStream);
}
}More: documentation
async Task<IEnumerable<ForwardingEmail>> GetForwardingEmails(Int64 id)
Retrieve the list of email addresses to which a fax was forwarded.
var emails = await interfax.Inbound.GetForwardingEmails(12345);
foreach(var email in emails)
Console.WriteLine($"{email.EmailAddress}, {email.MessageStatus}, {email.CompletionTime.ToString("s")}")More: documentation
async Task<string> MarkRead(Int64 id)
async Task<string> MarkUnread(Int64 id)
Mark a transaction as read/unread.
// mark as read
var result = interfax.Inbound.MarkRead(123456);
// => OK
// mark as unread
var result = interfax.Inbound.MarkUnread(123456);
// => OKMore: documentation
async Task<string> Resend(Int64 id, string emailAddress = null)
Resend an inbound fax, optionally to a specific email address.
// resend to the email(s) to which the fax was previously forwarded
var result = await interfax.Inbound.Resend(123456);
// => OK
// resend to a specific address
var result = await interfax.Inbound.Resend(123456) "[email protected]");
// => OKMore: documentation
Create document upload session | Upload chunk | Get upload session list | Status | Cancel
Document upload sessions allow for uploading of large files up to 20MB in chunks of arbitrary size.
You can do this with either a file path :
UploadSession UploadDocument(string filePath)
var fileInfo = new FileInfo("test.pdf"));
var session = _interfax.Outbound.Documents.UploadDocument(fileInfo.FullName);Or with a file stream :
UploadSession UploadDocument(string fileName, FileStream fileStream)
using (var fileStream = File.OpenRead("test.pdf"))
{
var session = _interfax.Outbound.Documents.UploadDocument(filePath, fileStream);
}The Uri property of the returned session object can be used when sending a fax.
If you want to control the chunking yourself, the following example shows how you could upload a file in 500 byte chunks:
var fileInfo = new FileInfo("large.pdf");
var sessionId = CreateUploadSession(new UploadSessionOptions
{
Name = fileInfo.Name,
Size = (int) fileInfo.Length
}).Result;
using (var fileStream = File.OpenRead(filePath))
{
var buffer = new byte[500];
int len;
while ((len = fileStream.Read(buffer, 0, buffer.Length)) > 0)
{
var data = new byte[len];
Array.Copy(buffer, data, len);
var response = UploadDocumentChunk(sessionId, fileStream.Position - len, data).Result;
if (response.StatusCode == HttpStatusCode.Accepted) continue;
if (response.StatusCode == HttpStatusCode.OK) break;
}
}async Task<string> CreateUploadSession(UploadSessionOptions options)
Create a document upload session, allowing you to upload large files in chunks.
var sessionId = _interfax.Outbound.Documents.CreateUploadSession(options);Options: Disposition, Sharing
async Task<HttpResponseMessage> UploadDocumentChunk(string sessionId, long offset, byte[] data)
Upload a chunk to an existing document upload session. The offset refers to the offset in the unchunked file not the data parameter.
var response = UploadDocumentChunk(sessionId, offset, data).Result;
// HttpStatusCode.OK (done) or HttpStatusCode.Accepted (unfinished)More: documentation
async Task<IEnumerable<UploadSession>> GetUploadSessions(ListOptions listOptions = null)
Get a list of previous document uploads which are currently available.
var list = _interfax.Outbound.Documents.GetUploadSessions(new Documents.ListOptions
{
Offset = 10,
Limit = 5
}).Result;Options: Limit, Offset
async Task<UploadSession> GetUploadSession(string sessionId)
Get the current status of a specific document upload session.
var session = interfax.Documents.GetUploadSession(123456);More: documentation
interfax.documents.cancel(document_id, callback);
Cancel a document upload and tear down the upload session, or delete a previous upload.
var result = await interfax.Outbound.Documents.CancelUploadSession(sessionId);
// => OKMore: documentation
- Build the project
- Open the Test Explorer Test > Windows > Test Explorer
- "Run All"
- Install the .NET Core SDK
- Run
dotnet testin the root or desired test folder
Integration tests require valid api credentials to pass, these can be provided within the testingConfig.cs within. A free developer account can be registered at https://www.interfax.net/en/dev/register.
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull request so that we can review your changes
This library is released under the MIT License.