You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • Tutorial - Integrate Custom Webmail Applications
Skip to end of metadata
Go to start of metadata

Introduction

Important:

These steps require cPanel & WHM version 11.28 or higher.

This document explains how to integrate custom webmail applications in cPanel's Webmail interface (cPanel >> Home >> Email >> Email Accounts >> Check Email).

For a list of 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 example to generate the webmail registration file:

#!/usr/local/cpanel/3rdparty/bin/perl

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 you run the script, the system creates the /var/cpanel/webmail/webmail_mywebmailapp.yaml registration file. Your webmail application will appear in the Webmail interface.

Important

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




Place and modify the webmail application.

Next, place your 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.
  • Add a button to return to Webmail.
  • Update the application's configuration.
  • Configure databases.

For more information on these modifications, see the Webmail application modifications section below. 




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 items:

  • Pristine sources
  • A patch file
  • An installation script
  • An uninstallation script

For more information on these tarball components, see the Application packages section below.


Webmail application modifications

 Automate logins 

To automate logging in to Webmail, 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.

Add a button for Webmail 

Important:

We introduced this functionality in cPanel & WHM version 84.

You can add a button to redirect users from your webmail application interface to the cPanel Webmail interface. An HTML anchor, around an image and text, forms the button. When the user clicks the button, the action returns the user to the Webmail home interface.

Use the following code to obtain a security token and add the Return to cPanel Webmail button:

// Retrieve the security token
<?php 
    $token = getenv('cp_security_token');
?>
// Add a button
<a href="<?php echo $token; ?>/webmail/paper_lantern/index.html?mailclient=none" title="Return to cPanel Webmail">
    <img src="<?php echo $token; ?>/img-sys/cp-logo-RGB-v42015.svg" alt="cP" style="max-height: 24px"></img>
    WebMail
</a>

The code above contains the following values:

  • $token  — The security token that grants access to the cPanel Webmail interface's session.
  • <a></a> — The anchor tags. Enter the button's text here.
    • href — The Webmail home URL attribute.
    • title  — The button's hover text attribute.
  • <img></img> — The image tags. Enter the button's image attributes here.
    • src — The image file path attribute.
    • style — The image's dimensions attribute.

Update the application's configuration

You must edit the following settings in the configuration file or configuration file processor. This ensures that the application works well with cPanel.

SettingsDescription

User files

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

Note:

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 in order to provide certain features. (For example, aspell or gpg programs.) Most often, a webmail application automatically detects these utilities. Other webmail applications may require you to provide the location in a configuration file of these utilities. These requirements vary based on the webmail application.

Mail servers

Webmail applications may specify which IMAP, POP3, or SMTP server they use in the configuration file. Make sure that you set this to the correct server (usually the localhost server).

Database

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


Important:

To learn more about database username limits, click your database type:

 MySQL 5.6

MySQL version 5.6 limits the database username to 16 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username.

For example:

  • db_ database prefix allows MySQL usernames of up to 13 characters.
  • An example_ database prefix allows MySQL usernames of up to eight characters.
 MySQL 5.7+

MySQL versions 5.7 and later limit the database username to 32 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username.

For example:

  • db_ database prefix allows MySQL usernames of up to 29 characters.
  • An example_ database prefix allows MySQL usernames of up to 24 characters.
 MariaDB

MariaDB limits the database username to 47 characters. The server uses the first nine characters of this limit for the database prefix. The database prefix uses the cPanel account's username and an underscore (_). The server only applies the first eight characters of the cPanel account's username.

For example:

  • db_ database prefix allows MariaDB usernames of up to 44 characters.
  • An example_ database prefix allows MariaDB usernames of up to 39 characters.

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.

Application packages

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 the changes that the integration made to the source code.

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.