Shicks! - Manual

This manual describes how to install and use the Shicks! POP3/SMTP server, version 2.0


The first section gives you some background on what Shicks! is, and what it can do for you.

What is POP3?

POP3 is a standardized internet protocol for retrieving mails from a mailbox. POP3 knows about users and mailboxes and how to read mail, but it doesn't know anything about how to send mail. This is why in most mail programs, you have to specify both a POP3 and a SMTP server.

Technical Note: The standard is defined in RFC 1725, which can be found online an TCP/IP reserves Port 110 for POP3 servers.

What is SMTP?

SMTP is a standardized internet protocol for sending mails to a local or remote mailbox. SMTP knows how to send mail, but it doesn't know anything about how to read mail, or even what a mailbox is.

Technical Note: The standard is defined in RFC 821, which can be found online an TCP/IP reserves Port 25 for POP3 servers.

What is Shicks!?

Shicks! is a combined POP3/SMTP server. Actually, it is two distinct servers for each protocol, plus a MySQL database that is the central storage for both servers. So, the POP3 server can read the messages stored locally by the SMTP server in the MySQL database.

The MySQL database holds the mailboxes defined on your Server. For each mailbox, you have a username and a password. When you logon to the POP3 server, the username and password are checked against the database. Here are the most common operations:

To be able to receive mails from remote users (users on the internet) their SMTP server has to find your SMTP server. This is done by resolving the name of the e-mail address. This is done by looking at the part of your e-mail address after the '@'. For example, an e-mail address "" will be resolved by looking up DNS entry for "" and connecting the SMTP server there. Actually, most of the time your ISP's SMTP server will do the name lookup for you.

So, in order to receive mails from remote users, your server must have a known DNS entry on the internet

Note that in Shicks!, in contrast to other mail servers, local addresses can be anything. If the SMTP server recognizes a local address, it sends the mail to the local recipient - no matter what. For example, even if your DNS entry is "", you can receive messages for "" as long as the messages are sent from internal users to internal users. Remote users will not be able to access "", because most likely "" will point to a different SMTP server.

But my machine is behind a firewall!

Well, this probably means you cannot receive remote mail. But Shicks! might still be usefull for you, if only to be able to better control mail sent inside your organisation without going to your ISP for every message. For example, if you share a DSL connection with two or three household members, you can easily use Shicks! to setup a local mail system. Using "full blown" mail servers would be way out of scope for your needs, probably.

Installation Instructions

Before you start, you need to check that your system meets the following requirements:


Creating the database

The first step is to create the database. You can do this at the shell prompt using

mysqladmin create maildb

Here, "maildb" is the name of the database. You can choose a different name if you want, but then you'll have to edit the file "". If the database admin account has a password, you can use the "-p" command line option to specify it. You would say:

mysqladmin -p create maildb

and then be asked for a password.

The next step is to create the structure of the database. For this, you need to connect to mysql.

NOTE: Before overwriting the database, please do check if a database named "maildb" already exists and is in possible use by another application.

Here is a sample session on a Win32 machine:

D:\scripts\shicks> c:\mysql\bin\mysql.exe -p
Enter password: **************

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 3.23.43-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> connect maildb;
Connection id:    2
Current database: maildb

mysql> source maildb.sql;
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.01 sec)
Query OK, 0 rows affected (0.00 sec)
Query OK, 0 rows affected (0.02 sec)
Query OK, 0 rows affected (0.01 sec)
Query OK, 0 rows affected (0.00 sec)
Query OK, 0 rows affected (0.03 sec)
Query OK, 0 rows affected (0.03 sec)
Query OK, 0 rows affected (0.00 sec)
Query OK, 0 rows affected (0.02 sec)
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.02 sec)


You can omit the -p option if your database doesn't need name and password. If everything went OK, you now have the data structure set up completely.

Accessing the database from python

IF you have protected your MySQL database with name and password (and you really should), then you need to edit the file Have no fear, its a very small and simple file that holds your name and password for the database at the top. You need to edit this, otherwise python won't be able to connect to the database. More instructions can be found in the sourcecode.

If something goes wrong

If you had problems in any of the steps in this section, you should verify:

Installing the Shicks! Administrator Tool

First of all, open the file "" in your favourite editor. You need to change the line that reads

#! c:\\python21\\pythonw.exe -u

to point to the executable of python. (The linux distribution already uses /usr/bin/python as default, but just in case you have installed python to a different directory you should still check if that line is ok).

You need to copy the files

to your servers' cgi-bin directory. The sourcecode currently assumes that the webserver path will always be


If your webserver has different settings (hint: IIS probably does), you need to either change the source or provide a name mapping between /cgi-bin/ and the directory you install to.

Once installed, open a webbrowser and go to http://localhost/cgi-bin/ . You should see a welcome screen saying "Shicks! Administration".

First-time administration

Check the settings. The path has some defaults, you might want to change these to fit your installation. Note that the path will be created if it doesn't yet exist.

Add at least one user, having one email to the system, so you can later check if it works.

TODO: Add documentation for the admin tool, even though its pretty self-explanatory. Volunteers welcome :)

If something goes wrong

If you had problems in any of the steps in this section, you could take one of the following actions:

Starting the servers

Well, this is the easy bit: Just run and On Windows, if you have the ActivePython distribution installed, you can simply doubleclick the files. (You'll be presented with two console windows saying "POP3Server/SMTPServer is up & running"). On Linux, you should start the apps from a xterm.

Linux only: Determining the installation path for python

The python scripts come with the header line "#!/usr/bin/python". If your copy of python 2.0 resides in a different directory (or is named differently, e.g. "python2.1"), you must modify the script headers. An alternative would be to manually start the files by using a syntax like this: $ /usr/local/bin/python2.1

Installing the Shicks! cgi-Administrator

Copy the file "" to your httpd/cgi-bin directory and mark it as executable (the last step is only required on linux). Then, point your browser to http://localhost/cgi-bin/ and off you go.

Editing the first-time configuration.

When you first started shicks!, it created some default configuration entries. You should now take the time to edit them to your personal needs. Go to the Shicks! Administrator and click on Configuration. The following settings are available:

SPAM detection

shicks! tries to automate spam detection by analyzing incoming subject lines. The keywords recognized are in the file "". You can edit this file if you have new subject lines.

Checking if the mail works

First of, configure your email client. Email client configuration varies widely, so I cannot give a general manual on that; but all Email clients should have configuration entries for POP3 server and SMTP server, respectively. As server name, choose the name of the machine you let both servers run (for testing, this can be localhost []).

Then, you should check, if:

Provided that you've set up a relay SMTP server, you can try the following:

If everything works fine, you've got yourself a shiny new Mailserver :)