Documentation and help portal

regimail Desktop User Manual

Description

The regimail desktop tool is created to turn PDF documents into regimail documents. To achieve this functionality, the application is given a source folder in which it will look for PDF documents. It will search these for valid e-mail addresses and potentially other text. It will then list the results and allow the user to create regimail documents and mail them.

Before processing the PDF documents the user is allowed to choose or add e-mail addresses as needed. Configuration allows for choosing the first address, showing an e-mail picker or marking a document invalid, in case more than one e-mail address was found.

If there is no e-mail address found in a PDF, the user is able to automatically send them to a printer or mark them as invalid.

After the PDF documents have been processed, they will be moved to a 'completed' folder specified during configuration.

The regimail documents will be moved into a 'completed' folder that is also specified during configuration. regimail desktop also allows the user to create custom expressions in order to extract additional information that can then be used in the e-mail body or subject. The expressions also allow filtering documents in which the given expression was not found. There are also means of excluding e-mail addresses from being detected, to prevent ones own address from showing up in the list.

regify desktop principle

Installation and Setup Assistant

In order to install, and for processing the PDF files, your regimail desktop tool needs the following information:

  1. A valid regify account to send on behalf of.

  2. An identity file to provide the sender’s authentication level to the recipient.

  3. A valid SMTP e-mail account to send the generated regimail documents via e-mail.

To install regimail desktop, simply run the regimail desktop_setup.exe executable. The first time regimail desktop is run, the setup assistant will guide you through a successful first configuration. Before starting the assistant, it is best to have your regify account data, identity file unlock code and SMTP e-mail credentials ready.

The general configuration dialogue later allows you to change all these settings, and provides additional ones. To open up the configuration dialogue later, click Program  Configuration in the menu bar of regimail desktop.

SMTP Settings

The first dialogue of the setup assistant will open up the generic tests followed by the SMTP settings. regimail desktop sends documents via e-mail. For this, it needs credentials for an SMTP e-mail account. Please fill in all needed information for sending e-mails from regimail desktop. In order to complete this dialogue, you need to verify the settings by clicking Send test e-mail button. Otherwise, the assistant will not let you continue.

wiz 5 smtp

If you do not know these credentials, please contact your system- or e-mail administrator to find out. Or maybe ask them to fill in the needed values for you.

regify Account

The first dialogue of the setup assistant will open up a dialogue like this:

wiz 1 pls

Please enter the e-mail address and password of the regify account you like to use for sending the regimail documents.

Identity File

It is mandatory to use an authenticated regify account for sending regimails. Authentication means, that the regify provider checked your identity. This allows the recipients to verify the sender of the documents and to trust that information.

wiz 2 identity

In order to get your identity file, you need to be authenticated. If that already happened, you have received an unlock-code by SMS or letter from your regify provider. Please enter the unlock-code to the text field and click on Get identity file to install it on your device.

If you are not already authenticated, you might click the Start an authentication now…​ button to log you into your regify provider portal and navigate to the authentication options.

Please note that in some circumstances, the authentication options may not be available for you. In this case, please contact your regify provider to check authentication for you.

Document Examination

The regimail desktop examines all your PDF documents to find e-mail addresses. These e-mail addresses are the recipients to whom the regimails will be sent. In many cases, your document header or footer contains organizational e-mail addresses like info@company.com or contact@company.org. As regimail desktop should not take these addresses as potential receivers, you can define e-mail addresses and e-mail domains to filter.

wiz 3 filter

Please enter e-mail addresses from your documents header and footer in this field (one by line). If you like to filter a whole domain like @company.org, simple enter this in a line.

Recipient

In some cases, regimail desktop may find multiple possible recipients or even no valid e-mail address in the documents. This page allows you to chose the correct behaviour for your needs.

wiz 4 recipient

Initially, select the behaviour for multiple (2 or more) e-mail addresses found. This is how the options work:

  1. Show Picker: Allows the user to open a dialogue to choose the desired recipients from the ones found. This needs interaction in order to process the document.

  2. Choose First: Tells regimail desktop to simply chose the first e-mail address it found. The system will not need any user interaction.

  3. Use all: The document will be sent multiple times to all e-mail addresses found. The system will not need any user interaction.

  4. Set invalid: The document will neither be sent nor printed in any way. There is no option for the user to fix the problem. This is helpful to identify invalid documents.

By default, documents with no e-mail address found are not processed (invalid). In case you plan to print all documents with no e-mail address, please chose the printer from the second drop-down list. This means, regimail desktop will send documents with no valid e-mail address directly to the chosen printer.

The Main Window

The main regimail desktop window looks like this. Here’s a brief description of each column.

regimail desktop

You may right-click on documents to get more options. You can also use Ctrl+A to select all documents and press the Del key to delete files in the input folder.

Column Description

State

Indicates the current state of a given document.

  • Green: Document is ready to be processed

  • Yellow: If “Show Picker” was chosen under “document examination” – “multiple address behaviour” and the document has more than one e-mail address.

  • Red: Either no e-mail address was found, or one of the required custom expressions was not found.

  • Printer: Document will be sent to specified printer, so it can be mailed by hand.

Double click onto the image (if not green) to find out the reason.

Filename

Double clicking on the file name will open the given PDF for viewing.

Recipient

The address of the designated recipient. You can double click into this field in order to open a small dialogue which allows you to chose found e-mail addresses or optionally add another one.

More fields

More fields are displayed if you use custom regular expressions. It is left blank when nothing is found. If the expression was required the empty field is shaded red. This column appears only if you have created such a REGEX. Double click in order to show the full content of the field.

Configuration

regify Account

If you have changed the password of your regify account, you can enter the new regify password in this dialogue.

The Check Settings button allows you to verify all your regify and connection settings (except e-mail) to make sure everything is setup correctly.

If you switched regify providers, you need to reset the regify account settings. Click on Reset Account Settings to do so.

Click on Proxy Settings to enter or edit your proxy settings.

If you need a new authentication, you can login and start the authentication in portal by clicking the Start an authentication now button.

If you re-authenticated, please click on Get Identity File button to request the new identity file. You will need the new unlock-code to install th new identity file.

Click on Display Identity File to show your currently installed identity file used for regimail desktop.

The Reminder duration days defaults to 5 days. This means, after 5 days the message is considered "not collected". Because of this, it will be flagged yellow in your "sent messages" list in your regify provider portal. Three days later the message will be flagged red. Please do not change this value if you are not asked to do so.

Program

Language allows you to select the language used for the user interface. You need to restart regimail desktop to get the new language.

You can also protect your configuration here. Select Protect program with password to protect the following dialogues and settings from unwanted changes:

  • Main configuration dialog

  • PDF processing options

  • PDF split settings (split can still get used, but parameters are fixed)

  • Profile manager 'delete' function

Enter the password twice to make sure you have no typo.

Directories

On this tab, the 'incoming' (Original PDF files are here), 'converted' (Place regimail documents here) 'completed' (Place completed original files here) and 'unfinished' (Place unfinished original files here) folders are chosen.

The 'incoming' folder is read by regimail desktop. All PDF documents in this directory are displayed in the regimail desktop main window.

Pressing Register and Send in the main window accomplishes the following things:

  1. The generated regimail documents are placed into the 'converted' folder.

  2. The original PDF documents are moved into the 'completed' folder.

  3. Documents that were not ready are placed in the 'unfinished' folder when regimail desktop is run in batch mode.

Processed files are placed under their corresponding folder in the given year\month structures. Meaning documents processed on April 15th 2013 will be in 2013\04\. If a document was sent to the print channel it will be in completed\2013\04\printed\.

The File Renaming Pattern allows customisation of the resulting regimail file names.

The Create Demo Data button copies some sample files into your incoming folder for testing and adds a regular expression as an example.

Documents

In this section you control how the content of a document influences document processing.

Filter E-mail Address

If you like to filter e-mail addresses from the document (like the ones of your own company), you can enter one or more addresses to the Filter e-mail Addresses field. You may divide multiple e-mail addresses using the semicolons, commas or simply place them one per line. You can enter full e-mail addresses or only domains (beginning with the @). In case of a domain, all addresses of this domain will be ignored. The start up wizard usually places your main regify address here.

Multiple Address Behaviour

Sometimes documents may contain more than one e-mail address. Here you can choose how to handle this case. The options are:

  1. Show Picker: Allows the user to open a dialogue to choose the desired recipients from the ones found. This needs interaction in order to process the document.

  2. Choose First: Tells regimail desktop to simply chose the first e-mail address it found. The system will not need any user interaction.

  3. Use all: The document will be sent multiple times to all e-mail addresses found. The system will not need any user interaction.

  4. Set invalid: The document will neither be sent nor printed in any way. There is no option for the user to fix the problem. This is helpful to identify invalid documents.

No matter what you have chosen, you can always double click the e-mail address field in order to select from found addresses and to also add one additional manual e-mail address.

Missing Address Behaviour

When an invoice contains no e-mail address, it is possible to send it to a printer for standard physical delivery. To do so simply change Set Invalid to label Print using your printer here. These documents will be printed and stored under <completed folder>\<year>\<month>\printed\.

Custom Expressions

Custom expressions are an optional feature that allow you to filter content out of a document. You can use the results as place holders, [REGEX1] through [REGEX5] in your message options. For example, the following regular expression searches for any number like 00-000000:

\d\d-\d{6}

It may be placed into your e-mail subject, body, meta tags or destination file names as needed. The found results (comma separated) will then be displayed in the main window under the name you gave to that custom expression.

If the Output field stays empty, it will use the whole result of the regular expression (also known as group 0). This field allows you to use groups and to combine the result as you like (groups are defined by covering someting in parenthesis). The groups are numbered from left to right and used with backslash like \1 for using group one.

This is very useful if you search for values behind other values like in this example:

RegEx: Year\s+(20\d\d)

Output: \1

This example will only find a year like 2021 if it follows the text "Year". The whole find is "Year 2021", but since the Output chooses group 1 (\1), it will only use the numeric year "2021". Using \0 or empty as Output would have returned "Year 2021".

Another example:

RegEx: (20\d\d)-(\d+)-(\d+)

Output: Datum: \3.\2.\1

If there is a date of the form "2021-05-02", the three values will be in groups and the chosen Output will make it appear as "Datum: 02.05.2021".

By checking the Required check box, you can invalidate a document preventing it from accidentally being processed without a valid result (eg invoice number). Regular expressions are a widely used standard to process text. You can find more information on this page: http://www.regular-expressions.info/

You can find some common RegEx examples in the Addendum of this document.

If the same value is found multiple times, it is only returned once. Any leading or trailing spaces are removed from the result.

Messages

Your regimail e-mail messages need a subject and a message body. This tab allows you to define these.

You may use place holders to individualize your subject or message body. You can find the available place holders by pressing the ? buttons. Alternatively, you may enter them by right clicking the place in the message body where you want to enter them. Note: Right click does not work in the subject.

Your message body content can either be simple text or HTML. We provide a default HTML template by default. There you can use HTML and CSS styles to format your document (you must use UTF-8 encoding in your HTML content-type header line).

To preview the current message, please press the P button on the bottom right.

To revert to the default regify template, you can right click the message body editor and select Reset to default template (nn) - where 'nn' is the current language. This way you will get the default for the currently used language. You have to switch the GUI language (tab regify Account) and restart regimail desktop in order to get another language.

Sending Options

regimail desktop sends the documents it creates to their corresponding recipients. For this, an outgoing SMTP server needs to be provided. If the SMTP Server field is left blank, the remaining fields are ignored and the Register and Send button in the main window is disabled. Only this and the Sender Account fields are required. The SMTP Server field takes a host name and an optional port number if the port is different from 25. Please note that IP addresses are not supported.

Check Use secure connection (TLS) to attempt using a secure connection. Please note that SSL alone is not supported (but also not very common).

Whether SMTP Username and SMTP Password are required depends on the policy of the chosen SMTP server’s administrator. All other fields are optional.

The sender name and sender e-mail will get displayed in the regify message in the form of sender name sender e-mail. The same concept applies to the two reply to fields.

When changes are made to any of the top four fields, the red notice on the bottom shows up. Pressing the send test e-mail button sends a test e-mail to the sender account, verifying SMTP functionality. After successfully sending off the e-mail regimail desktop will turn the red notice off and Register and Send in the main window will be enabled.

If you like to receive a copy of every regimail message that is sent using regimail desktop, simply check the Send me a copy option.

Profile Manager

If you need to run regimail desktop with several different settings, you can use the profile manager to handle this. Profiles contain all setup and configuration options of regimail desktop including:

  • regify account and identity file

  • document path and filter settings

  • e-mail address handling options

  • custom expressions (regex)

  • subject and message templates

  • SMTP settings

  • PDF enclosure and background settings

profile manager main

Profile Handling

To select an existing profile, double-click the entry in the list or select one and click on Open.

If you need a new profile, you first select the one which is closest to the needed result followed by a click on Duplicate. This will create a new profile with all settings of the previous selected one. The new profile automatically starts in edit-mode. Now, please enter a new unique profile name and a description. You can also modify the name of the creator.

To edit the profile name and description, click the Edit button below the profile list. Please note, that the profile configuration (eg message templates etc.) are edited in the main dialogue and not in the profile manager.

To delete a profile, simply click on Delete. Please note that there is no undo functionality.

Please note that you can’t delete the profile that is currently loaded. In order to delete this profile, first load another profile and re-enter profile manager. You can then select the previous profile for deletion.

Profile Edit-Mode

In edit mode, you can enter or edit a profile name, profile description and profile creator:

profile manager edit

In case you have more than one profile, regimail desktop will start with the profile manager by default. This is to let you chose a profile first. If you mark a profile with the checkbox Load this profile as default on startup this profile as default on startup, then regimail desktop will start by loading this profile automatically and go directly to the main screen. If you previously checked that option in another profile, the new profile will become default and this option is removed from the previous one. There is always only one or no profile marked as default.

You may click on Save to save the changes or Cancel to discard previous changes.

Import and Export

With these two buttons, you can export complete profiles in order to import them on another system. Due to some security considerations, the export does not contain identity file information. Because of this, you need to enter the unlock-code for the account during import. The regify account credentials and the SMTP password are part of the export and do not need to be entered.

Please note that you can’t import the same profile multiple times. Use the duplication function to get copies of a profile.

Split function

In order to split a PDF file in your documents list, please right click the document to split. Some self explaining options will pop-up. Please chose Split this file.
Alternatively, press Ctrl+S after you selected the file to split. The split PDF file dialogue will open up:

split options

This dialogue allows you to split document using different modes:

Split Options

Split Option Description

Split every single page

The result will be a new PDF for every single page.

Split using e-mail address

This algorithm will keep all documents, with the same mail address in series, together.

Example: A PDF with with a@b.com on pages 1,2 and 3 and b@c.com on pages 4 and 5 will produce a PDF with 3 pages (a@b.com) and a PDF with two pages (b@c.com).

The e-mail address is only used if it does not fit the filters in the configuration document tab.

Split using marker

A free text can be used as split marker (for example the recipients name). In this case the page is split if this marker was found.

Split using regular expression

Instead of an e-mail address in the Split using e-mail address function, a free regular expression can be used to split the pages (for example a RegExp to match the invoice number).

If no e-mail address or marker is found

This option sets the behavior, if the property defined above is not found.

Add page to previous document

If the value is not found, the page is added to the previous document which found the marker (e.g. if the e-mail address is only placed on the first page of a multi page document).

Save page as single PDF

If the value is not found, the page is saved as individual single PDF document.

Renaming options

The split algorithm generates multiple PDF files. They can either be renamed using an e-mail address (if found) or the page number (from the original document). If you have chosen to split using Regular Expression you also can use that result to rename.

Please consider that the page number will be used in all cases if no e-mail address or Regular Expression was found.

Delete original

In most cases, the original PDF document is no longer needed after splitting. If you like to delete the original file after splitting, check the Remove original document after successful splitting option. This will delete the original file. Please note that there will neither be a copy, nor will it be in the waste basket.

Detailed explanation of the split options

For the following examples, let’s pretend that the triangle, the circle and the diamond are different e-mail addresses.

If you chose to split using e-mail address or Regular Expression, then documents with the same value will be grouped.

split info 1

If you split documents using a marker (a word or a sentence), a new document will be created every time that marker (rectangle) is found on a page:

split info 2

The option to handle pages with no e-mail address or marker has great impact on the result. Lets imagine this set of pages in a PDF file to split (where a triangle is an e-mail address and the diamond is another one):

split info 3

If you chose to add such pages to the previous document, the result will be two PDF files:

split info 4

If you chose to save as single page, the result will be three files:

split info 5

Merge Function

In order to merge multiple PDF files in your documents list, please select the files to be merged.

To select multiple files, use Ctrl or Shift keys together with left mouse-click.

When you right click the selected documents, a list of self explanatory options will pop-up. Simply chose Merge selected files. Alternatively pressing Ctrl+M brings up the same dialogue. The merge PDF file dialogue looks like this:

merge options

This dialogue allows you to merge multiple documents using different options:

Define order

This field shows the selected files to be merged. In order to change the sequence, select the entry to move and move it by using the arrow buttons on the right.

Destination filename

This will be the resulting filename of the merged documents. The dialog automatically adds the .pdf extension. If such a file already exists, it automatically adds an incrementing number and indicates this in the extension field on the right. This insures you always get a unique filename.

Remove original documents after successful merging

In most cases, the original PDF documents are no longer needed after merging. If you like to delete these original files after merging, check this option. Please note that there will neither be a copy, nor will it be in the waste basket.

PDF Processing Options

The application offers two ways to pre-process these PDF files before they get registered and sent.

To enter this dialoge, open it from the main menu Program  PDF processing options or press Ctrl+P.

In order to get good results, please try to generate the PDF documents to enclose or to use as background as small as possible. Every document is getting increased in size by this additional content.

PDF Enclosure

This function offers you a simple way to add additional pages to the PDF documents. This may be advertisement, handling instructions or any other content.

pdf enclose

Check the Enclose PDF option and select the PDF file to enclose in order to activate this feature. By default, this does not happen to PDF files that are being sent to the printer. Check the Also apply on print jobs option to also process these.

PDF Background

This function does an overlay of the files to send with the given PDF document. This is mainly used for adding the logo, header and footer information of a document if the provided PDF files do not contain such information. Sometimes this functionality is also called stitching.

pdf background

Check the Add some PDF background option and select the PDF file to stitch in order to activate this feature. By default, this does not happen to PDF files that are being sent to the printer. Check the Also apply on print jobs option to also process these.

If you need the background only added to the first page of your PDF files, check the Apply on first page only option.

Addendum

Useful Regular Expressions

You can find additional information about regular expressions on http://www.regular-expressions.info/

And here is our favorite RegEx tester:
https://regex101.com/

Find different markers:

RegEx Info
\(regify\)

search "(regify)" (please note the escaped brackets)

\d\d-\d{6}

search "dd-dddddd" where d is a digit (like "12-123456")

\d+-\d+\/20\d{2}

search "number-number/20dd" (like "71-07/2021")

Find values behind words:

RegEx Info
Year:\s+(20\d\d)

Searching for "Year:" followed by one or more spaces, followed by a 4 digit number starting with 20. The group is wrapped around 20\d\d, so it will return the year only if you choose 'Output' to be "\1".

Invoice-Nr\.:\s+([0-4]{5})-(\d{4})

Find "Invoice-Nr.: " followed by one or more spaces, followed by five digits from 0 to 4, followed by minus and four digits. Returns the first digits group as group 1 (\1) and the second 4 digits as group 2 (\2). To get the second number followed by the first one, you may set 'Output' to be "\2-\1".

Find German "Anrede":

Sehr geehrte Frau [\p{L}\d-\s]*|Sehr geehrter Herr [\p{L}\d-\s]*|Sehr geehrte Damen und Herren

Search German "Anrede" like "Sehr geehrter Herr Meier" or "Sehr geehrte Frau Kunz" or "Sehr geehrte Damen und Herren".

Command-line Options

The regimail desktop supports several command-line options:


regimail_desktop.exe [-b] [-p] [-h] [-l [-v]]

-b Batch mode.
-p Profile name to load (requires -b)
-h This output.
-l Specifies log file to log to. No logging without this.
-v Verbose mode. Increases log level to verbose. Requires -l.

Example call with activated verbose logging:

regimail_desktop.exe -v -l "c:\temp\logfile.txt"

Batch Mode

regimail desktop can be run in batch mode by an automated task scheduler. In this mode the main window is opened minimized and all progress bars are hidden. All documents are processed immediately and documents that are not ready to be processed, are placed in the 'unfinished' folder. Information generated during the run, such as processed files is logged into the batch log. The batch log may be inspected by visiting Folders – Open Batch Log. To run regimail desktop in batch mode it should be called like this:

regimail_desktop.exe -b

In case you’ve defined multiple profiles, you need to either define one as the default profile or tell regimail desktop to load a dedicated profile by name. This is done using the -p switch followed by the profile name (covered in quotes).

Optional RGF file upload

As of version 2.1 the regimail desktop INI file offers a UploadURL field, which is empty by default. By setting this to a URL, you can tell regimail desktop to upload each final RGF file to another location. The functionality is currently very limited and always submits the file content in the POST field "file". The URL can also be used to transmit additional information. It supports all the usual placeholders. Especially the [UDID] value is very useful for several scenarios, as it is a unique hexadecimal number for every PDF file (256 bits).

If you plan to use this for some functionality, please contact regify support at support@regify.com for assistance.

Optional recipient override

As of version 2.1.2 the regimail desktop INI file offers a OverrideRecipient field, which is empty by default. By setting this to a valid email address, you can tell regimail desktop to replace any found email recipient by this generic one. Independent of what is found in the PDF or not, the recipient will be this email address. It is highlighted with a different color and can only get changed manually by double clicking and manual change.

The intention of this functionality is only for very special purposes where all PDF, with email or not, should be sent to the same recipient.

If you plan to use this for some functionality, please contact regify support at support@regify.com for assistance.

Optionally prevent SMTP sending

As of version 2.1.2 the regimail desktop INI file offers a DoNotSendSMTP field, which is 0 (zero) by default. By setting this to 1, you can tell regimail desktop to not send the resulting message (RGF/PDF) to the recipients in any case.

The messages will get encrypted, optionally uploaded and processed as usual, but the message is not sent by email. Sending is skipped.

Please note that you may need a configured SMTP sending address even if this option is used. regimail desktop may not work without proper email configuration.

If you plan to use this for some functionality, please contact regify support at support@regify.com for assistance.

Terminal Server and Citrix Information

Please note the following information in order to use the regimail Desktop in Terminal-Server or Citrix environments:

  • Installation

    • Install normally on the server. If you run a cluster with multiple servers/hosts, please install on all machines!

  • Special settings for Terminal-Server and Citrix