dot-qmail - control the delivery of mail messages
Normally the qmail-local
program delivers each incoming message to your
system mailbox, homedir/Mailbox, where
is your home directory.
It can instead write the mail to a different file or directory, forward it to
another address, distribute it to a mailing list, or even execute programs,
all under your control.
THE QMAIL FILE¶
To change qmail-local
's behavior, set up a .qmail
file in your
contains one or more lines. Each line is a delivery instruction.
follows each instruction in turn. There are five types of
delivery instructions: (1) comment; (2) program; (3) forward; (4) mbox; (5)
- A comment line begins with a number sign:
# this is a comment
qmail-local ignores the line.
- A program line begins with a vertical bar:
|preline /usr/ucb/vacation djb
qmail-local takes the rest of the line as a command to supply to
sh. See qmail-command(8) for further information.
- A forward line begins with an ampersand:
qmail-local takes the rest of the line as a mail address; it uses
qmail-queue to forward the message to that address. The address
must contain a fully qualified domain name; it must not contain extra
spaces, angle brackets, or comments:
# the following examples are WRONG
If the address begins with a letter or number, you may leave out the
&email@example.com (New Address)
Note that qmail-local omits its new Return-Path line when
- An mbox line begins with a slash or dot, and does not end with a
qmail-local takes the entire line as a filename. It appends the mail
message to that file, using flock-style file locking if possible.
qmail-local stores the mail message in mbox format, as
described in mbox(5).
WARNING: On many systems, anyone who can read a file can flock
it, and thus hold up qmail-local's delivery forever. Do not deliver
mail to a publicly accessible file!
If qmail-local is able to lock the file, but has trouble writing to
it (because, for example, the disk is full), it will truncate the file
back to its original length. However, it cannot prevent mailbox corruption
if the system crashes during delivery.
- A maildir line begins with a slash or dot, and ends with a slash:
qmail-local takes the entire line as the name of a directory in
maildir format. It reliably stores the incoming message in that
directory. See maildir(5) for more details.
has the execute bit set, it must not contain any program lines,
lines, or maildir
lines. If qmail-local
such lines, it will stop and indicate a temporary failure.
is completely empty (0 bytes long), or does not exist,
follows the defaultdelivery
instructions set by your
system administrator; normally defaultdelivery
appends the mail message to Mailbox
may contain extra spaces and tabs at the end of a line. Blank
lines are allowed, but not for the first line of .qmail
is world-writable, qmail-local
stops and indicates a
SAFE QMAIL EDITING¶
Incoming messages can arrive at any moment. If you want to safely edit your
file, first set the sticky bit on your home directory:
chmod +t $HOME
will temporarily defer delivery of any message to you if your
home directory is sticky (or group-writable or other-writable, which should
never happen). Make sure to
chmod -t $HOME
when you are done! It's a good idea to test your new .qmail
qmail-local -n $USER ~ $USER '' '' '' '' ./Mailbox
In the qmail
system, you control all local addresses of the form
user-anything, as well as the address
itself, where user
is your account name. Delivery to
user -anything is controlled by the file
homedir/ .qmail-anything. (These rules may be
changed by the system administrator; see qmail-users(5)
user controls all other addresses. Delivery to local
controlled by the file homedir/.qmail-local,
's home directory.
In the following description, qmail-local
is handling a message addressed
, where local
is controlled by
.qmail-ext. Here is what it does.
If .qmail-ext is completely empty, qmail-local
follows the defaultdelivery
instructions set by your system
If .qmail-ext doesn't exist, qmail-local
some default .qmail
files. For example, if ext
will try first .qmail-foo-bar
, and finally .qmail-default
. If none of these
will bounce the message. (Exception: for the basic
treats a nonexistent .qmail
same as an empty .qmail
For security, qmail-local
replaces any dots in ext
with colons before checking .qmail-ext. For
converts any uppercase letters in
forwards a message as instructed in
.qmail-ext (or .qmail-default
), it checks whether
.qmail-ext-owner exists. If so,
it uses local-owner@domain as the envelope
sender for the forwarded message. Otherwise it retains the envelope
sender of the original message. Exception: qmail-local
always retains the original envelope sender if it is the empty address or
, i.e., if this is a bounce message.
also supports variable envelope return paths
if .qmail-ext-owner and
.qmail-ext -owner-default both exist, it
uses local-owner-@domain-@ as the
envelope sender. This will cause a recipient
recip@reciphost to see an envelope sender of
If a delivery instruction fails, qmail-local
stops immediately and
reports failure. qmail-local
handles forwarding after all other
instructions, so any error in another type of delivery will prevent all
If a program returns exit code 99, qmail-local
ignores all succeeding
lines in .qmail
, but it still pays attention to previous forward lines.
To set up independent instructions, where a temporary or permanent failure in
one instruction does not affect the others, move each instruction into a
separate .qmail-ext file, and set up a central
file that forwards to all of the
.qmail-exts. Note that qmail-local
handle any number of forward lines simultaneously.