The inability to access your e-mail while you are away, was until now, one of the major problems. Configuring any conventional mail package to access your mailbox is annoying and sometimes impossible if your server is protected by firewalls, and why make your network unsecured disabling such protection in order to access your mail remotely?. Free Mail services such as Hotmail, force you to have an additional e-mail address and save your confidential mail on an untrusted server, something not very useful for most people.

That is why VisualMail was created, a fully featured web based mail software designed to enable any user to access his/her POP3/IMAP mailbox using a standard browser or web terminal.

With VisualMail there is no need to worry about configurations, firewalls, privacy or where you are, because it was designed with the security in mind, it runs on your server, you access it via web and you can customize it to fit your needs.

VisualMail supports unlimited users and works with UNIX mail servers as well as Microsoft Exchange and Lotus Notes Domino mail servers.

VisualMail is available in two versions, "Standard version" and "Enterprise version". It's important that you understand the functional differences between the two versions in order to choose the more suitable one for your needs.

The standard version is a gateway to any POP3/IMAP4 mailbox, that fetches messages from a mail server and displays them in HTML format.

This version is more suitable for ISPs or companies where the users want to use VisualMail as a complement to their conventional software, for example, an user that is travelling and wants to check his email via web and then, when he is back home, downloads his mails using his conventional e-mail package.

The enterprise version is a fully featured mail program, that fetches messages from a mail server and stores them into an internal database, just like as Hotmail does. This version is more suitable for free mail providers (like Hotmail) or companies where the users want to use VisualMail as their conventional e-mail software, for example, an user that stores his mails on the VisualMail server and has access to them using a browser.

VisualMail is written in C++ and its modular architecture makes it a scalable and multiplatform solution easily adaptable to new technologies.

All the data is handled by VisualMail as an object. All the objects are referenced with an Object identifier (also called Session identifier). Before processing an object, VisualMail checks the Object-ID against the Local Security Authority (called CSession) that validates if the user is logged in, if the session has not expired and if the user is allowed to gain access to the object.

The object accessed could be an attachment, an email address, a message or a particular action to perform.

All the internal data flow between the different modules is managed by the VisualMail Engine, these modules handle specific functions like interfacing with users or servers, and performing particular

actions. Let's take the example of an user downloading an attachment:

All the objects are requested and validated using the same method, but they are handled using a different handler (CFolder in this example).

The most important objects are:

CGIClass: Handles the interaction with the user, it receives the data posted by the browser and processes it.

CSmtp: Handles the communication with the SMTP servers.

CPop3: Handles the communication with the POP3 servers.

CImap: Handles the communication with the IMAP servers.

CSocket: Handles the TCP connections used by the CSmtp, CPop3 and CImap modules.

CMailSrv: Interfaces the CPop3 and CImap modules and processes RFC-822 headers.

CMime: Handles MIME, UUENCODE and ISO-8859 encoding and decoding.

CConfig: Handles the system and user configuration.

CSession: Handles Object-ID requests and validation.

CSyslog: Handles logging.

CFolder: Handles database object access.

The enterprise.conf file contains all the configuration parameters of VisualMail and is located in the /etc directory. (Note: to comment a line append a # at the beginning of the line)

VisualMail sends all the mails using any standard SMTP server like sendmail, that can be installed in the same machine that runs VisualMail or on a remote server.

To modify the SMTP server address, change the SMTPAddress parameter to match your SMTP server address. The SMTP address can be either an IP address or a FQDN (Full Qualified Domain Name).

Example:

SMTPAddress = smtp.mintersoft.com

If your SMTP server is running on a port different to 25, you can change it by modifying the SMTPPort parameter.

Example:

SMTPPort = 25

Both VisualMail standard and enterprise retrieve the mails from a POP3 or IMAP2/4 server. VisualMail calls this server the Main Mail Server, because is the default server that is used to download the user’s mails and must be always available. Like the SMTP server, the Main Mail Server (MMS) can be installed in the same machine that runs VisualMail or on a remote server.

To modify the Main Mail Server address, change the MMSAddress parameter to match your POP3 or IMAP server address. The Main Mail Server can be either an IP address or a FQDN (Full Qualified Domain Name).

Example:

MMSAddress = mail.mintersoft.com

Also, you must modify the server type to tell VisualMail which protocol to use when talking to the Main Mail Server. The server type can be either IMAP or POP3.

Example:

MMSType = Imap

for and IMAP server or,

MMSType = Pop3

for a POP server.

Besides changing the MMS server type, you must specify VisualMail which port to connect to, that is usually 110 for POP3 servers and 143 for IMAP4 servers, to modify this you must change the MMSPort parameter.

Example:

MMSPort = 110

for POP3 servers or,

MMSPort = 143

for IMAP4 servers.

If you don’t want VisualMail to remove the mails from the MMS once downloaded, you can set the MMSLeaveOnSrv parameter to Yes.

Example:

MMSLeaveOnSrv = Yes

VisualMail supports two basic authentication methods to validate users, a file with passwd format or the Main Mail Server (this is called Cross Server validation).

The file validation method can be used to read the users and passwords from the /etc/passwd, the /etc/shadow file or from a separate file with the format:

user:crypted_password[:more data]

The Cross Server validation method authenticates the users against the Main Mail Server using the POP3 or IMAP protocol. This method is useful when the user database is stored on a Exchange Server® , a Lotus Notes® server or another.

Examples:

To enable file validation from the shadow file:

Validation = /etc/shadow

To validate from the passwd file:

Validation = /etc/passwd

To validate from the MMS server:

Validation = Cross Server

You can append a footer with a customized message or an advertisement to every outgoing message. To configure this you must create a text file with your message, and specify its path in the OutgoingAd parameter. To disable Outgoing advertisement, append a # at the beginning of the line.

Example:

OutgoingAd = /usr/local/visualmail/conf/advertise.txt

VisualMail can be configured to automatic disconnect an user before some amount of time of inactivity. This feature is very useful for security purposes, if an user leaves a terminal connected VisualMail automatically will disconnect the session after a configurable amount of time. To disable automatic logout specify 0 in the AutoLogout parameter, or specify the number of minutes of inactivity to enable automatic logout.

Example:

AutoLogout = 30

You can specify the maximum file size allowed to upload by an user from the compose message page, this is done by modifying the AttachLimit parameter. To disable the attach limit, specify 0 in the AttachLimit parameter, or specify the number of kilobytes allowed to upload.

Example:

By default an user is allowed to use unlimited disk space, to change this you can modify the QuotaDisk parameter and specify how many megabytes a user can use or 0 to disable this feature.

Example:

QuotaDisk = 10

To troubleshoot some problem or to view the activity of the users, you can configure the logging. The logging is performed by using the syslog daemon, using the LOG_LOCAL0 facility. By default the logging is disabled (level 0). To enable logging you must specify a log level from 1 to 4 in the LogLevel parameter. The level 1 logs logins and logouts, the level 2 logs the same as level 1 and several errors, the level 3 logs the same as level 2 and all the errors and finally the level 4 logs everything.

Example:

LogLevel = 4

The default domain name is used to send the HELO command to the SMTP server and to automatically generate the user’s e-mail address. Specify your mail domain name in the DefDomain parameter.

Example:

DefDomain = mintersoft.com

The list of supported domains by the system is read from a text file. This file is specified in the DomainList parameter.

You must specify to VisualMail where the visualmail executable file is located from the web. This parameter is needed to create the HTML files POST info. This value is specified in the URLVisualMail parameter.

Example:

URLVisualMail = /cgi-bin/visualmail

The template directory is where all the HTX files are stored. The HTX files are used to generate the HTML pages.

Example:

TemplateDir = /usr/local/visualmail/htx

The DBUtil is the command used to clean the users databases. You have to specify it in the enterprise.conf file in order to enable the empty trash function.

The home directory is where all the user data files are stored.

Example:

HomeDir = /usr/local/visualmail/data

The temporary directory is where all the temporary data is stored.

Example:

HomeDir = /tmp

The language file contains all the messages displayed by VisualMail listed one per line, this file is language dependent, when you install a language extension this file is replaced. The path to this file is specified in the LangFile parameter.

Example:

LangFile = /usr/local/visualmail/conf/language.cfg

By modifying this file, you can customize date formatting options, error messages and some default texts.

The language file is common to both versions of VisualMail. (Note: Don't delete or add any line(s) of the language file, or you will receive error messages).

The date formatting macros are the same used by strftime():

If you want to deny access to a specific user to VisualMail, you can do this by adding the username to the banned users file. The path to this file is specified in the BannedUsers parameter.

Example:

BannedUsers = /usr/local/visualmail/conf/banned.cfg

The banned users in this file are listed one per line.

The enterprise version of VisualMail supports a customizable Sign Up procedure that allows your users to automatically create their accounts.

SignUpAddUser = /usr/sbin/useradd -c "{firstname} {lastname}" -s /bin/false -d /dev/null -p {cpass} {user}

SignUpChPass = /usr/local/visualmail/bin/chpass {user} {pass} /etc/shadow

SignUpUsrChk = /usr/local/visualmail/bin/check_user.sh {user}

SignUpWelcome = /usr/local/visualmail/conf/welcome.txt

SignUpSendWelcome = Yes

The message sender name (and e-mail) is configurable from the language file, lines 99 and 100.

VisualMail creates all the HTML files using a language called HTX. The HTXs files contain a mini-language that is used to place dynamic text and objects in the HTML that is displayed to the end-user.

The structure of the VisualMail HTXs is similar to the HTXs used by Microsoft Internet Information Server®.

This language is very simple, it only has 'if' and 'while' control commands and tags that are used to print dynamic information and HTML objects.

Let's view an example of the HTX language:

1:<H1>Welcome <% UserFullName %> to VisualMail!</H1><BR>

2:<% if HaveMail %>

3:<B><U>You have mail!</U></B><BR>

4:<% while GetMail %>

5:<HR>

6: Message from: <% MsgFrom %><BR>

7: Subject: <% MsgSubject %><BR>

8: Size: <% MsgSize %><BR>

9: Date: <% MsgSize %><BR>

10: <% while end %>

11: <% else %>

12: <B><U>You don't have mail.</U></B><BR>

13: <% end if %>

Line 1 prints the Full Name of the current logged in user.

Line 2 checks if the user has mail on his mailbox, and if this condition is true the HTX is parsed until the <% else %> directive is found, otherwise the HTX is parsed from the <% else %> to the <% end if %> directive.

Line 4 is parsed from the <% while %> to the <% end while %> as many times as messages in the mailbox.

Lines 6 to 9 print information about each message.

Each HTX page has different commands, but there are some global commands that can be referenced from any page.

The following table describes the function of each HTX file:

As you can see this is a very simple language but very helpful to customize VisualMail and change default behaviors.

The HTX files are stored in the Template directory under the template number that the user selects. For instance, if the user selects the template number two, all the HTX files will be retrieved from:

/template_dir/2

If you want to write your own HTX files, use as a guide the examples that come with VisualMail and read the Appendix A ( HTX command reference).

Problem: Performing actions that take too much time (like downloading a very big mailbox), the user always receives after a constant amount of time a "the server returned an invalid or unrecognized" error message.

Cause: Web server configuration issue.

Solution: Check the ScriptTimeout parameter in your web server's config file, by default most web server software kills the cgi application if no response is received for more than x time.

Problem: VisualMail returns a "Incomplete config file" error message.

Cause: Missing parameter in enterprise.conf

Solution: Check if the VisualMail configuration file enterprise.conf is located in the /etc directory and contains all the required parameters.

Problem: VisualMail returns a "Error reading language file" message.

Cause: VisualMail can’t access the language file.

Solution: Check if the language file specified in the enterprise.conf file is present and can be read from VisualMail.

Problem: VisualMail returns a "Error processing <file>.htx file" message.

Cause: <file>.htx can’t be read by VisualMail.

Solution: Check if the HTX directory specified in the enterprise.conf file is present and can be read from VisualMail. Also check is the <file>.htx file is present and can be read from VisualMail.

Problem: VisualMail returns a "Error parsing HTX file" message.

Cause: The HTX file selected can’t be accessed from VisualMail or contains incorrect HTX commands.

Solution: Check if the HTX path specified in the enterprise.conf file is present and can be accessed from VisualMail. Also check if the HTX file accessed contains any incorrect HTX command.

Problem: The images appear as broken links.

Cause: The /images directory can’t be accessed from the web browser.

Solution: Check if the /images directory is copied correctly in your web server html root directory.

Problem: The messages deleted are not cleaned at nights.

Cause: The dbutil program is not installed correctly in the cron file.

Solution: Read the installation procedure described in chapter 2.

Prints the username of the current logged in user.

Prints the Full Name of the current logged in user.

Prints the Company name of the current logged in user.

Prints the e-mail address of the current logged in user.

Default domain name specified in enterprise.conf

Prints the licensed to name specified in enterprise.conf. If the key is demo key, the remaining days are also displayed.

Automatic Logout time specified in enterprise.conf

Starts a HTML form.

Ends a HTML form.

Prints all the hidden vars needed by VisualMail.

Prints the Object-ID of the compose screen.

Prints the Object-ID of the Inbox screen.

Prints the Object-ID of the Address Book screen.

Prints the Object-ID of the configuration screen.

Prints the Object-ID of the Folder screen.

Prints the Object-ID of the Logout screen.

Prints the Object-ID of the Accept command.

If the user is accessing VisualMail without frames, the HTX is parsed until an <% else %> or an <% end if %> is found.

Prints the error message.

Prints the Login text box, with x chars of length and y characters of max length.

Prints the Password text box, with x chars of length and y characters of max length.

Prints the select frames option check.

Prints the select no frames option check.

Prints the Object-ID of the Option Bar screen.

Prints the Object-ID of the Inbox screen without frames support.

If the user has mail, the HTX is parsed until an <% else %> or an <% endif %> is found.

If a message has an attach, the HTX is parsed until an <% else %> or an <% endif %> is found.

If a message is urgent, the HTX is parsed until an <% else %> or an <% endif %> is found.

If the user is located on the Deleted Items folder, the HTX is parsed until an <% else %> or an <% endif %> is found.

The HTX is parsed until the <% while end %> command is found while the user has mails.

Prints the Object-ID of the Sort by Name command.

Prints the Object-ID of the Sort by Subject command.

Prints the Object-ID of the Sort by Size command.

Prints the Object-ID of the Sort by Date command.

Prints the CheckBox used to select a message.

Prints the Object-ID of the Check Mail command.

Prints the sender name of the message.

Prints the Subject of the message.

Prints the message’s Size.

Prints the message’s sent date.

Prints the destination folders list with x lines of size.

Prints the current page number.

Prints the max page number.

Prints the folders list, with x lines of size.

Prints the current folder name.

Prints the Object-ID of the Empty Trash command.

Prints the Object-ID of the Message Reply Command.

Prints the Object-ID of the Message Reply All Command.

Prints the Object-ID of the Message Forward Command.

Prints the Object-ID of the Message Delete Command.

Prints the Object-ID of the Add to Address Book command.

Prints the sender of the message.

Prints the recipients of the message.

Prints the carbon copy recipients of the message.

Prints the subject of the message.

Prints the sent date of the message.

Prints the body of the message.

If a message has attachments, the HTX is parsed until an <% else %> or an

<% endif %> is found.

The HTX is parsed until the <% while end %> command is found while the message has attachments.

Prints the Object-ID of the attachment.

Prints the Object-ID of the Filters Configuration screen.

Prints the Object-ID of the Signature Configuration screen.

Prints the Object-ID of the Personal Configuration screen.

Prints the Object-ID of the Advanced Configuration screen.

Prints the filter number.

Prints the filter status check box.

Prints the list of "where to find the string" with x lines of size.

Prints the list of conditions to match with x lines of size.

Prints the match string text box with x chars of size and a max length of y chars.

Prints the list of folders with x lines of size.

The HTX is parsed until the <% while end %> command is found while the message has filters to show.

Prints the Full Name text box with x chars of length and y chars of max length.

Prints the E-Mail text box with x chars of length and y chars of max length.

Prints the Company Name text box with x chars of length and y chars of max length.

Prints the Page Size text box with x chars of length and y chars of max length.

Prints a signature text area with x rows and y columns.

Prints the server status check box.

Prints the server number.

Prints the login name text box with x chars of length and y chars of maxlength.

Prints the login pass text box with x chars of length and y chars of maxlength.

Prints the server text box with x chars of length and y chars of maxlength.

Prints the port text box with x chars of length and y chars of maxlength.

Prints the POP3 server option box.

Prints the IMAP server option box.

Prints the Leave Mail on Server check box.

The HTX is parsed until the <% while end %> command is found while the message has servers to show.

Prints the Object-ID of the Cancel command.

Prints the list of addresses with x lines of size.

Prints the full name text box with x chars of length and y chars of maxlength.

Prints the E-Mail box with x chars of length and y chars of length.

If the user is in modify mode, the HTX is parsed until an <% else %> or an <% endif %> is found.

Prints the Object-ID of the Cancel command.

Prints the list of folders with x lines of size.

Prints the folder text box with x chars of length and y chars of maxlength.

If the user is in modify mode, the HTX is parsed until an <% else %> or an <% endif %> is found.

Prints the Message To text box with x chars of length and y chars of maxlength.

Prints the Message Cc text box with x chars of length and y chars of maxlength.

Prints the Message Bcc text box with x chars of length and y chars of maxlength.

Prints the Message Subject text box with x chars of length and y chars of maxlength.

Prints the Attachments text box with x chars of length and y chars of maxlength.

Prints the priority levels list with x lines of size.

Prints the Address List with x lines of size.

Prints the Message Body text area with x rows and y columns.

Prints the Attach text box with x chars of length.

Prints the Add Signature check box. If x is equal to ‘1’, the check box is selected by default, otherwise the check box remains unselected.

Prints the Add to sent items check box. If x is equal to ‘1’, the check box is selected by default, otherwise the check box remains unselected.

Prints the Old Password text box with x chars of length and y chars of maxlength.

Prints the New Password text box with x chars of length and y chars of maxlength.

Prints the New Password verification text box with x chars of length and y chars of maxlength.

Prints the Answer to Secret Question text box with x chars of length and y chars of maxlength.

Prints the Secret Question text area with x rows and y columns.

Prints the New user’s account name text box with x chars of length and y chars of maxlength.

Prints the New Password text box with x chars of length and y chars of maxlength.

Prints the New Password verification text box with x chars of length and y chars of maxlength.

Prints the Answer to Secret Question text box with x chars of length and y chars of maxlength.

Prints the Secret Question text area with x rows and y columns.

Prints the list of available domains combo box with x chars of size.

Prints the error message.

Prints the New user’s account name.

Prints the login name text box with x chars of length and y chars of maxlength.

Prints the New Password text box with x chars of length and y chars of maxlength.

Prints the New Password verification text box with x chars of length and y chars of maxlength.

Prints the Answer to Secret Question text box with x chars of length and y chars of maxlength.

Prints the Secret Question text.

Prints the User’s account name.