Overview and Configuration
Qmail is a powerful e-mail package that allows for a great deal of custom e-mail processing and other settings.
Normally, qmail recipes are stored in your account’s home directory, /usr/home/USERNAME. However, to make e-mail handling more reliable, our custom qmail setup has an additional directory to store e-mail recipes: /var/rules/USERNAME. By not having the e-mail recipes in the home directory, it is easier to keep the e-mail files intact.
It should be noted that /var/rules/USERNAME is automatically maintained by the Account Control Center (ACC). You should not put custom recipes there, because they will be overwritten. However, you can set up rules in the ACC, and then check /var/rules/USERNAME to review the format of each recipe.
Filename Structure and Rule Matching
All user configuration files used by qmail start with “.qmail”. A normal account at pair Networks will have two main files:
.qmail
.qmail-default
The .qmail file controls e-mail sent to your username@pair.com, while .qmail-default controls e-mail sent to any domain name in your account. The .qmail and .qmail-default files can reside in the home directory or in /var/rules/USERNAME.
.qmail is not required, but you must have a .qmail-default file (or else mail to your domain name will bounce). For this reason, if there is no .qmail-default file in the home directory, the system automatically creates one for you in /var/rules/USERNAME.
Qmail rules match e-mail addresses from the most specific match, to the least specific. If no match is found, the .qmail-default rule is used.
Please note that if you create .qmail* files locally and FTP them to the server, you must use ASCII mode for the file transfers.
A scenario should help to clarify this and allow it to be explained more easily. In this example, “username” is the account username, and “example.com” will be the domain name on the account.
E-mail sent to the address “sample-test@example.com” will look for these e-mail rule files, in this order:
.qmail-example:com-sample-test
.qmail-example:com-sample-default
.qmail-example:com-default
.qmail-default
The actions found in the matching rule file will be used. More detail is given on specific actions below.
Qmail rewrites periods in e-mail addresses as colons. So, example.com in a qmail rule file becomes example:com.
The files listed above will be used in this way:
.qmail-example:com-sample-test
– will match only e-mail sent to the specific address sample-test@example.com
.qmail-example:com-sample-default
– will match “sample-ANYTHING@example.com,” so in this case it would be used
– will NOT match “sample@example.com”
.qmail-example:com-default
– will match e-mail to any address @example.com that has not already matched anything
.qmail-default
– used for general e-mail to any domain name in your account.
When e-mail comes in, the system checks it against the qmail rules. No matter which directory contains the rules, the most specific qmail rule “wins.” Using joe@example.com as an example, the qmail rules are examined in this order:
.qmail-example:com-joe
.qmail-example:com-default
.qmail-default
If both /var/rules/USERNAME and /usr/home/USERNAME have the exact same file, the one in /var/rules/ will be followed.
Once an “exit” condition has been found within a rule file, parsing stops.
Mail Actions within a qmail Rule
The major categories of actions that can be triggered within a recipe are:
Forward – send the e-mail to another e-mail address
File – save the e-mail to a file on your server
Pipe To Script — pass the e-mail to an external script (this is how the autoresponder in the Account Control Center works)
Qmail rules are plain text files with one action per line. Multiple actions will be parsed until an exit condition is encountered or until the end of the file is reached. The leading character on each line normally determines what happens with the e-mail.
& – Forwards the mail.
/ – Files the mail.
| – Pipes the mail to a script.
Examples
To forward e-mail for sample@example.com to myself@myisp.com, create a file called .qmail-example:com-sample. It would have these contents:
&myself@myisp.com
To save out e-mail for sample@example.com to your incoming e-mail spool, .qmail-example:com-sample would contain:
/var/mail/USERNAME
To save out e-mail for sample@example.com as well as forward it to myself@myisp.com, .qmail-example:com-sample would contain:
/var/mail/USERNAME
&myself@myisp.com
To bounce e-mail for badaddress@example.com back to the sender, .qmail-example:com-badaddress would contain:
|bouncesaying ‘Sorry, no mailbox here by that name.’
“bouncesaying” is a special program that comes with qmail. The message that comes after bouncesaying is what the bounce message will say at the top.
To keep a copy of e-mail to badaddress@example.com under the home directory, while bouncing it back to the sender, .qmail-example:com-badaddress would contain:
/usr/home/USERNAME/badaddress
|bouncesaying ‘Sorry, no mailbox here by that name.’
Note that bouncesaying is considered an exit condition, so it must appear last in the file (or else the mail will not be saved).
Most any combination of applicable forwards, filing, and piping to programs can be used. We recommend testing custom qmail configurations on unused e-mail addresses in your account first, so that no important e-mails are accidentally lost.
