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 <user@example.com> is a local address, and there is no such system account, nor is there an alias defined for this address, Courier attempts to read delivery instructions from /etc/courier/aliasdir/.courier-user.

All the usual aspects of .courier deliveries apply. If there is no account that corresponds to the address <user-foo@example.com>, Courier looks for /etc/courier/aliasdir/.courier-user-foo, then /etc/courier/aliasdir/.courier-user-default, and finally /etc/courier/aliasdir/.courier-default.

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(8) for more information. (This directory corresponds to local addresses that begin with ".xalias/", but Courier prohibits explicit local addresses that begin with a period).

Additionally, makealiases(8) creates subdirectories named /etc/courier/aliasdir/.courier-:xalias-protocol/, where "protocol" is set by the -m option.

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. Note: 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, Courier will be able to reject mail to non-existent mailboxes right away. Courier'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 Courier. 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 Courier 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. Note: Even if one delivery instruction fails (and the message is returned as undeliverable) previous delivery instructions in the file will have been completed anyway.

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 maildirmake(1) command. Note: Courier does not implement the "dot-locking" form of mailbox file locking. Courier's locking abilities are limited solely to system file locking facilities (namely the lockf, or flock system calls). You can always use maildrop(1), 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 \ character.

Courier runs the specified command, and provides the contents of the message on standard input.

Courier waits until the external command completes execution before going to the next delivery instruction. Courier 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, any additional delivery instructions in the file are NOT executed, but the message is considered to be successfully delivered.

If the external command terminates with any of the following exit codes: 64, 65, 67, 68, 69, 70, 76, 77, 78, or 112, the E-mail message will be returned as undeliverable, and no further delivery instructions will take place.

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 attempt later. Note: 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 \ character.

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 Courier.

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 or 99. 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 Courier delivers to default delivery instructions in /etc/courier/aliasdir, those delivery instructions are carried out under Courier's installed system user and group id. That means that any executed programs or mailboxes are accessed as Courier's mail system user and group.

External commands executed from the .courier file will have the following environment variables:

HOME

The home directory.

USER

The recipient's userid.

SENDER

The message envelope return address.

RECIPIENT

The complete receipient address.

HOST

When RECIPIENT is of the form user@domain, HOST contains the domain part of the address.

LOCAL

When RECIPIENT is of the form user@domain, LOCAL contains the user part of the address.

EXT

When USER is of the form $USER-foobar, EXT will contain the foobar part.

EXT2

The portion of EXT that follows the first dash.

EXT3

The portion of EXT2 that follows the first dash.

EXT4

The portion of EXT3 that follows the first dash.

DEFAULT

When delivery instructions for the address user-foo-bar@domain come from the file $HOME/.courier-foo-default, DEFAULT will contain the bar part.

UFLINE

This environment variable contains the entire From_ header that should be prepended to the message if it is to be delivered to a mailbox.

RPLINE

This environment variable contains the entire Return-Path: header.

DTLINE

This environment variable contains the entire Delivered-To: header. Note: 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. Note: The maildrop mail filter will not require preline if the system administrator correctly configures Courier. The system administrator can optionally configure Courier to recognize maildrop, and activate certain maildrop-specific optimizations in Courier. If these arrangemenets have been made, you can run maildrop directly from the .courier file, in a straightforward fashion, but those headers will automatically appear in the message, as seen by maildrop. Because the message is provided directly on standard input, without using a pipe, maildrop will be able to deliver the message directly from Courier's message queue, without using a temporary file.

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.