dot-courier - Local mail delivery instructions
In most cases delivering mail to an account means simply placing the message in
the account's system mailbox, but that does not have to be the case. Alternate
mail delivery instructions include running a separate program to process the
message, or forwarding the message to another address. The various .courier
files specify some basic mail delivery instructions. If sophisticated mail
filtering is required, the delivery instructions should include running an
external mail filter, such as maildrop
The file $HOME/.courier specifies how messages are delivered to this account. If
this file does not exist, default instructions set by the system administrator
are used. The system administrator's default instructions specify the location
of the account's system mailbox.
In addition to receiving mail addressed user@domain, it is also possible for
user to receive mail addressed to user- foo
@domain, for arbitrary
values of foo
. To do this, install $HOME/.courier- foo
delivery instructions for mail addressed to user-foo@domain.
The system administrator can configure the Courier mail server to accept mail
without regard to whether addresses are in uppercase and lowercase. In that
case the name of a .courier file must contain only lowercase characters. In
any event, all periods in the address must be replaced with colons. For
example, to specify delivery instructions for user-Foo.Bar@domain, put the
delivery instructions in ~user/.courier-foo:bar.
The file $HOME/.courier-foo-default specifies delivery instructions for any
@domain address, where bar
can be anything.
However, it does NOT control mail delivery to user-foo@domain, which is
controlled by $HOME/.courier-foo.
Possible mail delivery instructions include: whether each message should be
delivered to a non-standard mailbox; forwarded to another E-mail address; or
if another program should be executed to handle the message. Programs executed
from a .courier file have access to some environment variables (see
ENVIRONMENT VARIABLES). Programs executed from a -default file can read those
environment variables to determine the exact E-mail address the message was
The /etc/courier/aliasdir directory is searched as the last resort, when all
attempts to figure out how to deliver mail to a local address have failed.
/etc/courier/aliasdir's functionality is very similar to how the alias account
is implemented in Qmail, except that no actual system account is needed. If
<email@example.com> is a local address, and there is no such system
account, nor is there an alias defined for this address, the Courier mail
server attempts to read delivery instructions from
All the usual aspects of .courier deliveries apply. If there is no account that
corresponds to the address <firstname.lastname@example.org>, the Courier mail
server looks for /etc/courier/aliasdir/.courier-user-foo, then
/etc/courier/aliasdir/.courier-user-default, and finally
It therefore follows that you can use /etc/courier/aliasdir/.courier-default to
specify local mail delivery instructions for addresses that do not exist.
Combined with dynamic mail delivery instructions (see below), that's one way
to specify non-standard locations of mailboxes.
The directory /etc/courier/aliasdir/.courier-:xalias/ is created and maintained
by the makealiases
(8) script to implement aliases that
deliver directly to programs or mailboxes. See makealiases
for more information. (This directory corresponds to local addresses that
begin with ".xalias/", but the Courier mail server prohibits
explicit local addresses that begin with a period).
(8) creates subdirectories named
" is set by the -m
Each .courier file specifies zero or more delivery instructions. If the .courier
file is zero bytes long, it means that default mail delivery instructions set
by the system administrator should be used. If the file is not a zero length
file, and does not specify any delivery instructions, messages to the
corresponding E-mail address are silently discarded.
If $HOME/.courier does not exist, it is treated as a zero-length file, resulting
in a delivery to a default mailbox. If $HOME/.courier-foo does not exist, it
is treated as a non-existent address, returning the message as undeliverable.
If home directories have global read and execute permissions, the Courier mail
server will be able to reject mail to non-existent mailboxes right away. the
Courier mail server's ESMTP server runs as a non-privileged process. It will
not be able to access home directories which do not have global read and
execute permissions. Therefore, the message will be accepted for delivery, by
the Courier mail server. As soon as an attempt to deliver the message is made,
the missing .courier file will result in the message being returned as
undeliverable. However, here the Courier mail server has to accept the message
for delivery first, before generating a non-delivery report.
Delivery instructions in .courier are executed one at a time. If the execution
of a delivery instruction fails for some reason, the message is either
returned as undeliverable, or requeued for another delivery attempt. Messages
that remain queued for a long period of time are returned as undeliverable.
Even if one delivery instruction fails (and the message is returned as
undeliverable) previous delivery instructions in the file will have been
Blank lines in the file are ignored. Lines starting with the # character are
comments, and are also ignored. Otherwise, each line specifies one of three
possible delivery instructions: deliver to a system mailbox or a Maildir; run
an external program; or forward the message to another address.
Lines that start with the . or the / character specify a mailbox or a Maildir
delivery. The line must specify the complete location of the mailbox file, or
a Maildir. Filenames starting with . are relative to the account's home
directory. A mailbox file is a traditional mailbox file that's readable by
most mail software. A Maildir is a directory based mail storage format that
offers several advantages over mailbox files. Mailbox files must be locked,
and therefore they do not permit concurrent mail deliveries. The mailbox file
must be locked while a new message is appended to it, otherwise multiple
messages being delivered at the same time will trample all over each other.
Maildirs do not require locking, and multiple concurrent deliveries can be
made to the same Maildir. You can create Maildirs by using the
The Courier mail server does not implement the "dot-locking" form of
mailbox file locking. The Courier mail server's locking abilities are limited
solely to system file locking facilities (namely the lockf
system calls). You can always use maildrop
which offers additional locking options.
Lines that begin with a single | character run an external program. The rest of
the line specifies the command to be executed by the shell. Long commands can
be continued on another line by terminating the previous line with the \
The Courier mail server runs the specified command, and provides the contents of
the message on standard input.
The Courier mail server waits until the external command completes execution
before going to the next delivery instruction. The Courier mail server
examines the exit code of the external command in order to determine whether
the delivery failed, or not.
If the external command terminates with the exit code of zero, the next delivery
instruction is executed. If the command was the last delivery instruction in
the file, the message is considered to be successfully delivered.
If the external command terminates with the exit code of 99
additional delivery instructions in the file are NOT executed, but the message
is considered to be successfully delivered.
If the external command terminates with the “EX_SOFTWARE” exit
code, which is usually 70, on most platforms, the E-mail message gets returned
as undeliverable, a non-delivery report, and no further delivery instructions
If the external command terminates with any of the following exit codes:
, or 112
, the delivery attempt is considered to be
failed, and the next course of action gets selected by Courier mail server's
backscatter suppression settings, as described in the “ Backscatter
” section of the installation instructions; see
(8) for more information.
If the external command terminates with any other exit code, it is interpreted
as a temporary error, and the message will be requeued for another delivery
On subsequent delivery attempts, delivery instructions will be carried out from
the beginning of the .courier file.
Lines that begin with the || characters also run an external program. The rest
of the line specifies the command to be executed by the shell. Long commands
can be continued on another line by terminating the previous line with the \
However, programs that are executed by the || instruction, unlike |, have their
standard output captured, and reinterpreted as additional delivery
instructions to be carried out. This feature allows an external program to be
invoked to generate dynamic delivery instructions to be carried out by the
Courier mail server.
The standard output of the external program is read and parsed as if it
contained .courier delivery instructions. There's a fixed upper limit on the
number of bytes in dynamically-generated delivery instructions. For glibc, the
limit is 8191 bytes, other systems's upper limit should be similar.
The dynamically generated delivery instructions may also specify ||
instructions, recursively. There is an upper limit of four recursive
dynamically-generated delivery instructions.
The exit code of the program invoked by the || instructions are interpreted
exactly like the exit code of a program invoked by |, with the following
exceptions. Dynamically-generated delivery instructions are carried out only
if the external program terminates with an exit code of 0
Any other exit code discards any dynamically-generated delivery instructions.
All other aspects of exit code treatment of external programs remains the
same. If the exit code is 99
, the delivery is deemed to be successful,
and any additional instructions in the original .courier file are ignored. If
the exit code is 0
, the remaining instructions in the original .courier
file are executed.
When the Courier mail server delivers to default delivery instructions in
/etc/courier/aliasdir, those delivery instructions are carried out under the
Courier mail server's installed system user and group id. That means that any
executed programs or mailboxes are accessed as the Courier mail server's mail
system user and group.
External commands executed from the .courier file will have the following
The home directory.
The recipient's userid.
The message envelope return address.
The complete receipient address.
When RECIPIENT is of the form
user@domain, HOST contains the domain part of the address.
When RECIPIENT is of the form
user@domain, LOCAL contains the user part of the address.
When USER is of the form $USER-foobar,
EXT will contain the foobar part.
The portion of EXT that follows the
The portion of EXT2 that follows the
The portion of EXT3 that follows the
When delivery instructions for the address
user-foo-bar@domain come from the file $HOME/.courier-foo-default,
DEFAULT will contain the bar part.
This environment variable contains the entire
From_ header that should be prepended to the message if it is to be delivered
to a mailbox.
This environment variable contains the entire
This environment variable contains the entire
When the external program reads the message from standard input, the message
will NOT have the customary From_, Return-Path:, and Delivered-To: headers
which are customary for locally-delivered messages. The external program can
find those headers in the respective environment variables. If you have a
command that expects to see those headers as a part of the message, you can
use the preline
(1) wrapper to add them to the message. For
example, the procmail
mail filter requires those headers.
mail filter will not require preline
if the system
administrator correctly configures the Courier mail server. The system
administrator can optionally configure the Courier mail server to recognize
, and activate certain maildrop
in the Courier mail server. If these arrangemenets have been made, you can run
directly from the .courier file, in a straightforward fashion,
but those headers will automatically appear in the message, as seen by
. Because the message is provided directly on standard input,
without using a pipe, maildrop
will be able to deliver the message
directly from the Courier mail server's message queue, without using a
Lines that do not start with the ., /, or the | character specify a
comma-separated list of E-mail addresses to forward the message to. If the
line starts with either the & or the ! character, the character is
ignored; this is a legacy compatibility option.
The Courier mail server's .courier may seem to be exactly like Qmail's .qmail,
but there are some minor differences. Qmail, as of 1.03, does not implement
dynamic delivery instructions. The Courier mail server also uses a slightly
different set of return codes which are classified as hard errors. The Courier
mail server's implementation of forwarding differs from Qmail's. According to
Qmail's documentation, if any external command terminates in a permanent or
temporary failure, the message is not forwarded to any forwarding address in
the .qmail file, even to addresses that precede the failed delivery
instruction. The message is forwarded only after it is successfully delivered.
The Courier mail server forwards messages to addresses immediately. Also, in
some cases Qmail resets the return address on the message to the address of
the account being forwarded.
To make things more confusing, there is a configuration setting to have the
Courier mail server read $HOME/.qmail files, instead of $HOME/.courier.
- Backscatter Suppression