Development Guides Home >> Quickstart Development Guide

Tutorial - Integrate Custom Webmail Applications

Introduction

This document explains how to integrate custom webmail applications in cPanel's Webmail interface (cPanel >> Home >> Email >> Email Accounts >> Check Email). Integrated webmail applications will appear in the interface in the Change your webmail client section.

For a list of Webmail applications, visit our Application Catalog.

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/mywebmailapp/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.

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 to return to Webmail

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/jupiter/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>
    Return to 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.

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. By default, your homedir is /home/<username>/ .
• 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).

Databases

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

Database usernames have the following limits:

• 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:
  • A 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 80 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:
  • A db_ database prefix allows MariaDB usernames of up to 77 characters.
  • An example_ database prefix allows MariaDB usernames of up to 72 characters.
    Note: We only support MariaDB 10.2 and higher. This is a note.
    
    

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.