For WHM version 11.28 and later
This document explain how to integrate custom webmail applications into your cPanel Webmail interface (Home >> Mail >> Webmail).
For a list of our Webmail applications, visit our Application Catalog.
Step 1: Create the webmail registration file
First, 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 (for example,
displayname— The name that the cPanel interface will display (for example,
icon— The path to the icon that the cPanel interface will display (for example,
Use the following Perl script, only as an example, to generate the webmail registration file:
Edit the Perl script to fit your needs.
After the system places the file in the
/var/cpanel/webmail/webmail_mywebmailapp.yaml file, your webmail application will appear in the cPanel user's Webmail interface.
/var/cpanel/webmail/directory must begin with
webmail_and end with
.yamlor the system will ignore it.
Step 2: Place and modify the webmail application
Next, place the actual webmail application in the
/usr/local/cpanel/base/3rdparty/ directory. The system will execute applications within this directory as the user who owns the email account. You must make the following modifications to a webmail application for it to integrate seamlessly into cPanel:
- Automate logins
- Edit the configuration file
- Configure databases
To automate logins, modify the login form to pull the authentication data from the
REMOTE_PASSWORD environment variables. 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 must add a template key.
Edit the configuration file
You must edit the following key settings in the configuration file or configuration file processor.
These settings will change drastically from application to application.
You must specify a location in which to store temporary files for the user, such as the
In this example:
System application paths
Some webmail applications rely on operating system level utilities, such as
Webmail applications may specify which IMAP, POP3, or SMTP server that they use in the configuration file. Make sure that this is set to the correct server (usually the
You must automate the database name and credentials. This will change based on the application.
To learn more about database username limits, click your database type to expand the following:
MySQL limits the database username to 16 characters. The system includes the database prefix (the first eight characters of the cPanel account's username and an underscore character) in the character count for the username.
MariaDB limits the database username to 47 characters. The system includes the database prefix (all of the cPanel account's username and an underscore character) in the character count for the username.
Generally, you must separate the databases for your webmail applications, to avoid shared database passwords 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
- If there is no SQLite support, you must create a MySQL® user and database for each user in question, and store its data locally.
- To automate this action after account creation, use the postwwwacct hook.
- Your installation script must go through all cPanel users on a system and set up the MySQL user and a database for each user.
Step 3: Package the application
After you integrate your application, package it for distribution and installation. We recommend that you package the application a
.tar file (tarball) that contains the following:
- Pristine sources
- A patch file
- An installation script
- An uninstall script
Pristine sources and patch
A webmail application often requires pristine sources and a patch. This also allows users to see how you achieved your webmail integration, and what changes that the integration made to the source base.
Installation and uninstallation scripts
We recommend that you provide installation and uninstallation scripts in order to simplify the new application's installation process. The installation script should perform the following tasks:
- Extract the pristine sources into the
- Apply the patch.
- Create the webmail registration file.