Roundcube configuration options

Roundcube webmail has nearly 200 configuration options that allow you to customize it according to your needs and taste and to perfectly interact with your email server infrastructure. After installation local configuration files have to be created and adjusted accordingly.

Starting with Roundcube version 1.0 (current git master), there's one single config file (config/ which only contains the configuration settings that differ from the defaults. Older version have their configuration split in two files (config/ and which together contain all configuration parameters.

Configuration files are pure PHP files and therefore strictly have to respect the PHP syntax. If you see a blank page you likely have a syntax error on your config file(s). Check the web server's error logs to find out why and where.

The following sections will explain the most common settings one need to make before starting to use Roundcube. If the local config file doesn't already contain one of the listed options simply copy it from the config/ file. There, every configuration option is preceded with a comment block that explains the option and the possible values to use.

Minimal setup

Database connection


Database connection string for read+write operations
Format: db_provider://user:password@host/database
Currently supported db_providers: mysql, pgsql, sqlite, mssql or sqlsrv
For examples see PEAR MDB2 Docs
NOTE: for SQLite use absolute path: sqlite:////full/path/to/sqlite.db?mode=0646


This key is used to encrypt the users IMAP password which is temporarily stored in the session database. For security reasons it's important that your Roundcube installation has its very own encryption key and that you don't use the default value!

IMAP server connection


By default the login screen provides a text box where you need to enter the IMAP host which you want to connect to. This box can be hidden by setting one fixed IMAP host address:

$rcmail_config['default_host'] = 'localhost';

To use SSL/TLS connection, enter the hostname with prefix "ssl://" or "tls://"

And if you want a drop-down list like it's explained in the comments you need something like this:

$rcmail_config['default_host'] = array('', '', 'ssl://');

In order to show nice labels instead of the host names in the drop-down box write it this way:

$rcmail_config['default_host'] = array(
  '' => 'Default Server',
  '' => 'Webmail Server',
  'ssl://' => 'Secure Webmail Server'


Usually email addresses are not case-sensitive and Roundcube by default converts the user name entered in the login form to lower case characters. But your IMAP server may treat user names for login case-sensitive and this option will let you control if and how Roundcube converts the entered username at login:

0: disabled, don't convert the user name
1: domain part only
2: lower-case the entire user name (default)


Use this option if your IMAP server doesn't support UTF-8 for passwords. It's set to "ISO-8859-1" for backward compatibility of Roundcube.


Automatically add this domain to user names for login. Only needed for IMAP servers that require full email addresses for login. Specify an array with 'host' => 'domain' values to support multiple hosts (from default_host):

$rcmail_config['username_domain'] = array(
  '' => '',
  '' => '',


Sometimes hard to understand is the 'auto_create_user' property. So here's a little background: Roundcube doesn't actually manage users, that's all the IMAP server's job. But Roundcube keeps a reference to IMAP users in its local database in order to store settings, address books, spell check dictionaries and cached messages for a particular user. With this option enabled (that's the default), a new Roundcube user reference is created once the IMAP login succeeds. If auto_create_user is set to False, the login only succeeds if there's a matching user-record in the local Roundcube database. Even if a user enters the correct password and the IMAP login succeeds, the login will fail with the message "Login failed" until you manually create such a record in Roundcube's database.

Sending messages via SMTP

For sending emails, Roundcube uses the SMTP protocol to submit a composed message via the "outgoing mail server". Similar to the IMAP connection, configuring the SMTP server is part of a minimal Roundcube setup.


The SMTP server for outgoing messages. To use SSL/TLS connection, enter the hostname with prefix "ssl://" or "tls://".
The host name can contain placeholders which will be replaced as follows:

%h - user's IMAP hostname
%n - hostname ($_SERVER['SERVER_NAME'])
%t - hostname without the first part
%d - domain (http hostname $_SERVER['HTTP_HOST'] without the first part)
%z - IMAP domain (IMAP hostname without the first part)

For example %n = mail.domain.tld, %t = domain.tld

$rcmail_config['smtp_server'] = 'tls://%h';

If this option is left blank, the PHP mail() function is used to send emails. We don't recommend this because mail() suffers of some limitations and doesn't restrict sending to authenticated users only.


SMTP username (if the outgoing email server requires authentication).
Use "%u" to let Roundcube use the IMAP login user name.


SMTP password (if required)
Use "%p" for the current IMAP login password.

Restricting Sender Identities

As with almost any other email client, Roundcube users are free to set any number of sender identities for outgoing mail. This also includes to set an arbitrary email as sender address. A proper SMTP sending policy should prevent people from sending emails with other From: addresses than the one assigned with their account. In order to restrict the sender identity configuration and to avoid WTF when sending is rejected by the SMTP server, the Roundcube config offers the 'identities_level' option which can be set to one of the following values:

0 - multiple identities with possibility to edit all parameters
1 - multiple identities with possibility to edit all parameters except email address
2 - one identity with possibility to edit all parameters
3 - one identity with possibility to edit all parameters except email address
4 - one identity with possibility to edit only signature

Customize the look


This option replaces the Roundcube logo with a custom image.
Specify an URL relative to the document root of your Roundcube installation.


This adds a link to every page to guide your users if they have questions or problems with your Roundcube installation.

You should provide an absolute URL to a support page with a form to submit questions to your support team.


Defaults for user preferences


Advanced configurations

Configuring for Virtual Users

Virtual users are useful for hosting providers where a single mailserver is providing email for a number of different domains. The goal is that the user logs in to roundcube with their email login/password, and roundcube knows where to lookup their complete email address. Two options are support, SQL lookups or a sendmail style virtuser file.

Important: Since version 0.4 this requires enabling the appropriate plugins which are virtuser_file and virtuser_query.

In order to test if virtuser is configured correctly, log in to roundcube with a user that does not exist yet. Compose a message, if you see the From address as user@correct_domain, then it worked. If you see user@localhost, something is wrong. To reset and try again, delete that user from the roundcube users table (all related records will be removed using foreign keys cascading).

1) virtuser_file

$rcmail_config['virtuser_file'] = '/etc/mail/virtuser';

This assumes that the file /etc/mail/virtuser contains information about your virtual users in the following format:

user@domain login1
user@domain login2

2) virtuser_query (SQL)

$rcmail_config['virtuser_query'] = "SELECT email_address FROM database.table WHERE login = '%u'";

If you are using postfix and/or some kind of hosting panel, chances are your email accounts are already stored in a SQL table. If that is the case, you want to lookup the emails with a virtuser_query. Virtuser_query plugin also allows to set all identity fields using the query. The parts of the example query:

// email_address - the first column returned by the query must be the complete email address
// database - name of the database where your table is located, the roundcube db user must have read access
// table - name of the table where your email addresses are stored
// login - name of the field that contains the username that is used to log in to roundcube (and send/receive email)

Deleted messages

Some mail clients just mark messages as deleted and finally remove them when leaving the application. Roundcube by default move messages to the Trash folder when hitting the delete button. However this behavior can be changed by unsetting the 'trash_mbox' property and enabling 'flag_for_deletion'. Your configuration could look like this:

$rcmail_config['trash_mbox'] = '';
$rcmail_config['flag_for_deletion'] = true;
$rcmail_config['skip_deleted'] = false;

Messages will now be marked as deleted which can be reverted again. To finally remove them, the user needs to click "Compact" below the folder list.

Further reading

Last modified 11 months ago Last modified on 03/15/15 08:17:51