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.
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 the
.yamlfile extension, or the system will ignore it.
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:
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.
You must edit the following key settings in the configuration file or configuration file processor.
These settings vary 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 the
Webmail applications may specify which IMAP, POP3, or SMTP server that they use in the configuration file. Make sure that you set this 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:
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, in order to avoid shared database passwords between cPanel accounts.
After you integrate your application, package it for distribution and installation. We recommend that you package the application in a
.tar file (tarball) that contains the following:
A webmail application often requires pristine sources and a patch. This allows users to see how you achieved your webmail integration, and what changes that the integration made to the source base.
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:
There is no content with the specified labels