Integrating Custom Webmail Applications

You can make your favorite third-party webmail application available to your users via the cPanel Webmail interface.

To do so, follow these steps:

Create the webmail registration file

First, you will need to create a webmail registration file.

The webmail registration file is a YAML file containing a single hash with the following required keys:

• url — The path to the webmail application in question (for example, /3rdparty/somewebmailapp/).
• displayname — The name that will be displayed in the cPanel interface (for example, Some Webmail Application).
• icon — The path to the icon to display in the cPanel interface (for example, /3rdparty/somewebmailapp/icon.png).

You can use the following Perl script to generate this file:

#!/usr/bin/perl

use lib '/usr/local/cpanel';
use Cpanel::DataStore;

my $app = {
	url => '/3rdparty/mywebmailapp/index.php',
	displayname => 'My Webmail Application',
	icon => '/3rdparty/mywebapp/icon.gif',
};

Cpanel::DataStore::store_ref('/var/cpanel/webmail/webmail_mywebmailapp.yaml', $app) || die("could not write webmail registration file");

Once this file has been put in place (at /var/cpanel/webmail/webmail_mywebmailapp.yaml), your webmail application should appear in the cPanel user's Webmail interface.

Important: The name of the file in /var/cpanel/webmail/ must start with webmail_ and end with .yaml or it will be ignored.

Place and modify the webmail application

Next, you need to put the actual webmail application in place.

The proper location for the application is /usr/local/cpanel/base/3rdparty/. Applications within this directory will be executed as the user who owns the email account. Typically, you will need to make three modifications to a webmail application for it to integrate seamlessly into cPanel:

• Automate logins
• Edit the configuration file
• Configure databases

Automate logins

Automated login is preferred. You can automate login by modifying the login form to pull the authentication data from the environment variables REMOTE_USER and REMOTE_PASSWORD, then place the data into hidden form fields within the login page.

Most webmail applications use a templating system for displaying this data. If your webmail application uses a templating system, you'll need to add an additional template key.

Edit the configuration file

The configuration file or configuration file processor will usually need to be edited for a few key settings. As this will change drastically from application to application, here are some settings to be on the lookout for:

User files

You may need to specify a location for storing temporary files for the user. You should usually place these files in $homedir/tmp/$appname directory.

• Note: In the example above you will need to replace $homedir with your home directory and $appname with a directory of the same name as the application.

System application paths

Some webmail applications rely on operating system level utilities, such as aspell or gpg, to provide certain features. Most often, a webmail application will automatically detect these utilities. Others may require you to provide the location these utilities in a configuration file. This will vary according to the webmail application.

Mail servers

Webmail applications may specify which IMAP/POP3/SMTP server they use in the configuration file. Ensure that this is set to the correct server (usually, localhost).

Database

The database name and credentials will need to be automated. This will change to suit the application in question.

Configure databases

If your webmail application uses a database, it will need to be handled in a specific way.

The reason for this is that webmail applications generally need to have their databases separated, to avoid database password sharing between cPanel accounts.

• If the webmail application offers the ability to use SQLite, we recommend using this and storing the database within the user's home directory.
• If there is no SQLite support, you will have to create a MySQL user and database for each user in question, and store its data locally.
  • You can use the postwwwacct hook for automating this action after account creation.
  • Your installation script will also need to go through all cPanel users on a system and set up the MySQL user and database for each.

Package the application

Once your application has been successfully integrated, you will need to package it. There are numerous ways of achieving this; however, for installation, we recommend distributing a tarball containing:

• pristine sources,
• a patch file,
• an installation script, and
• an uninstall script.

Pristine sources and patch

Pristine sources and a patch are often required by a webmail application's license. This will also allow users to see how your webmail integration was achieved, and what changes have been made to the source base.

Installation and uninstallation scripts

The purpose of providing installation and uninstallation scripts is to make the process of installing the new application as simple as possible. The installation script should:

1. Extract the pristine sources into /usr/local/cpanel/base/3rdparty
2. Apply the patch.
3. Create the webmail registration file.

Frequently Asked Questions

Are databases used by custom webmail applications included in cPanel backups?

This will depend on the configuration of your webmail application. If databases are stored in the home directory, they will be included in the backup.

How are session files handled in PHP applications? Will they go into /tmp or somewhere else?

This is entirely dependent on the configuration of the webmail application. To find this answer, examine your PHP webmail application's configuration.