acmemail is a webmail application written in Perl. It enables multiple users to check their mail (residing on a POP3 or IMAP mail server) via the web using their web browser. Requirements: a web server, CGI access, Perl.
Quite a few such webmail applications exist -- features which separate acmemail from the competition include the fact that it fully supports MIME messages, that is has a "pretty" user interface, and that security is very important to the development team.
acmemail doesn't aim to compete with Hotmail or any other such free email site at the moment because you need to have an existing POP3 email account, CGI access on a web server, and currently quite a bit of spare time to set it up. This may change in the future.
The motivation for developing acmemail came from the fact that the company I was working for at the time had a very restrictive firewall. This meant that I couldn't check my mail from the outside. In this case both the POP3 server and the web server that acmemail was running on were behind the firewall -- which didn't let POP3 out, but did however let the web server serve pages to the outside world. Hence the need for a light-weight webmail solution.
acmemail's target market is small companies, departments, universities
and even ISPs that wish to provide a webmail solution for their users.
Note that its scalability has not been fully tested, although it
The 2.0.x acmemail release (quite old now) had fairly limited capabilities: it was single user, could only handle POP3 servers, was hard to configure, and had little documentation.
The 2.2.x acmemail release is much more capable: it is multiuser, can use files or a real database to handle sessions, can handle IMAP servers and there have been a large number of bug fixes, as well as performance and security improvements.
However, it is still quite hard to customize acmemail and a great many changes are planned for the next version, code-named "Project Sparkle". Read about it in the section named "The future: Project Sparkle". We live in very exciting times.
And remember, it's "acmemail", not "Acmemail"!
acmemail has the following features:
The last one may not be true.
acmemail currently requires a number of programs to be installed. In fact, it mostly needs services rather than specific programs, so when necessary we'll list programs that acmemail has been developed with.
The most common platform used to develop acmemail is Linux, Apache, the University of Washington IMAP server, and sendmail or Exim. There is no real reason why acmemail shouldn't run under a non-Unix system such as Windows or MacOS -- we just haven't tried it ourselves. Feel free to do so and tell us how it went!
acmemail is freely available from its .
Installing acmemail is unfortunately quite a hard and long task.
As we don't believe in reinventing the wheel, we use a lot of
Perl modules from CPAN. All of these have to be installed, including
the rather troublesome "
If your setup isn't exactly a Red Hat 6.1 box then this may not quite work. We're in the process of automating this procedure, so this chapter will hopefully disappear some time soon. However, since everyone has a slightly different system and file layout, please read and understand this section -- sorry.
This will get everything working. You may want to change some of the way we've done things. You may want database support, not POS. This isn't the most efficient way of installing either. Still, at the very least this should prove as a guide. In the following text '(yak yak yak)' means the computer responds with about a couple of hundred lines of useless of uninteresting code you can ignore...
Download a copy of acmemail-2.2.2.tar.gz. From the directory acmemail is downloaded to do the following to extract the files and put them in the right place...
[mark@slave mark]$ su
Password:
[root@slave mark]# cp acmemail-2.2.2.tar.gz /home/httpd/cgi-bin/
[root@slave mark]# cd /home/httpd/cgi-bin/
[root@slave cgi-bin]# gunzip -c acmemail-2.2.2.tar.gz | tar -xf -
[root@slave cgi-bin]# rm -f acmemail-2.2.2.tar.gz
[root@slave cgi-bin]# mv acmemail-2.2.2 acme
[root@slave cgi-bin]# cd acme
[root@slave acme]# chown nobody.nobody dope mime-tmp
[root@slave acme]# mv mime-tmp ../../html
[root@slave acme]# mv graphics/ ../../html/acmegraphics
Okay, now reconfigure acmemail to run correctly by editing
sub image_path() {
return '/acmegraphics/';
}
sub smtphost() {
return 'localhost';
}
sub local_domain() {
return 'example.com'; # you need to change this to your own domain
}
sub session_type() {
return "POS"; # using files and Persistant::Object::Simple
# return "Database"; # using a real database
}
# Where is the temporary mime directory?
sub temporary_mime_directory() {
return "../../html/mime-tmp/";
}
# Where is the temporary mime directory? (in relation to the web server)
sub web_temporary_mime_directory() {
return "/mime-tmp/";
}
To save and exit in emacs do a Ctrl-X Ctrl-S Ctrl-X Ctrl-C -- but I should hope you know that already... Likewise it's Esc:qw for vi.
While connected to the Internet do the following:
[root@slave acme]# perl -MCPAN -e shell;
At this point if it's your first time running CPAN you'll need to answer a whole host of questions. On a Red Hat 6.1 box you can normally hit return for all questions but the ones on geography. Be sure to select follow.
cpan> install Bundle::CPAN
This installs the latest version of CPAN, making your and my life easier, and also happens to install some of the modules that we want to install for acmemail anyhow.
cpan> exit
Lockfile removed.
[root@slave acme]# perl -MCPAN -e shell;
cpan> install CGI
(yak yak yak)
cpan> install HTML::Entities
(yak yak yak)
cpan> install Mail::Internet
(yak yak yak)
cpan> exit
Lockfile removed.
Now we have to install
[root@slave acme]# cd
[root@slave /root]# wget http://www.cpan.org/modules/by-module/Mail/Mail-Cclient-0.6.tar.gz
(yak yak yak)
[root@slave /root]# gunzip -c Mail-Cclient-0.6.tar.gz | tar -xf -
Now get the (1.8MB) source distribution that this module relies on. This is probably on the Red Hat source distribution, but that's on th e other side of the room at the moment, and I'm feeling lazy
[root@slave /root]# wget ftp.cac.washington.edu:/mail/imap-4.7b.tar.Z
[root@slave /root]# gunzip -c imap-4.7a.tar.Z | tar -xf -
[root@slave /root]# cd imap-4.7b
[root@slave imap-4.7b]# make slx
(yak yak yak)
[root@slave imap-4.7b]# cd ../Mail-Cclient-0.6
[root@slave Mail-Cclient-0.6]# perl Makefile.PL CCLIENT_DIR=../imap-4.7b/c-client/
(yak yak yak)
[root@slave Mail-Cclient-0.6]# make
(yak yak yak)
[root@slave Mail-Cclient-0.6]# make install
(yak yak yak)
Note: If you get lots of "sv_undef undeclared" errors, add "POLLUTE=1" to the "perl Makefile.PL..." command.
Okay, that should have installed everything. We'd better clear up after ourselves, but you might want to leave these installation files around till you're sure everything has worked, and come back and delete them at the end.
[root@slave Mail-Cclient-0.6]# cd
[root@slave /root]# rm -rf Mail-Cclient-0.6
[root@slave /root]# rm -rf imap-4.7b
Phew! Now back to CPAN
[root@slave /root]# perl -MCPAN -e shell;
cpan> install MIME::Entity
(yak yak yak)
cpan> install Persistence::Object::Simple
(yak yak yak)
cpan> install Time::CTime
(yak yak yak)
cpan> install URI::Escape
(yak yak yak)
cpan> install DBI
(yak yak yak)
Your system probably isn't set up for IMAP, even if you did install the right RPMs at install time. You'll need to edit your inetd file like so...
[root@slave acme]# emacs /etc/inetd.conf &
You're looking for the line which reads
#imap stream tcp nowait root /usr/sbin/tcpd imapd
Remove the hash (the '#') from the front, save and exit emacs, and then restart your server with this command :
root@slave init.d]# /etc/rc.d/init.d/inet restart
Stopping INET services: [ OK ]
Starting INET services: [ OK ]
In order to clear up after yourself you need to periodically clear
house on the old and out of date files. To do this you need to
add the following lines to
/usr/sbin/tmpwatch 20 /home/httpd/html/mime-tmp
/usr/sbin/tmpwatch 20 /home/httpd/cgi-bin/acme/dope
Boot up your browser of choice and go to:
If all goes to plan you should see a login prompt. Try typing in your user name and password (you have set up a mail account on the server haven't you?) and you should display a list of messages in your inbox. If you don't have any messages then either:
Then list the messages again. Now click on one of the subject lines and, hopefully, the message should be displayed. Try sending yourself some test messages, ones with an image, a binary file or a web page attached. Try multiple attachments. Try sending yourself a forwarded message. If all these work then you're definitely getting somewhere. Try replying, forwarding and just plain sending a message. Try attachments. Try life, Try a great big TV. Try apologizing for ripping off Trainspotting adverts.
Annnnywaaaay. Back on the plot.
There are quite a few temporary files in acmemail, and we would like
to restrict direct viewing of these files / directories. In Apache
this can be done by adding the following lines to the Apache
configuration file (probably
<Directory /home/httpd/html/mime-tmp>
Options None # no options means no indices/browsing
</Directory>
Above we've just set up acmemail to use POS (
We're not going to explain how to configure or install a database -- that's way outside the scope of this document. Acmemail current ships with scripts to set up the database tables for MySQL and PostgreSQL. Scripts for other databases will be similar.
Note that for the following you'll need to have a username/password which can create a database and tables. You may have to amend the scripts.
With MySQL (given a username/password), something like the following should do:
% mysqladmin create acmemail
Database "acmemail" created.
% mysql acmemail < mysql.sql
With PostgreSQL (given a username/password), something like the following should do:
% su - postgres
[postgres@leonsplace pgsql]$ createdb acmemail
[postgres@leonsplace pgsql]$ psql acmemail < postgresql.sql
[postgres@leonsplace pgsql]$ exit
Once that has been done, you have to change various parameters in
# What kind of sessions are we going to use?
sub session_type() {
# return "POS"; # using files and Persistant::Object::Simple
return "Database"; # using a real database
}
# If using the Database session type...
# What is the datasource for our database?
sub db_datasource() {
return "dbi:mysql:acmemail:localhost"; # for MySQL
# return "dbi:Pg:dbname=acmemail"; # for PostgreSQL
}
# If using the Database session type...
# What is the username for access to the database
sub db_username() {
return "acme";
}
# If using the Database session type...
# What is the password for access to the database
sub db_password() {
return "thisisasecretpassword";
}
Problem: You get weird errors about undefined values in
Problem: You keep getting "can't log in" messages. Solution: check that you've set the right mail server and that you have actually got an account there and that you've typed the username and password in properly.
Problem: You get a web server error with something like "Can't locate Joe/Bloggs.pm in @INC". Solution: This means you're missing the Joe::Bloggs module. Go find it on CPAN and install it.
Problem: You're tired and can't think of any more 'common problems to write'. Solution: Post documentation you've just written to mailing list and hope for the best (laziness, impatience and hubris etc. etc.)
Problem: You get lots of "sv_undef undeclared" errors while installing Mail::Cclient. Solution: Add "POLLUTE=1" to the "perl Makefile.PL..." command.
Security is very important aspect of a webmail program -- Hotmail, for example, has consistently had security problems in the past. Bugtraq (a security mailing list) notes that many webmail programs are vulnerable to trivial exploits. Acmemail attempts to be as secure as possible by default, although it will allow you to do unsecure things if it is more convenient for you.
There are actually quite a few different aspects of security involved with a webmail program. I'll try and cover everything in as much depth as possible.
Let's make this quite clear: the server side is the web server and the mail server that acmemail is running on or accessing -- these may even be the same machine. We need a username and password to connect to the mail server, so we store this as a session in either a POS file or a database.
The risk here is that you may have users on the web server. If you are simply using POS sessions, the usernames and passwords are visible to anyone in the DOPE directory. There are ways of restricting this, but we much rather prefer database sessions -- the database takes care of the security aspect for us.
With database sesssions, the usernames and passwords are kept in the clear inside the database. Thus if the database is compromised, so will all your usernames and passwords. A solution for this is currently being investigated.
Note that the installation instructions put the DOPE directory outside the web server root -- this is so that web users will not be able to access passwords.
You should consider running acmemail on a secure server (SSL) -- that way the username and password isn't sent over the network whenever a user logs on.
Currently, emails are unpacked onto disk before being displayed. You might consider this a problem if you have users on that machine. This is going to be replaced with decoding on the fly in the next major release.
Ideally, the web server that acmemail is running on should be user-less. This solves many other problems.
The main problem with the client side of webmail programs is to never disclose the session ID. Classically, exploits achieve this by looking at the 'referer' field when a user clicks on a link or views a graphic embedded in a mail message.
One way to reduce this threat is to not keep the session
ID as a CGI parameter but instead as a cookie on the client
acmemail makes sure to only set cookies which
do not have an expiration date -- this means the browser
never saves them to disk. The cookie is expired when
the user logs out. acmemail has a
There is the risk that JavaScript may be embedded into
a mail message somehow -- the code would retrieve the
session ID and then do something evil. Historically,
it has been very tricky trying to filter away
Javascript, so acmemail goes the whole way and can
force you to disable JavaScript completely with the
However, forcing people to disable JavaScript is quite
a strong option - your users will probably complain.
It is for this reason that we have the
acmemail hasn't gone under a lot of performance testing, but it is sufficiently fast on normal hardware for small groups (say a couple hundred people in total). If you wish to scale beyond this, there are various things you should have a look at.
Here we're going to talk about basic acmemail support under normal CGI. There are a number of performance limitations:
IMAP is known to be significantly slower than POP3 so finding a quick IMAP server is fairly important. The IMAP server bundled with Red Hat 6.1 for example, is the . An alternative server which is known to be more scalable is the . However, we haven't benchmarked these -- if you do, please let us know!
Luckily, there
embeds a Perl interpreter into Apache server -- this avoids the overhead of starting an external interpreter and the penalty of Perl start-up time. It even caches the compiled Perl bytecode, giving us a great speedup. This alone should make acmemail from about two to ten times faster (but please do your own benchmarks and send them in!).
In addition to mod_perl you'll also want
Installing mod_perl is a bit challenging as it needs to be
compiled in with the Apache server -- see the
for that. Installing
Enabling mod_perl and
PerlModule Apache::DBI
<FilesMatch "\.pl$">
SetHandler perl-script
PerlHandler Apache::Registry
Options ExecCGI
PerlSendHeader On
</FilesMatch>
Note: There is a major disadvantage to mod_perl -- your Apache processes will use up a great deal more memory. You should plan for this. Also note that mod_perl is a complex program and that tuning Apache and mod_perl for optimum performance is a tricky thing to do, but at least this will help!
Summary: with a bit of work and some higher memory usage, acmemail is able to scale much higher than its original limit. There still remains the problem of IMAP connections -- it's possible that connection pooling will be implemented in a future release.
Well, like any other CGI program acmemail is a state machine. Like a normal program CGI programs must store their state as GET or POST variables or in a persistent objects.
This is in no way meant to be complete or totally accurate documentation of the internal workings of acmemail but it's a start if you want to start looking into the code.
Displays the login box.
Lists messages in the mailbox you have selected. For POP3 this is always the INBOX but for IMAP that could be any of the mailboxes you're subscribed to.
Each line gives information about a message; whether or not you've read this before, who it came from, whether or not it has an attachment, the time it was sent and gives you the option to delete it either individually or en masse.
The subject line is a link to show the message and the name of the person who sent it is a link to compose a message to that person.
Takes either an individual message or a list of messages, deletes them and then lists messages again.
Shows an individual message by recursively MIME decoding each section if there are any. If it's an image (such as a GIF) it saves it and decodes it, saves and then display it inline. Web pages are shown inline too which is rather sexy 'cos all the links are mangled properly to point to an absolute URL rather than relative ones.
There are links to reply, reply to all and forward the message and the name of the sender and other people on the Cc list are turned into links to compose to that person.
Displays all the usual boxes plus one for attachments. Currently no-one can think of a decent way of doing multiple attachments. Bruno Daniels has produced a quick patch that just displays multiple attachment boxes. We'd prefer not to pass round file attachments as parameters (oooh, baaaaaad overheads) or storing the uploads as temporary files but... there's a pint for the first person to come up with something good. Time to look to see how other people do it.
Gets the message body, adds quote marks, sets the to or cc parameters and then calls compose.
MIME encodes what it needs to encodes, sends the mail, and then displays your list of mails.
Of course there are plenty of other auxiliary functions for mangling HTML links, recursively decoding MIME etc. etc.
One of the big problems currently is that HTML formatting is done within lots of different functions which makes it a pain to change the layout and formatting. Hopefully this will change soon. Which leads us neatly onto ...
The future is bright. The future is Sparkle. Ever since he got bored at work one day, had a couple of pints at lunchtime and got ideas above his station (grin) Mark Fowler has been working on a new development tree of acmemail called, for reasons known only to himself, "Project Sparkle". Basically acmemail suffers from its original purpose in that it was never designed to be a totally web based, fully-functional email client. Whilst it's been ripped to shreds and reinvented itself so many times even Madonna's taking notice, it's about time acmemail had a complete rewrite.
The plan is to make it much more modular so that adding features will be easier rather than the current system of shoe-horning them into the existing structure. Things planned for this are:
One idea that has been knocking around is to do with MIME. Currently everything is decoded when you read a message and to download an non-inlinable attachment it has to get saved out as a temporary file. This is not ideal. A better arrangement would be that stuff only gets decoded when necessary and that stuff never has to get saved to disk. This cannot be done using the current MIME modules so either someone will have to write new ones or write patches for one of the current ones.
Currently Project Sparkle is in a state of heavy development -- it only actually parses when it feels like it but as soon as it's a vaguely workable proposition it will become the new development tree. Mark assures me that that'll be 'really soon now'.
acmemail is currently being used as the web based email client for a free, UK based ISP; . For that it's been given a makeover by some professional (web) designers who are also going to give the release version a makeover (or two if, we get themes implemented).
Basically, you think acmemail needs a feature, write it, send in a patch, Leon may or may not include it. Something broken? Ditto. Looking for ideas? Take a gander at the list above or check out the other web-based email clients listed below and steal / be inspired by their feature list.
Coding not your idea of fun? Help with the documentation. Or try get it running on as many different systems and configurations as possible then tell us how you did it and how well it runs.
If we ever get them implemented then write stuff for different languages or write different themes. The list goes on.
"We will fight them on the beaches, we will fight them on the sons of beaches" -- Miguel Churchill, Winston's bastard Mexican brother.
Not really. We don't actually hate people who've written alternatives to acmemail so don't get any funny ideas about hunting them down like dogs. For those people who even considered it for the merest second, find a pony, stroke it and repeat after me "Free Software does not mean brutally slaying people who are writing apps similar to mine". Or something. Remember Open Source(tm) and competition are good things. Although try telling that to Microsoft.
first appeared looking suspiciously like acmemail, even down to the non-transparent GIFs. Now being sold for large quantities of money.
seems quite spartan, but the new development release shows promise.
seems simple to install and lots of features. Written for the Roxen web server.
seems quite popular. Written in PHP.
has turned into a groupware product. Very low bandwidth and simple. Written in PHP.
seems quite cool. Written in Java.
seems very professional and scalable -- currently being used at Oxford with thousands of users. Functional. Written in Perl and for mod_perl.
Please insert names, URLs, and descriptions here. We need some more reviews, and it would be good if they were in depth too. Why should people choose acmemail over any of these?
acmemail is Copyright (c) 1997-2000 Leon Brocard. All rights reserved.
You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.
Leon Brocard wrote the original acmemail and maintains the code. Some of the developers live in the UK (Leon, Mark, Pete, Simon) while others are scattered around the globe. Development is carried out via a developer mailing list, so it doesn't really matter what timezone you're in!
The full list of developers and contributors in alphabetical order follows -- write in if you think you've been missed! Note that a couple people have pushed acmemail in the right direction but haven't actually written code. They are the unsung heroes. We salute them.
See the ChangeLog file distributed with acmemail.
This documentation was originally written by Simon Wistow. The new installation section was written by Mark Fowler. Leon Brocard has amended, reformatted, rephrased and added the security, and performance sections.