You can find our user documentation at

Check out our new API beta site!

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



  • This document is only valid for cPanel & WHM versions 78 and 80.
  • Roundcube version 1.3.8 and earlier does not support email addresses that contain Unicode characters.
  • We recommend that only experienced server administrators perform the steps in this document.
  • cPanel Technical Support does not provide assistance with the instructions in this article.


For instructions on how to migrate SquirrelMail address books to Horde, read our Importing SquirrelMail Address Books to Horde documentation.

This document describes the roundcube_squirrelmail_contact_import plugin.

We deprecated SquirrelMail in cPanel & WHM version 74 and removed it in cPanel & WHM version 78. The roundcube_squirrelmail_contact_import plugin migrates a SquirrelMail user's email contact list to their Roundcube address book. When a Roundcube user logs in to their email account after the hosting provider installs the plugin, the system migrates the user's SquirrelMail contacts to Roundcube.

Install and uninstall the plugin

To install the plugin, run the following command as the root user:

yum install roundcube-squirrelmail-contacts-import-plugin

The system adds the following files to the /usr/local/cpanel/base/3rdparty/roundcube/plugins/ directory:


To uninstall the plugin, run the following command:

yum remove roundcube-squirrelmail-contacts-import-plugin

Configuration options

You can configure the following options for the plugin in the /usr/local/cpanel/base/3rdparty/roundcube/plugins/cpanel_squirrelmail_contact_import/ file:

Sets the full path to the SquirrelMail data directory.
$config['cpanel_squirrelmail_data_dir'] = getenv('HOME'). '/.sqmaildata';
Creates a touch file in the cpanel_squirrelmail_data_dir to prevent the plugin from running more than once.
$config['cpanel_squirrelmail_run_once'] = true;

Checks for duplicate email addresses.

$config['cpanel_squirrelmail_unique'] = false;

Creates a new email folder for imported SquirrelMail contacts.


If you enable this option and set the cpanel_squirrelmail_unique option to true, the system adds any duplicate email addresses to new email groups.

$config['cpanel_squirrelmail_group_name'] = 'SquirrelMail Contacts';

Configures the type of information for the system to record in the cPanel user's /home/user/tmp/error.log file.

  • 0 — Disable this setting.
  • 1 — Only record errors in the error.log file.
  • 2 — Record all information in the error.log file.

$config['cpanel_squirrelmail_log_level'] = 1;

Configures the SquirrelMail files' character set.

To configure this option for the ASCII character set, leave this option blank.

$config['cpanel_squirrelmail_file_charset'] = '';

The full configuration file will resemble the following example:

// full path to the squirrelmail data directory
$config['cpanel_squirrelmail_data_dir'] = getenv('HOME'). '/.sqmaildata';

// Place a "touch" file in $config['cpanel_squirrelmail_data_dir'], preventing the plugin from
// running again if the file exits.
$config['cpanel_squirrelmail_run_once'] = true;

// whether or not to check for duplicate addresses - if used with the
// cpanel_squirrelmail_group_name option duplicates will be added to new groups 
$config['cpanel_squirrelmail_unique'] = false;

// optional new group name for imported contacts - set to false to disable
$config['cpanel_squirrelmail_group_name'] = 'SquirrelMail Contacts';

// log level 0 to disable, 1 for errors only, 2 for verbose
// the default log file is the cpanel users /home/user/tmp/error
$config['cpanel_squirrelmail_log_level'] = 1;

// file charset - e.g. 'EUC-JP'. Leave empty for ASCII.
$config['cpanel_squirrelmail_file_charset'] = '';

The roundcube interface

After you install the plugin, the system migrates any SquirrelMail contacts to Roundcube. These contacts reside in the SquirrelMail mailbox. This mailbox resides in the Personal Addresses mailbox in the Groups section of the roundcube interface.

Log file

The log data for this plugin resides in the /home/username/logs/roundcube file and resembles the following example:


  • In cPanel & WHM version 78, the log data resides in the /home/username/tmp/errors file.
  • In these filepaths, username represents a cPanel user's username.
  • This example displays a list of SquirrelMail address book migration errors.

[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid ökçe - ökç for user]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid Dörte - Dörte@Sö for user]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid θσερ - θσερ@εχαμπλε.ψομ for user]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid 用户@例子 - 用户@例子.广告 for user]
[04-Mar-2019 11:58:49 America/Chicago] [Contacts: Name or email not valid Pelé - Pelé for user]

Additional documentation

There is no content with the specified labels

There is no content with the specified labels

There is no content with the specified labels