Web Development

SolutionBase: Set up Web-based e-mail quickly using SquirrelMail

A good alternative to a traditional client/server-based e-mail solution is to simply set up one that's Web-based. In this article, Jack Wallen shows how to configure Web-based e-mail quickly and easily using SquirrelMail.

SquirrelMail's tagline is "Webmail For Nuts". The way I see it, SquirrelMail is web-based email for those nutty about solid, free solutions for an often difficult-to-fill need. SquirrelMail is one of those packages all-too-often overlooked for one reason: it's free. This of course is the bane of a lot of open source software. Like many OSS tools, SquirrelMail seems to remain, however, in the background running like a champion on many an ISP. In this article, I'll show you what it is and how to get it up and running.

What's SquirrelMail?

The ISP I use for both personal sites and client sites uses SquirrelMail. That's where I first discovered this little gem of a mail system. SquirrelMail is a simple to set up, easy to use, reliable web front-end written in PHP that supports IMAP and SMTP protocols. SquirrelMail has a number of add-ons and a small list of requirements. SquirrelMail is also simple to install and easy to learn.

There are two requirements to meet for installing SquirrelMail:

  • Web server with PHP >= 4.1.2 installed.
  • Access to an IMAP server which supports IMAP 4 rev 1.

The OS is actually irrelevant. Your OS only needs to stably support PHP. So, in order to get SquirrelMail to install, you will have to install an IMAP server such as Dovecot (my IMAP server of choice) and PHP. I, of course, would suggest doing a full install of a Linux distro first, then installing Dovecot, followed by SquirrelMail.

The real instructions

I'm going to assume you've met all the requirements for SquirrelMail on your server. With that out of the way, you'll need to download the latest release of SquirrelMail. This file will look something like squirrelmail-1.4.10a.tar.gz.

The first thing to do is to move that file into your Web server document root. I am installing on an OpenSuSE 10.2, so the document root is located in /srv/www/htdocs/. Once you have moved the file, unpack it. If you downloaded the gzipped .tar file, the command would be tar xvzf squirrelmail-RELEASE-NUMBER.tar.gz.

This next trick will save your users a lot of typing. If you just use the directory as-is, your users will have to point their browsers to something like http://your-domain.com/squirrelmail-1.4.10/ every time they want to check their e-mail. Instead, change the name of the directory. You can change the name of the directory to webmail if you like. Make it something your users can remember.

In Linux, a file gets renamed from the command line with the mv command. So rename the directory like so:

mv squirrelmail-1.4.10 webmail

and you're ready to continue.

Once you have renamed your directory, change into that directory and, as root, run the configure script. Note: If you are within the SquirrelMail directory, to run the configure script, use the command ./configure.

When you run the configure script, you're going to be presented with a few configuration options. The first option is the Main configuration menu:

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Main Menu --
1.   Organization Preferences
2.   Server Settings
3.   Folder Defaults
4.   General Options
5.   Themes
6.   Address Books
7.   Message of the Day (MOTD)
8.   Plugins
9.   Database
10.  Languages

D.   Set pre-defined settings for specific IMAP servers

C    Turn color on
S    Save data
Q    Quit

The first option I will select will be the Organizational Preferences. So, at the SquirrelMail command prompt, I will select:

Command >> 1

The new configuration menu looks like:

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Organization Preferences
1.   Organization Name       : SquirrelMail
2.   Organization Logo       : ../images/sm_logo.png
3.   Org. Logo Width/Height  : (308/111)
4.   Organization Title      : SquirrelMail $version
5.   Signout Page            :
6.   Top Frame               : _top
7.   Provider link           : http://www.squirrelmail.org/
8.   Provider name           : SquirrelMail

R    Return to Main Menu
C    Turn color on
S    Save data
Q    Quit

As you can see, the first choice -- Organization Name -- is set as SquirrelMail. You will want to change this to reflect your client's company name. Select:

Command >>   1

You will then see a brief set of instructions telling you that if you change the Organization Title, new title will appear in most places where SquirrelMail would be named. One other very important bit of information regards names that begin with $. If your company title begins with the $ symbol, it would be treated as the beginning of a variable.

Fortunately, the SquirrelMail developers thought of this and allowed for the inclusion of a $ symbol in the name, but it must be preceded by a \ first. For example, if your company's name is $avings, you'll have to enter \$avings in order to use this as your Organization Title.

I'm going to use my company's name for this option.

[SquirrelMail]: TransLinux

Now we are back to the Organization Preferences menu.

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Organization Preferences
1.   Organization Name       : TransLinux
2.   Organization Logo       : ../images/sm_logo.png
3.   Org. Logo Width/Height  : (308/111)
4.   Organization Title      : SquirrelMail $version
5.   Signout Page            :
6.   Top Frame               : _top
7.   Provider link           : http://www.squirrelmail.org/
8.   Provider name           : SquirrelMail

R    Return to Main Menu
C    Turn color on
S    Save data
Q    Quit

From this same sub-menu, you can configure your company's logo and a few other tidbits of information. Once you are finished with this screen, press [R] to return to the main Configuration window.

Of course, you will have to configure your server settings. To do this, press [2] to enter the Server Settings submenu.

SquirrelMail Configuration : Read: config_default.php (1.4.0)
Server Settings

1.   Domain                  : example.com
2.   Invert Time             : false
3.   Sendmail or SMTP        : SMTP

A.   Update IMAP Settings    : localhost:143 (other)
B.   Update SMTP Settings    : localhost:25

R    Return to Main Menu
C    Turn color on
S    Save data
Q    Quit

Now you need to set the Domain option. Select the 1 option, and you will be greeted with the following text:

The domain name is the suffix at the end of all email addresses.   If
for example, your email address is jdoe@example.com, then your domain
would be example.com.

[example.com]: yourdomain.com      

where yourdomain.com is the domain associated with your client.

The other options to configure are:

  • Invert Time: This option is to get around an IBM AIX/Solaris bug that always reads the time zone as positive. If are using either of those OSs, set this option to false.
  • Sendmail or SMTP: Set this to match outgoing mail system will you be using.
  • Update IMAP Settings: Configure your IMAP address and port.
  • Update SMTP Settings: Configure your SMTP address and port.

Once you have finished these configurations, press [R] to return to the main menu; press [S] to save your configurations. You will be greeted with this message upon saving:

Data saved in config.php
Press enter to continue...

You will then be taken back to the main menu. Press [Q] to quit, at which point you will see:

Exiting conf.pl.
You might want to test your configuration by browsing to

Happy SquirrelMailing!

Before you open up the configtest.php file, you need to follow a few steps not outlined in the installation instructions. Create the following directories:


Then chmod -R 777 the /var/squirrelmail directory.

Fire up Firefox

The next step is to run the configtest.php file in your browser. The address in our example will be http://yourdomain.com/webmail/src/configtest.php . When you open that page, you will see the following text:

SquirrelMail configtest
This script will try to check some aspects of your SquirrelMail configuration and point you to errors whereever it can find them. You need to go run conf.pl in the config/ directory first before you run this script.

SquirrelMail version:


Config file version:


Config file last modified:

10 May 2007 14:55:15

Checking PHP configuration...
       PHP version 5.2.0 OK.
       PHP extensions OK.
Checking paths...
       Data dir OK.
       Attachment dir OK.
       Plugins are not enabled in config.
       Themes OK.
       Default language OK.
       Base URL detected as: http://linux-wsbm/squirrelmail/src (location base autodetected)
Checking outgoing mail service....
       SMTP server OK (220 linux-wsbm.site ESMTP Postfix)
Checking IMAP service....
       IMAP server ready (* OK Dovecot ready.)
Checking internationalization (i18n) settings...
         gettext - Gettext functions are unavailable. SquirrelMail will use slower internal gettext functions.
         mbstring - Mbstring functions are unavailable. Japanese translation won't work.
         recode - Recode functions are unavailable.
         iconv - Iconv functions are available.
         timezone - Webmail users can change their time zone settings.
Checking database functions...
       not using database functionality.
Congratulations, your SquirrelMail setup looks fine to me!

Now that you know it's working fine, let's secure it up and log in. The first thing you will need to do is find out which user is running your Web server. If you're using Apache, you will find this information in the httpd.conf file under the variable called webusername. You need to do is change the ownership of the data directory to the webuser. If your webuser is apache, run the command:

chown -R apache data

from the /var/www/html/webmail directory. Note: Remember, the webmail directory is the squirrelmail-1.4.10 directory, renamed.

Now give the attachments directory over to root with the command chown -R root attachments. Finally, give the attachments directory write (but not read) permissions with this command:

chmod -R 730 attachments

Now you are ready to log in.

Logging in for the first time

Point your browser to http://yourdomain.com/webmail/ to log in to your SquirrelMail server. The index file in that directory will actually point your browser to http://yourdomain/com/webmail/src/login.php but your users don't need to know that. Figure A illustrates the SquirrelMail login screen.

Figure A

A login screen so clean even a squirrel would find nothing to dig up.

Once you log in with your username/password, you will see the main window, the home of your e-mail (see Figure B).

Figure B

The SquirrelMail interface is as simple and user-friendly as it gets.

Further configurations

Now that you have the system up and running where do you go? Outside of revisiting the configuration script (which you should do anyway, to polish up your configuration), you will need to install a few plug-ins before you can do much more.

There are two administration plug-ins you should install. The first plug in you'll need to download is called admin_add. Download this file and then move it to the webmail/plugins directory. Note: I am not including the full path to the plug-ins directory and assuming the standard set in this article is where webmail is the SquirrelMail directory.

Once the plug-in is in the directory, unpack it. Create a file called admins and place it in the /webmail/config directory. In this file, you will place the name(s) of the users (one per line) that will be allowed access to the admin tool. After the last name place, type a few empty carriage returns and save the file.

Now you have to revisit the configure script. Change to the webmail directory and run ./configure again. Now that you're in the configuration menu, enter [8] for the plug-ins menu. You should now see a listing of plug-ins. All you have to do is enter the number for each plug-in to install. So look for the admin_add plug-in, enter the number for that, and press [Enter]. Now add the administrator plug-in in the same way.

Once you have those two plug-ins added, press [S] (to Save) and [Q] (to Quit).

Now log back into SquirrelMail with one of the users added to the admins file. Once logged in, select the Options link and you'll see some Administrator entries now available as seen in Figure C.

Figure C

Before adding the admin plug-ins, the only options available are those for the individual users' account.

The admin_add plug-in just allows those able to use it to add or remove administrators to the system. This is handy for dealing with this issue remotely (when an ssh connection is not available). The real administration takes place within the Administration plug-in. But ultimately what this plug-in does is act as a Web-based interface for the configuration script. As recommended in the Administration plug-in, it is best to use the configuration script because there is additional information to be given, but the plug-in is nice for those who don't like using text-based tools.

Final thoughts

SquirrelMail is one of the most reliable Web-based e-mail systems I've used. I know a lot of hosts that take advantage of this system, and with good reason: it's cost effective, reliable, simple, user-friendly, and cross platform. So if you have a need for a Web-based email system, give SquirrelMail a try. You'd be nuts if you don't try it.


Jack Wallen is an award-winning writer for TechRepublic and Linux.com. He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website getjackd.net.


how to reflect user name on inbox panel in squirrel panel.

Woody Goode
Woody Goode

This is an example of a "tip" that does far more damage than good. 1. As the very first response demonstrates, the author hasn't started by describing the problem and then explaining how the solution best solves it. I can't think of an answer, frankly. Why would you want to both (a) use the mail server of the company hosting the web site to store and process mail AND (b) not use Outlook, Outlook Express or Thunderbird to get the mail? I use the "let the web host process mail" trick all the time for companies too small to want/afford their own mail server, but I sure don't expect people who are leery of computers to use an unfamiliar program and be happy about it (that's why Outlook and OE are listed first, by the way). Webmail would be necessary in only one situation: Users (a) do not have laptops or cannot easily connect them to the internet, (b) they often need to SEND mail from different computers (not merely check it-- you could do that by getting a gmail or yahoo account and having it fetch messages) and (c) they need the sending address to be the company's domain (not gmail, yahoomail, hotmail or their ISP). If none of those situations apply, then you don't need this article. But even if you ARE in that situation, it's not terribly hgelpful. 2. SquirrelMail isn't the only web-based e-mail solutions that is free and reliable. Both Horde and Neomail qualify as well The author doesn't explain why SqM is better, and perhaps that's because he can't. The article mentions that he learned about SqM because his ISP uses SqM. It might well be the only one he knows. 3. I assume SqM is the only one he knows because the ISP that I use offers SqM, Horde and Neomail to people who need webmail. I've found SqM to be BY FAR the least popular among my users and clients. I used to tell users "you pick whichever one you like" (not wanting to be the IT jerk who forces people to use programs they don't like). After about 18 months, I started adding "But most people prefer Horde", because most people do. Horde has the most user-friendly interface, and offers lots of extra features and configuration options. Neomail is popular with folks who seem to like "stripped-down" interfaces. SqM gets responses like "old-fashioned" and "not very friendly" and "yuck". I will say one good thing about SqM. Since its interface is text-based, it loads much faster. On a slow modem connection, where you don't want to wait for icons to load, it is better. But how many people constantly need to send e-mail, from different machines, from connections that are always slow? Would that be "None?" 4. As for the "reliability" caveat-- if the mail is being processed and stored by your web host, THEY are most likely going to be the biggest source of the problem, not the PHP/IMAP solution you use to access mail from the web. And I assume this situation is relying on the web host simply because the article keeps saying that people go to www.your-domain.com/webmail to get mail. If the WEB SITE is being hosted in-house, but the company doesn't have an in-house mail server with a webmail option better than SquirrelMail, they're nuts. Even if a company is so MS-phobic that it won't run Small Business Server (which, after 147 tries, is finally good enough, cheap enough and reliable enough to impress even me), there's no excuse for SquirrelMail. Zimbra is a nifty product-- and you can even install the $0, open-source version and upgrade to the paid version if you want more bells and whistles. The web client (written in Ajax) makes SqM look like a joke, 5. What kind of "Simple and Quick" article says "You need an IMAP server installed and working on your web server, but I'll assume you already have that"? If your host offers an IMAP server without at least one webmail program already installed, you should change hosts. By the way, while the requirements listed here are technically correct, SqM has a long list of "our program works much better if IMAP is set up like this" statements on the web site, and they aren't all "no-brainer" tweaks or trivial issues to correct. Of course, maybe the author just assumes that the IMAP fairies configured it correctly. 6. Another "simple and quick" trick is to suggest that people transfer a compressed file to the web server and then run Linux commands to decompress it and rename directories. That's stupid and irresponsible. Here's the correct way to do this: A. Download the file and verify it (check the Md5 hashes) on a test system NOT A PRODUCTION SERVER. B. Decompress it on the test system and verify that it succeeded. Two of the last three enterprise packages I've downloaded had errors in them (folders weren't being recursed properly). C. Connect to the server with an FTP program and use it to create a "WEBMAIL" folder (not manually rename). D. Transfer the decompressed stuff from the test system to the web server (every FTP program I have seen will either automatically transfer and duplicate the directory structure or ask if you want it done). Other than these flaws, it's a really good piece.


Our school uses Squirrel Mail and we constantly have problems. Takes hours for a cc: to return - and longer for messages to be delivered. Messages are also "lost" with alarming frequency - at least our experience with this system has been negative. This is not managed in-house.


Obviously I'm missing a very basic point here somewhere. What are the pros/cons of using SquirrelMail over other POP3 alternatives such as HotMail, GMail or Yahoo Mail? Yahoo Mail currently has unlimited storage too.

Editor's Picks