1. Home
  2. Email
  3. Using Qmail

Using Qmail



This article describes features available to Dedicated Hosting and VPS accounts only. However, all account types can make use of Email Recipes. To learn more, please see our Email Recipe tutorial.

Overview and Configuration

Qmail is a powerful email package that allows for a great deal of custom email processing and other settings.

Normally, qmail recipes are stored in your account's home directory, /usr/home/USERNAME. However, to make email handling more reliable, our custom qmail setup has an additional directory to store email recipes: /var/rules/USERNAME. By not having the email recipes in the home directory, it is easier to keep the email 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:


The .qmail file controls email sent to your username@pair.com, while .qmail-default controls email 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 email 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.

Email sent to the address "sample-test@example.com" will look for these email rule files, in this order:


The actions found in the matching rule file will be used. More detail
is given on specific actions below.

Qmail rewrites periods in email 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 email 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 email to any address @example.com that has not already matched anything
  • .qmail-default
    - used for general email to any domain name in your account.

When an email 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:

  1. .qmail-example:com-joe
  2. .qmail-example:com-default
  3. .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 email to another email address
  • File - save the email to a file on your server
  • Pipe To Script -- pass the email 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 email.

  • & - Forwards the mail.
  • / - Files the mail.
  • | - Pipes the mail to a script.


To forward email for sample@example.com to myself@myisp.com, create a file called .qmail-example:com-sample. It would have these contents:


To save out email for sample@example.com to your incoming email spool, .qmail-example:com-sample would contain:


To save out email for sample@example.com as well as forward it to
myself@myisp.com, .qmail-example:com-sample would contain:


To bounce email 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 email to badaddress@example.com under the home directory, while bouncing it back to the sender, .qmail-example:com-badaddress would contain:

|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 email addresses in your account first, so that no important emails are accidentally lost.

Updated on February 27, 2020

Was this article helpful?

Related Articles