Provided by: courier-mta_0.68.2-1ubuntu3_amd64 bug

NAME

       dot-courier - Local mail delivery instructions

SYNOPSIS

       $HOME/.courier

       $HOME/.courier-foo

       /etc/courier/aliasdir/.courier-foo

DESCRIPTION

       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(1)[1].

       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, with
       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 user-foo-bar@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 delivered to.

   Default delivery instructions
       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, the Courier mail server 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>, the Courier mail server 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.

   Program/mailbox aliases
       The directory /etc/courier/aliasdir/.courier-:xalias/ is created and maintained by the makealiases(8)[2]
       script to implement aliases that deliver directly to programs or mailboxes. See makealiases(8)[2] 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).

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

   DELIVERY INSTRUCTIONS
       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, 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.

           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.

   DELIVERY TO A SYSTEM MAILBOX OR A MAILDIR
       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)[3] command.

           Note
           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, or flock system calls). You can always use maildrop(1)[1], which offers additional locking
           options.

   RUNNING AN EXTERNAL PROGRAM
       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.

       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, 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, 100, 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.

   DYNAMIC DELIVERY INSTRUCTIONS
       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 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 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.

   Alias-based deliveries
       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.

   ENVIRONMENT VARIABLES
       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)[4] 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
           the Courier mail server. The system administrator can optionally configure the Courier mail server to
           recognize maildrop, and activate certain maildrop-specific optimizations in the Courier mail server.
           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 the Courier mail server's message queue, without
           using a temporary file.

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

BUGS

       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.

SEE ALSO

       dot-forward(1)[5], maildirmake(1)[3], maildrop(1)[1], courier(8)[6].

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. maildrop(1)
           [set $man.base.url.for.relative.links]/maildrop.html

        2. makealiases(8)
           [set $man.base.url.for.relative.links]/makealiases.html

        3. maildirmake(1)
           [set $man.base.url.for.relative.links]/maildirmake.html

        4. preline(1)
           [set $man.base.url.for.relative.links]/preline.html

        5. dot-forward(1)
           [set $man.base.url.for.relative.links]/dot-forward.html

        6. courier(8)
           [set $man.base.url.for.relative.links]/courier.html