Receiving a Fax

As faxes arrive at etherFAX, they are immediately available for download once the fax receive operation has completed. Using the inbox functions, programmers can easily query the number of unread faxes available, retrieve lists of unread faxes, and download the faxes for processing.

Fax applications using this API simply query the etherFAX REST API every 30-60 seconds looking for newly arrived faxes.

Retrieve the number unread faxes. Use this function to simply determine if there are faxes available for download.

var unread = client.GetUnreadFaxCount();

Retrieve a list of unread faxes, including all metadata associated with the fax. The following example will return a list of FaxReceive objects (one for each fax received). You may optionally pass a count parameter to GetUnreadFaxList() to limit the number of items returned in the list.

// retrieve unread fax list
var faxList = client.GetUnreadFaxList();
foreach (var fax in faxList)
{
    // retrieve the full fax (including image data)
    var f = client.GetFax(fax.JobId);

    // process fax, image data in byte[] f.FaxImage
    // ...

    // mark fax as received
    client.SetFaxReceived(fax.JobId);
}

In some configurations, developers may have multiple instances of their fax applications running for fault-tolerant and high-availability reasons. In such cases, developers can make use of the GetNextUnreadFax() method to resolve fax receive contention. When this method is used against the etherFAX network, an immediate 5-minute lock is placed on the item so it will not appear in the unread fax item list and allow time for the requesting application to complete the download and mark the fax as received (this operation normally just takes a few seconds, even for large faxes).

while (true)
{
    var fax = client.GetNextUnreadFax();
    if (fax == null)
        break;

    // process fax
    // ..

    // mark fax as received
    client.SetFaxReceived(fax.JobId);
}

📘
Note
When using the GetNextUnreadFax() method, the download parameter should be set to true if you wish to have the fax image content downloaded all in one operation.

The following illustrates a typical unread fax list:

[
  {
    "JobId": "833fd712-2ca2-4c7b-8b26-8166629963de",
    "FaxResult": 0,
    "ConnectTime": 56,
    "ConnectSpeed": 33600,
    "PagesReceived": 2,
    "RemoteId": "9085551234",
    "CalledNumber": "+18005551234",
    "CallingNumber": "2125551234",
    "ReceivedOn": "2015-10-27T21:47:37.92",
    "FaxImage": null
  },
  {
    "JobId": "c12e1f95-77e7-4471-a456-508e43daa9a9",
    "FaxResult": 0,
    "ConnectTime": 68,
    "ConnectSpeed": 33600,
    "PagesReceived": 3,
    "RemoteId": "9085551234",
    "CalledNumber": "+18005551234",
    "CallingNumber": "2125551234",
    "ReceivedOn": "2015-10-27T21:47:43.14",
    "FaxImage": null
  }
]

📘Note

📘
Note