FaxCore.Ev6.RestClient 2.0.0

FaxCore EV6 REST Client

A .NET client library for the FaxCore EV6 REST API. Handles OAuth authentication, HTTP communication, and serialization so you can focus on integrating fax capabilities into your application.

Supported Frameworks

Installation

dotnet add package FaxCore.Ev6.RestClient

Or via the NuGet Package Manager:

Install-Package FaxCore.Ev6.RestClient

Quick Start

Prerequisites

You need a FaxCore EV6 server and a set of OAuth client credentials (client ID and client secret) configured on that server.

Direct Instantiation

FaxClient implements IDisposable — use a using block or dispose manually:

using FaxCore.Ev6.RestClient;

using (var client = new FaxClient("https://your-faxcore-server.com", "your-client-id", "your-client-secret"))
{
    var status = await client.GetMessageStatus(messageId);
}

With IHttpClientFactory (Recommended for ASP.NET Core)

Pass an externally managed HttpClient to avoid socket exhaustion in high-throughput scenarios. The provided HttpClient will not be disposed when the FaxClient is disposed:

using FaxCore.Ev6.RestClient;

// In Startup.cs / Program.cs
services.AddHttpClient("FaxCore");
services.AddSingleton<IFaxClientFactory, FaxClientFactory>();

services.AddScoped<IFaxClient>(provider =>
{
    var httpClientFactory = provider.GetRequiredService<IHttpClientFactory>();
    var httpClient = httpClientFactory.CreateClient("FaxCore");
    var factory = provider.GetRequiredService<IFaxClientFactory>();
    return factory.Create("https://your-faxcore-server.com", "your-client-id", "your-client-secret", httpClient);
});

Dependency Injection (Simple)

Register the client with your IoC container using the built-in factory:

using FaxCore.Ev6.RestClient;

services.AddSingleton<IFaxClientFactory, FaxClientFactory>();

services.AddSingleton<IFaxClient>(provider =>
{
    var factory = provider.GetRequiredService<IFaxClientFactory>();
    return factory.Create("https://your-faxcore-server.com", "your-client-id", "your-client-secret");
});

Then inject IFaxClient into your classes:

public class FaxService
{
    private readonly IFaxClient _faxClient;

    public FaxService(IFaxClient faxClient)
    {
        _faxClient = faxClient;
    }
}

Usage Examples

Sending a Fax

Sending a fax is a two-step process: first upload the document, then send the message with the upload response.

// Step 1: Upload the document
var uploadResult = await _faxClient.UploadFile("/path/to/document.pdf");
var uploadedFile = uploadResult.Data.First();

// Step 2: Build and send the message
var request = new SendMessageRequest<MessageRecipient>
{
    Message = new MessageRequest<MessageRecipient>
    {
        SenderName = "John Doe",
        Subject = "Invoice #1234",
        Note = "Please review the attached invoice.",
        Priority = 70,
        Recipients = new List<MessageRecipient>
        {
            new MessageRecipient
            {
                Address = "15551234567",
                Name = "Jane Smith",
                IsRawFax = true
            }
        },
        Documents = new List<Document>
        {
            new Document
            {
                Name = uploadedFile.Id,
                Path = uploadedFile.FileName,
                IsMerge = false
            }
        },
        Agents = new List<Agent>(),
        Trackings = new List<Tracking>()
    }
};

var sendResult = await _faxClient.SendMessage(request);
string messageId = sendResult.Data.MessageId;

Checking Message Status

var status = await _faxClient.GetMessageStatus(messageId);
// status.Data.Status returns a MessageStatus enum:
// Completed, Failed, Processing, InQueue, InSchedule, Approved, etc.

Getting Message Details

var details = await _faxClient.GetMessageDetails(messageId);
var message = details.Data;

Downloading a Fax

var fileBytes = await _faxClient.DownloadMessage(new DownloadMessageRequest
{
    MessageID = messageId,
    DeliveryNum = 1,
    DownloadType = FileType.PDF
});

// Write to file
File.WriteAllBytes("downloaded-fax.pdf", fileBytes);

Listing Message Folders

var folders = await _faxClient.GetMessageFolders();
foreach (var folder in folders.Data)
{
    Console.WriteLine(folder.FolderName);
}

Searching Messages

var results = await _faxClient.SearchMessages(new MessageSearchRequest
{
    // Set your search criteria
});
// results.Data.Records contains the matching messages
// results.Data.Pagination contains paging info

Managing Users

// Create a user
var newUser = await _faxClient.CreateUser(new CreateUserRequest { /* ... */ });

// Get user details
var user = await _faxClient.GetUserDetails(userId);

// Search users
var searchResults = await _faxClient.UserSearch(new UserSearchRequest { /* ... */ });

// List users in a domain
var users = await _faxClient.UserList("domain-name");

Managing Contacts

// Create an address book
var addressBook = await _faxClient.CreateAddressBook("My Contacts");

// Add a contact
var contact = await _faxClient.CreateContact(new CreateContactRequest { /* ... */ });

// List contacts
var contacts = await _faxClient.ListContacts(new ContactListRequest { /* ... */ });

// Update a contact
await _faxClient.UpdateContact(new UpdateContactRequest { /* ... */ });

// Get a single contact
var singleContact = await _faxClient.GetContact(contactId);

Managing Printers

// List printers
var printers = await _faxClient.GetPrinters();

// Create a printer
await _faxClient.CreatePrinter(new CreatePrinterRequest { /* ... */ });

// Delete printers
await _faxClient.DeletePrinters(new List<int> { printerId1, printerId2 });

Managing Inbound Routes

// Create a routing rule
await _faxClient.CreateRoutingRule(new RouteCreateRequest { /* ... */ });

// Search routes
var routes = await _faxClient.SearchRoutingRules("search-term");

// Enable/disable routes
await _faxClient.EnableRoutingRule(routeId);
await _faxClient.DisableRoutingRule(routeId);

API Reference

All methods are asynchronous and return Task<T>. API responses are wrapped in FaxCoreResponse<T> (with Status, Message, and Data properties) or PagedResponse<T> for paginated results.

Messages

Files

Users

Contacts & Address Books

MFP

Printers

Domains

Routes

Cancellation and Timeout

All async methods accept an optional CancellationToken as the last parameter:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var status = await _faxClient.GetMessageStatus(messageId, cts.Token);

The default HTTP timeout is 1 minute. You can configure it via the constructor:

// 5-minute timeout for large file operations
var client = new FaxClient(url, clientId, clientSecret, null, TimeSpan.FromMinutes(5));

When providing an external HttpClient, the timeout parameter is ignored — configure the timeout on your HttpClient directly.

Resilience and Retry

This library does not include retry or circuit breaker policies by design. Different API operations have different idempotency characteristics (e.g., retrying SendMessage could double-send a fax), so resilience decisions are left to the consumer.

To add retry, circuit breaker, or other resilience policies, configure your HttpClient pipeline before passing it to FaxClient:

// Using Microsoft.Extensions.Http.Resilience or Polly
services.AddHttpClient("FaxCore")
    .AddStandardResilienceHandler();  // or .AddPolicyHandler(...)

// Then pass the configured HttpClient to FaxClient
var httpClient = httpClientFactory.CreateClient("FaxCore");
var client = new FaxClient(url, clientId, clientSecret, httpClient);

The library does perform a single automatic retry on transient server errors (5xx, network failures) during OAuth token refresh, since token acquisition is inherently idempotent.

Error Handling

The client throws FaxCoreException for API errors, which includes:

• ErrorCode — the HTTP status code
• HttpResponse — the raw response body from the server
• Message — a description of the error

try
{
    var result = await _faxClient.GetMessageDetails("invalid-id");
}
catch (FaxCoreException ex)
{
    Console.WriteLine($"Error {ex.ErrorCode}: {ex.Message}");
    Console.WriteLine($"Response: {ex.HttpResponse}");
}

Authentication failures (invalid credentials, expired tokens) throw FaxCoreException with the message "Authentication failed" and the server's error response.

Parameter validation errors (missing required fields) also throw FaxCoreException with an inner ArgumentException.

Contributing

Prerequisites

• .NET 8.0 SDK (required for building and running tests)
• Access to a FaxCore EV6 server (required for running integration tests)

Building

dotnet build src/FaxCoreRestClient.sln

Running Tests

Tests are integration tests that require a live FaxCore server. Set the following environment variables before running:

export FAX_SERVER_URL="https://your-faxcore-server.com"
export FAX_SERVER_CLIENT="your-client-id"
export FAX_SERVER_SECRET="your-client-secret"

You can also create a local_settings.sh file in the project root and source it:

source local_settings.sh

Then run the tests:

# Run all tests
dotnet test src/FaxCore.Tests/FaxCore.Tests.csproj

# Run a specific test
dotnet test src/FaxCore.Tests/FaxCore.Tests.csproj --filter "FullyQualifiedName~FaxIsSubmittedToFaxServerSuccessfully"

Project Structure

src/
├── FaxCoreRestClient.sln                # Solution file
├── FaxCore.Ev6.RestClient/              # Main library (NuGet package)
│   ├── FaxClient.cs                     # Public client — constructor, file upload, cover pages
│   ├── MessageClient.cs                 # Message operations (partial class)
│   ├── UserClient.cs                    # User operations (partial class)
│   ├── ContactsService.cs              # Contact/address book operations (partial class)
│   ├── DomainsClient.cs                # Domain operations (partial class)
│   ├── RoutesClient.cs                 # Routing operations (partial class)
│   ├── PrinterClient.cs               # Printer operations (partial class)
│   ├── MfpClient.cs                   # MFP operations (partial class)
│   ├── Endpoints.cs                   # API endpoint path constants
│   ├── FaxCoreBaseClient.cs            # Internal HTTP client (auth, serialization)
│   ├── FaxClientFactory.cs             # DI factory
│   ├── IFaxClient.cs                   # Public interface (extends IDisposable)
│   ├── Models/
│   │   ├── Request/                    # Request DTOs
│   │   ├── Response/                   # Response DTOs
│   │   └── Enumerators/               # Enums (MessageStatus, FileType, Role, etc.)
│   └── Tools/                          # JSON converters and utilities
├── FaxCore.Functional.Core/            # Utility library (Option<T> monad, Config)
├── FaxCore.Tests/                      # xUnit integration tests
└── FaxCore.Sandbox/                    # Console app for manual testing

The FaxClient class is split across multiple files using C# partial classes, organized by API domain (messages, users, contacts, domains, routes, printers, MFP).