ReplixFax OutBound Fax API

ReplixFax Visual Basic SOAP API Tutorial

Using the ReplixFax Cloud Service to send faxes is straightforward. All you need is a valid username and password, a destination fax number and a document to be sent as the fax. This tutorial describes the steps to create a Visual Basic .Net application in Visual Studio that sends a fax using the ReplixFax SOAP API.

You can Download the completed tutorial or follow the steps below.

Create a Visual Studio Console Application.

This tutorial uses Visual Studio 2008, however the code and concepts are applicable to later Visual Studio versions.

Select Visual Basic/Windows/Console project. Name it SendAFax.

Add a Web Service Reference

In the Solution Explorer, right mouse select the References folder and then select “Add Service Reference…”

Enter https://api.rpxtest.com/softlinx/replixfax/wsapi in the Address field. Then press “Go”. Change the Namespace to be “ReplixFax”. Then click “OK”.

Visual Studio will create wrapper classes for the ReplixFax Web Services.

Helper function

Before we start using the wrapper classes, we need a helper function that will be used when specifying the password. Add the following function to the Module1.vb file:

    Function EncodeTo64(ByVal toEncode As String) As String
        Dim toEncodeAsBytes = System.Text.ASCIIEncoding.ASCII.GetBytes(toEncode)
        Return System.Convert.ToBase64String(toEncodeAsBytes)
    End Function

Create a ReplixFaxPortClient object and set its credentials.

Now we can create a ReplixFaxPortClient.

Sub Main()
    Dim binding As New System.ServiceModel.BasicHttpBinding()

    binding.Security.Mode = System.ServiceModel.BasicHttpSecurityMode.None

    binding.Security.Mode = System.ServiceModel.BasicHttpSecurityMode.Transport
    binding.Security.Transport.ClientCredentialType = ServiceModel.HttpClientCredentialType.Basic
    binding.MessageEncoding = ServiceModel.WSMessageEncoding.Mtom
    binding.MaxReceivedMessageSize = 104857600

    Dim endpointStr = "https://api.rpxtest.com/softlinx/replixfax/wsapi"
    Dim endpoint = New System.ServiceModel.EndpointAddress(endpointStr)

    Dim client As New ReplixFax.ReplixFaxPortClient(binding, endpoint)
    client.ClientCredentials.UserName.UserName = "anonymous"
End Sub

You can change the EndpointAddress after testing to point to production: https://api.rpxfax.com/softlinx/replixfax/wsapi

Since we are NOT using basic authentication, client.ClientCredentials.UserName.UserName is set to “anonymous”. We will be passing the real username and password inside the SOAP message.

Now create a new Authentication object and set the username and pasword. We will be using the helper function added in a previous step to encode the password. You should replace <organization name>, <username> and <password> with your credentials.

Dim auth As New ReplixFax.Authentication
auth.Login = "<username>"
auth.Password = EncodeTo64("<password>")
auth.PasswordSecurity = "base64"
auth.Realm = "<organization>"

Create a SendFaxInput object

When making any ReplixFax web service call, you must pass a corresponding input object. Since we are going to send a fax, we need to create a SendFaxInput object and set its Authentication to the Authenitcation object created in the previous step.

Dim input As New ReplixFax.SendFaxInput
input.Authentication = auth

Now set the recipient. You can have a list of recipients, but for this tutorial, we wil have a single recipient. Also each recipient can have attributes set, such ad company and title. These attributes are only used if a ReplixFax coverpage template is being used. Since we are not using a cover page, then all we need is the fax number for the recipient.

Dim recipients(1) As ReplixFax.FaxRecipient
recipients(0) = New ReplixFax.FaxRecipient
recipients(0).FaxNumber = "<fax number>"

input.FaxRecipient = recipients

Once the recipient is specified, you should add the attachment. You can have a list of attachments, but for the tutorial we will only have one file. The order you specify the attachments dictates the page order of the fax. So if you had your own cover page, you could specify that file as the first attachment and have a second attachment as the remainder of the fax.

Dim attachments(1) As ReplixFax.Attachment
attachments(0) = New ReplixFax.Attachment
attachments(0).FileName = "<filename>"

Dim bytes = My.Computer.FileSystem.ReadAllBytes("<path to file>")
attachments(0).AttachmentContent = bytes

input.Attachment = attachments

Make a SendFax Request

To send the fax request to the server, call SendFax and pass in the SendFaxInput object. As mentioned before all ReplixFax service calls require a corresponding input object. They also return a corresponding output object. In this case, SendFaxOutput.

Dim output As New ReplixFax.SendFaxOutput
output = client.SendFax(input)

The SendFaxOutput object will contain a status code and optional message. It will also contain the fax job IDs created. There will be a fax job id for each recipient. Since we only specified a single recipient, we only have one fax job id.

Console.Out.WriteLine("StatusCode is " & output.RequestStatus.StatusCode)
Console.Out.WriteLine("StatusText is " & output.RequestStatus.StatusText)
Console.Out.WriteLine("FaxId= " & output.FaxInfo(0).FaxId)

Check the status of the Outgoing Fax

When a fax request is made, it must be processed by the system and then it is scheduled to be faxed. The system processing includes converting all document files to tiff and generating cover pages if a ReplixFax template cover page is being used. When a fax is ready to be sent, potentially the recipient fax machine (or server) is busy and does not have any open lines. Therefore it is difficult to determine when a fax will be successfully sent and received by the recipient fax machine or server.

In order to check the status of a fax, you need to query the system. Look at the Query Sent Faxes sample to see how to do this.

Next steps

The Visual Basic samples show how to perform other common Fax tasks. If you have questions about this tutorial or other API related items, contact Softlinx support.

ReplixFax Tutorials