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.

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, /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 to generate the 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 .yaml or 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

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 will change drastically 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 aspell or gpg, to provide certain features. Most often, a webmail application automatically detects these utilities. Others may require you to provide the location 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 this is set to the correct server (usually the localhost server).


You must automate the database name and credentials. This will change based on the application.


MySQL limits the database username to 16 characters. The system includes the database prefix in the character count for the username.

For example:

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


Configure databases

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