Page tree
Skip to end of metadata
Go to start of metadata

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.

Integrate custom webmail applications

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, /3rdparty/webmailapp/).
  • displayname — The name that the cPanel interface will display (for example, Webmail Application).
  • icon — The path to the icon that the cPanel interface will display (for example, /3rdparty/webmailapp/icon.png).

Use the following Perl script, only as an example, to generate the webmail registration file:


Edit the Perl script to fit your needs.


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");

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.


The name of the file in /var/cpanel/webmail/ directory must begin with webmail_ and end with the .yaml file extension, or the system will ignore it.



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

Automate logins

To automate logins, modify the login form to pull the authentication data from the REMOTE_USER and 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 vary from application to application.


User files

You must specify a location in which to store temporary files for the user, such as the homedir/tmp/appname directory.


In this example:

  • homedir represents your home directory
  • appname represents a directory of the same name as the application.

System application paths

Some webmail applications rely on operating system-level utilities, such as the aspell or gpg programs, in order to provide certain features. Most often, a webmail application automatically detects these utilities. Others may require you to provide the location of these utilities in a configuration file. This varies based on the webmail application.

Mail servers

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 localhost server).


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.

For example:

  • A MySQL database with the db_ prefix allows usernames up to 13 characters long.
  • A MySQL database with the example_ prefix allows usernames up to eight characters long.

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.

For example:

  • A MariaDB database with the db_ prefix allows usernames up to 44 characters long.
  • A MariaDB database with the example_ prefix allows usernames up to 39 characters long.

Configure databases

Generally, you must separate the databases for your webmail applications, in order 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 /homedir directory.
  • If there is no SQLite support, you must create a MySQL® user and database for each webmail user, 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.



Package the application

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:

  • 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 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 /usr/local/cpanel/base/3rdparty directory. 
  • Apply the patch.
  • Create the webmail registration file.


Additional documentation