SquirrelMail is a modular system, wherein its functionality can be extended with
extra features provided by various plugins. The plugins may be downloaded from
various sources, one of them being
the SquirrelMail Project's official plugin page.
Read the plugin's documentation and requirements to find out if this is a plugin
that might be used in your setup. Sometimes you might need to uncompress the
plugin package to be able to read the full documentation about it.
Plugins available to SquirrelMail must be stored in the SquirrelMail plugins
directory. Each plugin uses its own subdirectory therein.
Installing a plugin
Installation of a new plugin is done it in a number of steps described below.
Uncompressing a plugin
Download the plugin package, save it in /[path to
SquirrelMail]/plugins/ and uncompress it. This should create a new
directory with the uncompressed plugin in it. Obviously, you have to substitute
[path to SquirrelMail] with the path used at your system. Here's an
tar -xzvf newplugin-1.0.tar.gz
Configuring a plugin
Every plugin should come with a README and/or INSTALL file (and maybe some other
documentation as well) which should always be read before enabling the plugin.
There might be some extra setup steps needed, such as configuring or patching,
that are specific to that plugin or your system, and those steps are described
there. Any dependencies, such as special libraries, should also be listed in the
plugin documentation. However, many plugins require no additional configuration.
Some plugins depend on
the Compatibility plugin, but it might be important which version of the
Compatibility plugin is used.
provides more information as a complement to the plugin's documentation.
Enabling or disabling a plugin
There are two ways to enable or disable a plugin: the configuration script tool,
or to edit the configuration manually. Using the configuration script is
Using the configuration script
Go to the main SquirrelMail directory and run the configuration script, by
cd /[path to SquirrelMail]/
Select the menu option "8. Plugins". This option displays all plugins present in
the directory plugins/ divided in two categories: installed and
available. The installed category lists plugins that are currently enabled, and
the available category lists plugins that are not currently enabled but are
available for use. If you correctly uncompressed the plugin in the right place,
it should be listed among the available plugins.
SquirrelMail Configuration : Read: config.php (1.4.0)
R Return to Main Menu
C Turn color on
S Save data
Each plugin has a number written next to its name. If you enter that number on
the command line, the corresponding plugin is enabled or disabled. Don.t forget
to save your changes by entering "S" at the command line.
Manually editing the configuration file
Find the SquirrelMail configuration file config.php file (usually located in
/[path to SquirrelMail]/config/. Edit it using your favorite text
editor, and add a line similar to this:
$plugins = 'newplugin';
The example above will add "newplugin" as the first plugin (index zero). There
might already be other plugins installed, and if that is the case, make sure to
change the zero to the first available plugin index number, since two plugins
aren't allowed to share index number.
Since SquirrelMail 1.5.2 you also need to edit the file plugin_hooks.php
(usually located in /[path to SquirrelMail]/config/. Inside of that
file, you must add all of the plugin hook registration points that are listed in
the plugin's setup.php file, inside the
squirrelmail_plugin_init_[plugin name]() function.
Test the plugin to make sure that it works. This step is almost always
successful, but if it isn't you may need to get support. Consult the plugin
documentation to find out how to get the support, since it might vary depending
on the plugin. It's usually a good idea to install, enable, and test one plugin
at a time, since some plugins might not go well with the used system setup or
other installed plugins.
There are configuration options dealing with customizing SquirrelMail to your
site available in the configuration tool under "1. Organization Preferences".
For those who prefer manual configuration the same configuration options are
available under the /*** Organization preferences ***/ headline.
TODO: This section has to rewritten with the changes, such as templates, in 1.5.2 when that version is released.
SquirrelMail users are able to customize the look of the interface by selecting
a custom theme and the font style. The configuration options dealing with
customizing SquirrelMail themes and styles available in the configuration tool
under "5. Themes". For those who prefer manual configuration the same
configuration options are available under * Themes.
SquirrelMail themes define interface colors. Each theme is a set of 17 or more
Creating your own theme is very simple. Just go into the themes/
directory and create a file called yourtheme_theme.php. You then need to
create an array with 17 elements (0-16). Below is a theme template followed by a
description of what the different entries are for. Replace each "xxxxxx" with
whatever HTML hex color code that you want for that element.
Here are descriptions of what the different entries in the array are colors of.
The letter after the number denotes "B" for background and "F" for foreground
Title bar at the top of the page header.
Error messages border, usually red.
Error messages, usually red.
Left folder list background color.
Normal background color.
Header of the message index (From, Date, Subject).
Normal text on the left folder list.
Links in the right frame.
Normal text (usually black).
Darker version of #0.
Darker version of #9.
Special folders color (Inbox, Trash, Sent).
Alternate color for message list (alters between #4 and this one).
Color for single-quoted text ("> text") when reading (default: #800000).
Color for text with more than one quote (default: #ff0000).
Non-selectable folders in the left frame (default: $color).
Highlight color (since SquirrelMail 1.5.1, default: $color). Note that even though color 16 is in the templates since SquirrelMail 1.4.6 it's not actually used in the 1.4 branch.
Next all you have to do is run SquirrelMail configuration utility and add the
theme to the list of themes available to you.
It's also possible to provide a style sheet to be included on every page. That's
useful for specifying a site-wide font or other characteristics. More
information about this is available at
the wiki page about style sheets.
SquirrelMail interface can be used with different languages. Default language
can be set in SquirrelMail configuration utility. User can select other language
in Options > Display Preferences. In SquirrelMail 1.4.5/1.5.1 or later
administrator can set default language to empty string. Then interface will try
to detect preferred translation from browser's preferred language setting.
SquirrelMail implements translations with gettext functions. Interface can use
PHP gettext extension or internal gettext implementation. If PHP gettext
extension is used, it might require a special web server setup. On Linux gettext
functions work only when appropriate system locales are available. On BSD you
should be able to set LC_ALL environment variable in PHP script. There are some
differences between GNU Gettext and Solaris Gettext implementations.
Supported character sets
SquirrelMail displays interface in character set that depends on selected
translation. If SquirrelMail has to display email written in other charset,
interface uses special decoding functions that convert email to html codes that
can display foreign symbols in selected character set.
Stock SquirrelMail installation supports following charset decoding
cp1250 (windows-1250) - since 1.4.3 and 1.5.0
cp1252 (windows-1252) - since 1.4.3 and 1.5.0
cp1255 (windows-1255) - since 1.4.3 and 1.5.0
cp1256 (windows-1256) - since 1.4.3 and 1.5.0
cp1258 (windows-1258) - since 1.4.3 and 1.5.0
cp855 (ibm855) - since 1.4.3 and 1.5.0
cp866 (ibm866) - since 1.4.3 and 1.5.0
iso-8859-3 - since 1.4.3 and 1.5.0
iso-8859-6 - since 1.4.3 and 1.5.0
iso-8859-8 - since 1.4.3 and 1.5.0
iso-8859-10 - since 1.4.3 and 1.5.0
iso-8859-11 - since 1.4.3 and 1.5.0
iso-8859-14 - since 1.4.3 and 1.5.0
iso-8859-16 - since 1.4.3 and 1.5.0
iso-ir-111 - since 1.4.3 and 1.5.0
koi8-u - since 1.4.1 and 1.5.0
tis-620 - since 1.4.3 and 1.5.0
us-ascii - since 1.4.4
utf-8 - two and three byte characters are supported since 1.4.0.
Four byte characters are supported since 1.4.4 and 1.5.1. Five and six
byte character decoding is available since 1.4.4 and 1.5.1, but not enabled
Decoding functions might break in some SquirrelMail versions, if PHP
mbstring.func_overload setting is enabled.
big-5, euc-kr and gb2312 characters can be displayed by Chinese and Korean
translations that use those character sets. Japanese translation can display
iso-2022-jp, euc-jp and shiftjis character sets. Other Eastern characters will
be displayed correctly only when character codes match big-5, euc-kr or gb2312
Other character sets can be decoded with extra decoding library functions. These
functions are loaded automatically since 1.4.4 and 1.5.1, if appropriate files
are present in functions/decode directory.
SquirrelMail can create emails that use character set defined in user's
translation. Composed email must use symbols that are supported by selected
charset. If unsupported symbols are used, browser might use different character
set or html entities instead of entered characters.
Different character set can be used only with US English
translation. Administrator can set that character set in SquirrelMail
1.4.5/1.5.1 configuration utility. Users can also select different character
set, if the Custom Charset plugin is installed.
SquirrelMail supports multiple address book backends. Backends can be
configured to provide access to address books that store entries visible
to one user or to group of users or to all users that use the same
SquirrelMail comes with support for address books in its own flat file format,
any database supported by the PHP PDO or Pear DB abstraction layers, as well
LDAP address books are read-only in SquirrelMail versions until 1.5.2. In
version 1.5.2 and up, you can configure a writeable LDAP address book. The
listing of addresses in a LDAP directory is available only when users search
for addresses unless the listing configuration attribute is set for
the LDAP server in SquirrelMail 1.5.2 and above or you add the following to
the config/config_local.php file in SquirrelMail versions 1.4.23 to
(but not including) 1.5.0:
$ldap_abook_allow_listing = TRUE;
In earlier versions, you'd need to make a small change to the
functions/abook_ldap_server.php file in the list_addr()
function near the bottom of the file (see instructions in the comments for
that function). NOTE: you should exercise caution enabling the listing of
large or public LDAP address book backends. Also note that the maxrows
configuration setting for the LDAP server will limit the number of entries
that are returned when listing it.
Global address book is address book that can be shared between users. Global
address books can be configured in SquirrelMail since 1.4.4 version. Before
than admin had to modify functions/addressbook.php file. There is a typo in
1.4.4 code and if you want to have writeable global address
books, you should apply patch or use newer SquirrelMail version. See
If admin wants to use different backend for address book storage (IMSP,
personal LDAP address books, sticky notes attached to server),
SquirrelMail 1.4.5 and 1.5.1 provide hooks that allow plugins to attach their
own functions during address book initiation and admin needs only a plugin that
can interact with used data storage system. Older SquirrelMail versions
need two extra hooks in functions/addressbook.php. Current backend implementation
is limited to standard SquirrelMail address book format.
How to use shared file based address book in SquirrelMail.
1. Get SquirrelMail 1.4.4, 1.5.1, or any later version.
4. If you want a writable address book, the file must be writable by the user
that the web server runs as.
5. After you have created address book file, go to SquirrelMail configuration
utility, select 6. Address Books option and configure address book in 3.
Global file address book.
If you enter only address book file name, system assumes that address book
is in data directory. For example: global_abook. If you use data directory
to store global address book, remember that personal address books use
.abook suffix. You should not use global address book file with same
suffix, unless you understand what you are doing.
If you enter full path, system uses full path. For example:
If your configuration option contains slashes, but does not look like full
path, system assumes path relative to SquirrelMail top directory.
If you want to use global file based address book in older SquirrelMail
versions, take a look at functions/addressbook.php file. It contains some
comments that explain how to do that without configuration utility.