Skip to end of metadata
Go to start of metadata

For WHM version 11.28 and later


You can make your favorite third-party webmail application available to your users through 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 that contains 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:


After 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.


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. To automate logins, you can modify 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 template system in order to display this data. If your webmail application uses a template system, you will 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 in which to store temporary files for the user. Generally, you should place these files in $homedir/tmp/$appname directory.


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 based on the webmail application.

Mail servers

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


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 that you use this and store 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 to automate 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

After your application has been successfully integrated, you will need to package it. There are numerous ways in which to achieve this. For installation, we recommend that you distribute a tarball that contains the following:

  • 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

You should provide installation and uninstallation scripts in order to make the installation process for 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.

Adaptavist ThemeBuilder EngineAtlassian Confluence