Using cover pages

This tutorial provides information on how to use cover pages for Fax-for-Applications. A cover page can hide the first page of your fax for privacy reasons and personalize it for different recipients.

Hiding information behind a cover page

Let’s suppose you want to hide the first page of your fax document behind a cover page for data privacy reasons. To do so, follow these steps:

1. Select the cover page

→ Log in to the EAS portal and ensure the coverpage-default.ftl.html cover page is selected in your Faxolution-for-Applications account:

• Select Administration - Fax Services - Faxolution for Applications.

• Choose your login ID and select Show.

• Navigate to the Cover page template field and check that coverpage-default.ftl.html is selected.

2. Add data to fax cover pages

→ Include pairs of keys and values in the recipient part of your fax job request. The keys are the variable names, and the values contain the data to be written on the cover page. These variables can be used as keys in the default cover page:

• FromName

• FromCompanyName

• FromTelNum

• ToName

• ToCompanyName

• ToFaxNum

• SubjectTitle

• SubjectText

The screenshots below show how a request could look with some of the available variables.

Are you in the middle of embedding our API into your application? We have created SDKs for different programming languages on our GitHub presence that facilitate the task.

REST request example

JSON

"recipients": [
  {
        "number": "+4989123456789",
        "properties": [
            {
                "key": "FromName",
                "value": "Jon Doe"
            },
            {
                "key": "FromCompanyName",
                "value": "retarus GmbH"
            },
            {
                "key": "FromTelNum",
                "value": "123456789"
            },
            {
                "key": "ToName",
                "value": "Jane Doe"
            },
            {
                "key": "ToCompanyName",
                "value": "ACME Corp"
            },
            {
                "key": "ToFaxNum",
                "value": "987654321"
            }
        ]
    }
] 

SOAP request example

NONE

<faxRecipient>
  <number>+49123456789</number>
  <property>
      <key>FromName</key>
      <value>Jon Doe</value>
  </property>
  <property>
      <key>FromCompanyName</key>
      <value>retarus GmbH</value>
  </property>
  <property>
      <key>FromTelNum</key>
      <value>123456789</value>
  </property>
  <property>
      <key>ToName</key>
      <value>Jane Doe</value>
  </property>
  <property>
      <key>ToCompanyName</key>
      <value>ACME Corp</value>
  </property>
  <property>
      <key>ToFaxNum</key>
      <value>987654321</value>
  </property>
</faxRecipient>

3. Send a fax job request

→ Send your fax job request. Regardless of whether you use SOAP or REST, the result on the cover page of the transmitted fax should look like this, with the values from above:

Addressing different recipients individually

Now, let's modify our first example and send faxes with cover pages to multiple recipients. Since the properties are part of the recipient's object, you set the individual values for each recipient (REST) or faxRecipient (SOAP) in your fax job request.

"recipients": [
  {
        "number": "+4989123456789",
        "properties": [
            {
                "key": "FromName",
                "value": "Jon Doe"
            },
            {
                "key": "ToName",
                "value": "Jane Doe"
            }
        ]
    },
    {
        "number": "+4989987654321",
        "properties": [
            {
                "key": "FromName",
                "value": "Jon Doe"
            },
            {
                "key": "ToName",
                "value": "Frank Doe"
            }
        ]
    }
] 

Customizing a cover page with your company logo

Would you like to harmonize the cover page with the look of your company's documents? To integrate a company logo, contact your contact person at Retarus and order a customized cover page. A technical consultant or implementation engineer will design the cover page according to your specifications.

The maximum size of the image is 32 kilobytes. If the logo is larger, only the first 32 kilobytes will be displayed in the fax. We recommend that you use a simple black-and-white version of your company logo, which will also look better in the fax document.

Example of an integrated logo on a cover page

Automating processes with barcodes or QR codes

Consider the following scenario:

• You send a lot of forms for different business processes and expect the recipients to respond by fax.

• Now, you need to classify them so that the returned faxes are routed to the right department for further processing.

→ By adding barcodes or QR codes to a cover page, you can easily associate incoming faxes with existing business transactions.

How it works

If you want to use graphic codes, get in touch with your contact at Retarus and order an individual cover page. You will be guided through the next steps. Graphic codes are set within the recipient properties section with the barcodeValue term as the key and the value that is to be displayed graphically.

<property>
        <key>barcodeValue</key>
        <value>123456789</value>
</property>

Form with an integrated graphical code

Using Faxolution-for-Applications to create documents

Do you need to send faxes but your application cannot create documents on its own?

With Faxolution-for-Applications, you can turn information into documents using a multi-page cover page. This is a cover page that contains so much content in one or more variables that additional pages are created during job processing. In fact, the cover page would be the fax document itself and no additional documents would be needed.

To use this feature, inform Retarus that you want to include content exceeding one page. A technical consultant or implementation engineer will design the page for you according to your requirements.

<tr><td colspan="2">${SubjectText1!}</td></tr>
<tr><td colspan="2"><hr></td></tr>
<tr><td colspan="2">${SubjectText2!}</td></tr>
<tr><td colspan="2"><hr></td></tr>
<tr><td colspan="2">${SubjectText3!}</td></tr>

Since the document (SOAP) or documents (REST) element in the request is optional, you can omit it and just fill in the destination number and the key/value pairs for the properties. The resulting fax will contain only the cover page.

Cover page example

Note that the two pages are shown side by side for layout purposes only. The fax document itself uses individual pages to display the content.

FAQ

What happens if I do not fill every variable in my request?

The visible result on the fax page depends on the layout of the page, but in general, unfilled variables are left blank. For example, if we do not include the company names in the example above, we will get this result:

How do I choose one of several cover pages?

You can either log in to the EAS Portal and select a cover page from the cover page template drop-down menu. Or you can reference a cover page in your fax job request.

In REST, the coverpageTemplate element is part of the renderingOptions element, while in SOAP, the coverpageTemplateName element is part of the options. For more details, refer to the respective guidelines.

If cover page settings exist both in the EAS portal and in the fax job request, the latter is used.