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:
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,
- 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,
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.
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
Automated login is preferred. To automate logins, you can modify the login form to pull the authentication data from the environment variables
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.
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:
You may need to specify a location in which to store temporary files for the user. Generally, you should place these files in
Some webmail applications rely on operating system level utilities, such as
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.
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,
The database name and credentials will need to be automated. This will change to suit the application in question.
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.
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 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.
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:
- Extract the pristine sources into
- Apply the patch.
- Create the webmail registration file.
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.
This is entirely dependent on the configuration of the webmail application. To find this answer, examine your PHP webmail application's configuration.