
getmail documentation

   This is the documentation for getmail version 4. Version 4 includes
   numerous changes from version 3.x; if you are using getmail version 3,
   please refer to the documentation included with that version of the
   software.
   
   getmail is Copyright © 1998-2005 Charles Cazabon.
   
   getmail is licensed under the GNU General Public License version 2
   (only). If you wish to obtain a license to distribute getmail under
   other terms, please contact me directly.
   
Table of Contents

     * getmail documentation
     *
          + getmail documentation
          +
               o Features
               o Differences from previous versions
               o Requirements
               o Obtaining getmail
               o Installing getmail
               o getmail mailing lists
     * getmail configuration
     *
          + Configuring getmail
          +
               o Creating a getmail rc file
               o
                    # Parameter types and formats
                    #
                         @ string
                         @ integer
                         @ boolean
                         @ tuple of quoted strings
                         @ tuple of integers
                         @ tuple of 2-tuples
                    # Creating the [retriever] section
                    #
                         @ What is a "multidrop" mailbox? How do I know
                           if I have one?
                         @ Common retriever parameters
                         @ SimplePOP3Retriever
                         @ BrokenUIDLPOP3Retriever
                         @ SimpleIMAPRetriever
                         @ SimplePOP3SSLRetriever
                         @ SimpleIMAPSSLRetriever
                         @ MultidropPOP3Retriever
                         @ MultidropPOP3SSLRetriever
                         @ MultidropSDPSRetriever
                         @ MultidropIMAPRetriever
                         @ MultidropIMAPSSLRetriever
                    # Retriever examples
                    # Creating the [destination] section
                    #
                         @ Maildir
                         @ Mboxrd
                         @ MDA_external
                         @ MultiDestination
                         @ MultiSorter
                         @ MultiGuesser
                         @ MDA_qmaillocal
                    # Creating the [options] section
                    #
                         @ [options] example
                    # Creating the [filter-something] sections
                    #
                         @ Filter_classifier
                         @ Filter_external
                         @ Filter_TMDA
                         @ [filter-something] examples
                    # getmail rc file examples
          + Running getmail
          +
               o Commandline options
               o Using getmail as an MDA
               o
                    # Using the getmail_maildir MDA
                    #
                         @ Example
                    # Using the getmail_mbox MDA
                    #
                         @ Example
     * getmail troubleshooting
     *
          + Troubleshooting problems
          +
               o Error messages
               o Warning messages
               o Unexpected Behaviour
     * getmail frequently-asked questions (FAQs)
     *
          + Frequently-Asked Questions (FAQs)
          +
               o About getmail
               o Configuring getmail
               o How do I ...
               o Using getmail with other software
               o I think I found this bug in getmail ...
       
Configuring getmail

   Once getmail is installed, you need to configure it before you can
   retrieve mail with it. Follow these steps:
    1. Create a data/configuration directory. The default is
       $HOME/.getmail/. If you choose a different location, you will need
       to specify it on the getmail command line. In general, other users
       should not be able to read the contents of this directory, so you
       should set the permissions on it appropriately.
mkdir -m 0700 $HOME/.getmail

    2. Create a configuration file in the configuration/data directory.
       The default name is getmailrc. If you choose a different filename,
       you will need to specify it on the getmail command line. If you
       want to retrieve mail from more than one mail account, you will
       need to create a separate rc file for each account getmail should
       retrieve mail from.
       
Creating a getmail rc file

   The configuration file format is designed to be easy to understand
   (both for getmail, and for the user). It is broken down into small
   sections of related parameters by section headers which appear on
   lines by themselves, enclosed in square brackets, like this:
[section name]

   Each section contains a series of parameters, declared as follows:
parameter_name = parameter_value

   A parameter value, if necessary, can span multiple lines. To indicate
   that the second and subsequent lines form a continuation of the
   previous line, they need to begin with leading whitespace, like this:
first_parameter = value
    first parameter value continues here
second_parameter = value

   You can annotate your configuration files with comments by putting
   them on lines which begin with a pound sign, like this:
first_parameter = value
# I chose this value because of etc.
second_parameter = value

   Each rc file requires at least two specific sections. The first is
   retriever, which tells getmail about the mail account to retrieve
   messages from. The second is destination, which tells getmail what to
   do with the retrieved messages. There is also an optional section
   named options , which gives getmail general configuration information
   (such as whether to log its actions to a file), and other sections can
   be used to tell getmail to filter retrieved messages through other
   programs, or to deliver messages for particular users in a particular
   way.
   
Parameter types and formats

   Several different types of parameters are used in getmail rc files:
     * string
     * integer
     * boolean
     * tuple of quoted strings
     * tuple of integers
     * tuple of 2-tuples
       
   Each parameter type has a specific format that must be used to
   represent it in the getmail rc file. They are explained below. Each
   parameter documented later specifies its type explicitly.
   
string

   Specify a string parameter value with no special syntax:
parameter = my value

integer

   Specify an integer parameter value with no special syntax:
parameter = 4150

boolean

   A boolean parameter is true or false; you can specify its value with
   the (case-insensitive) words "true" and "false". The values "yes",
   "on" and 1 are accepted as equivalent to "true", while values "no",
   "off" and 0 are accepted as equivalent to "false". Some examples:
parameter = True
parameter = false
parameter = NO
parameter = 1

tuple of quoted strings

   A tuple of quoted strings is essentially a list of strings, with each
   string surrounded by matching double- or single-quote characters to
   indicate where it begins and ends. The list must be surrounded by
   open- and close-parenthesis characters. A tuple may have to be a
   specific number of strings; for instance, a "2-tuple" must consist of
   two quoted strings, while a "4-tuple" must have exactly four. In most
   cases, the number of strings is not required to be a specific number,
   and it will not be specified in this fashion.
   
   In general, a tuple of quoted strings parameter values should look
   like this:
parameter = ('first string', 'second string',
    "third string that contains a ' character")

   However, tuples of 0 or 1 strings require special treatment. The empty
   tuple is specified with just the open- and close-parenthesis
   characters:
parameter = ()

   A tuple containing a single quoted string requires a comma to indicate
   it is a tuple:
parameter = ("single string", )

tuple of integers

   This is very similar to a tuple of quoted strings, above, minus the
   quotes. Some examples:
parameter = (1, 2, 3, 4, 5)
parameter = (37, )
parameter = ()

tuple of 2-tuples

   This is a tuple of items, each of which is a 2-tuple of quoted
   strings. You can think of this as a list of pairs of quoted strings.
# Three pairs
parameter = (
    ("first-a", "first-b"),
    ("second-a", "second-b"),
    ("third-a", "third-b"),
    )
# One pair
parameter = (
    ("lone-a", "lone-b"),
    )

Creating the [retriever] section

   The retriever section of the rc file tells getmail what mail account
   to retrieve mail from, and how to access that account. Begin with the
   section header line as follows:
[retriever]

   Then, include a type string parameter to tell getmail what type of
   mail retriever to use to retrieve mail from this account. The possible
   values are:
     * SimplePOP3Retriever -- for single-user POP3 mail accounts.
     * BrokenUIDLPOP3Retriever -- for broken POP3 servers that do not
       support the UIDL command, or which do not uniquely identify
       messages; this provides basic support for single-user POP3 mail
       accounts on such servers.
     * SimpleIMAPRetriever -- for single-user IMAP mail accounts.
     * SimplePOP3SSLRetriever -- same as SimplePOP3Retriever, but uses
       SSL encryption.
     * SimpleIMAPSSLRetriever -- same as SimpleIMAPRetriever, but uses
       SSL encryption.
     * MultidropPOP3Retriever -- for domain mailbox (multidrop) POP3 mail
       accounts.
     * MultidropPOP3SSLRetriever -- same as MultidropPOP3Retriever, but
       uses SSL encryption.
     * MultidropSDPSRetriever -- for domain mailbox SDPS mail accounts,
       as provided by the UK ISP Demon.
     * MultidropIMAPRetriever -- for domain mailbox (multidrop) IMAP mail
       accounts.
     * MultidropIMAPSSLRetriever -- same as MultidropIMAPRetriever, but
       uses SSL encryption.
       
What is a "multidrop" mailbox? How do I know if I have one?

   Some ISPs, mailhosts, and other service providers provide a mail
   service they refer to as a "domain mailbox" or "multidrop mailbox".
   This is where they register a domain for you, and mail addressed to
   any local-part in that domain ends up in a single mailbox accessible
   via POP3, with the message envelope (envelope sender address and
   envelope recipient address) recorded properly in the message header,
   so that it can be re-constructed after you retrieve the messages with
   POP3 or IMAP. The primary benefit of this is that you can run your own
   MTA (qmail, Postfix, sendmail, Exchange, etc.) for your domain without
   having to have an SMTP daemon listening at a static IP address.
   
   Unfortunately, a lot of what is advertised and sold as multidrop
   service really isn't. In many cases, the envelope recipient address of
   the message is not properly recorded, so the envelope information is
   lost and cannot be reconstructed. If the envelope isn't properly
   preserved, it isn't a domain mailbox, and you therefore can't use a
   multidrop retriever with that mailbox.
   
   To determine if you have a multidrop mailbox, check the following
   list: if any of these items are not true, you do not have a multidrop
   mailbox.
     * the mailbox must receive one copy of the message for each envelope
       recipient in the domain; if the message was addressed to three
       local-parts in the domain, the mailbox must receive three separate
       copies of the message.
     * the envelope sender address must be recorded in a header field
       named Return-Path at the top of the message. If the message
       (incorrectly) already contained such a header field, it must be
       deleted before the envelope sender address is recorded.
     * the envelope recipient address must be recorded in a new header
       field. These may be named various things, but are commonly
       Delivered-To, X-Envelope-To, and similar values. In the case of
       messages which had multiple recipients in the domain, this must be
       a single address, reflecting the particular recipient of this copy
       of the message. Note that this field (and the envelope recipient
       address) are not related to informational header fields created by
       the originating MUA, like To or cc.
       
   If you're not sure whether you have a multidrop mailbox, you probably
   don't. You probably want to use SimplePOP3Retriever (for POP3 mail
   accounts) or SimpleIMAPRetriever (for IMAP mail accounts) retrievers.
   
   Specify the mail account type with one of the above values, like this:
type = typename

   Then, include lines for any parameters and their values which are
   required by the retriever. The parameters and their types are
   documented below.
   
Common retriever parameters

   All retriever types take several common required parameters:
     * server (string) -- the name or IP address of the server to
       retrieve mail from
     * username (string) -- username to provide when logging in to the
       mail server
       
   All retriever types also take several optional parameters:
     * port (integer) -- the TCP port number to connect to. If not
       provided, the default is a port appropriate for the protocol (110
       for POP3, etc.)
     * password (string) -- password to use when logging in to the mail
       server. If not provided, getmail will prompt you to enter the
       password when run.
       
SimplePOP3Retriever

   The SimplePOP3Retriever class takes the common retriever parameters
   above, plus the following optional parameters:
     * use_apop (boolean) -- if set to True, getmail will use APOP-style
       authentication to log in to the server instead of normal USER/PASS
       authentication. This is not supported by many POP3 servers. The
       default is False.
     * timeout (integer) -- how long (in seconds) to wait for socket
       operations to complete before considering them failed. If not
       specified, the default is 180 seconds. You may need to increase
       this value in particularly poor networking conditions.
       
BrokenUIDLPOP3Retriever

   This retriever class is intended only for use with broken POP3 servers
   that either do not implement the UIDL command, or which do not
   properly assign unique identifiers to messages (preventing getmail
   from determining which messages it has seen before). It will identify
   every message in the mailbox as a new message, and therefore if you
   use this retriever class and opt not to delete messages after
   retrieval, it will retrieve those messages again the next time getmail
   is run. Use this retriever class only if your mailbox is hosted on
   such a broken POP3 server, and the server does not provide another
   means of getmail accessing it (i.e., IMAP).
   
   The BrokenUIDLPOP3Retriever class takes the common retriever
   parameters above, plus the following optional parameters:
     * use_apop (boolean) -- see SimplePOP3Retriever for definition.
     * timeout (integer) -- see SimplePOP3Retriever for definition.
       
SimpleIMAPRetriever

   The SimpleIMAPRetriever class takes the common retriever parameters
   above, plus the following optional parameters:
     * timeout (integer) -- see SimplePOP3Retriever for definition.
     * mailboxes (tuple of quoted strings) -- a list of mailbox paths to
       retrieve mail from, expressed as a Python tuple. If not specified,
       the default is to retrieve mail from the mail folder named INBOX.
       You might want to retrieve messages from several different mail
       folders, using a configuration like this:
mailboxes = ("INBOX", "INBOX.spam",
    "mailing-lists.model-railroading")

     * move_on_delete (string) -- if set, messages are moved to the named
       mail folder before being deleted from their original location.
       Note that if you configure getmail not to delete retrieved
       messages (the default behaviour), they will not be moved at all.
       
SimplePOP3SSLRetriever

   The SimplePOP3SSLRetriever class takes the common retriever parameters
   above, plus the following optional parameters:
     * use_apop (boolean) -- see SimplePOP3Retriever for definition.
     * keyfile (string) -- use the specified PEM-formatted key file in
       the SSL negotiation. Note that no certificate or key validation is
       done.
     * certfile (string) -- use the specified PEM-formatted certificate
       file in the SSL negotiation. Note that no certificate or key
       validation is done.
       
SimpleIMAPSSLRetriever

   The SimpleIMAPSSLRetriever class takes the common retriever parameters
   above, plus the following optional parameters:
     * mailboxes (tuple of quoted strings) -- see SimpleIMAPRetriever for
       definition.
     * move_on_delete (string) -- see SimpleIMAPRetriever for definition.
     * keyfile (string) -- see SimplePOP3SSLRetriever for definition.
     * certfile (string) -- see SimplePOP3SSLRetriever for definition.
       
MultidropPOP3Retriever

   The MultidropPOP3Retriever class takes the common retriever parameters
   above, plus the following required parameter:
     * envelope_recipient (string) -- the name and position of the header
       field which records the envelope recipient address. This is set to
       a value of the form field_name : field_position . The first
       (topmost) Delivered-To: header field would be specified as:
envelope_recipient = delivered-to:1

   The MultidropPOP3Retriever also takes the following optional
   parameters:
     * use_apop (boolean) -- see SimplePOP3Retriever for definition.
     * timeout (integer) -- see SimplePOP3Retriever for definition.
       
MultidropPOP3SSLRetriever

   The MultidropPOP3SSLRetriever class takes the common retriever
   parameters above, plus the following required parameter:
     * envelope_recipient (string) -- see MultidropPOP3Retriever for
       definition.
       
   The MultidropPOP3SSLRetriever class alo takes the following optional
   parameters:
     * use_apop (boolean) -- see SimplePOP3Retriever for definition.
     * keyfile (string) -- see SimplePOP3SSLRetriever for definition.
     * certfile (string) -- see SimplePOP3SSLRetriever for definition.
       
MultidropSDPSRetriever

   The MultidropSDPSRetriever class takes the common retriever parameters
   above, plus the following optional parameters:
     * timeout (integer) -- see SimplePOP3Retriever for definition.
       
MultidropIMAPRetriever

   The MultidropIMAPRetriever class takes the common retriever parameters
   above, plus the following required parameter:
     * envelope_recipient (string) -- see MultidropPOP3Retriever for
       definition.
       
   The MultidropIMAPRetriever class also takes the following optional
   parameters:
     * timeout (integer) -- see SimplePOP3Retriever for definition.
     * mailboxes (tuple of quoted strings) -- see SimpleIMAPRetriever for
       definition.
     * move_on_delete (string) -- see SimpleIMAPRetriever for definition.
       
MultidropIMAPSSLRetriever

   The MultidropIMAPSSLRetriever class takes the common retriever
   parameters above, plus the following required parameter:
     * envelope_recipient (string) -- see MultidropPOP3Retriever for
       definition.
       
   The MultidropIMAPSSLRetriever class also takes following optional
   parameters:
     * mailboxes (tuple of quoted strings) -- see SimpleIMAPRetriever for
       definition.
     * move_on_delete (string) -- see SimpleIMAPRetriever for definition.
     * keyfile (string) -- see SimplePOP3SSLRetriever for definition.
     * certfile (string) -- see SimplePOP3SSLRetriever for definition.
       
Retriever examples

   A typical POP3 mail account (the basic kind of mailbox provided by
   most internet service providers (ISPs)) would use a retriever
   configuration like this:
[retriever]
type = SimplePOP3Retriever
server = popmail.isp.example.net
username = account_name
password = my_mail_password

   If your ISP provides POP3 access on a non-standard port number, you
   would need to include the port parameter:
[retriever]
type = SimplePOP3Retriever
server = popmail.isp.example.net
port = 8110
username = account_name
password = my_mail_password

   If your ISP provides POP3-over-SSL and you wanted to use that, your
   retriever configuration might look like this:
[retriever]
type = SimplePOP3SSLRetriever
server = popmail.isp.example.net
username = account_name
password = my_mail_password

   If you have an IMAP mail account and want to retrieve messages from
   several mail folders under that account, and you want to move messages
   to a special folder when deleting them, you would use a retriever
   configuration like this:
[retriever]
type = SimpleIMAPRetriever
server = imapmail.isp.example.net
username = account_name
password = my_mail_password
mailboxes = ("INBOX", "lists.unix", "lists.getmail")
move_on_delete = mail.deleted

   If you are retrieving your company's mail from a domain POP3 mailbox
   for delivery to multiple local users, you might use a retriever
   configuration like this:
[retriever]
type = MultidropPOP3Retriever
server = imapmail.isp.example.net
username = account_name
password = company_maildrop_password
envelope_recipient = delivered-to:1

Creating the [destination] section

   The destination section of the rc file tells getmail what to do with
   retrieved messages. Begin with the section header line as follows:
[destination]

   Then, include a type string parameter to tell getmail what type of
   mail destination this is. The possible values are:
     * Maildir -- deliver all messages to a local qmail-style maildir
     * Mboxrd -- deliver all messages to a local mboxrd-format mbox file
       with fcntl-type locking.
     * MDA_external -- use an external message delivery agent (MDA) to
       deliver messages. Typical MDAs include maildrop, procmail, and
       others.
     * MultiDestination -- unconditionally deliver messages to multiple
       destinations (maildirs, mbox files, external MDAs, or other
       destinations).
     * MultiSorter -- sort messages according to the envelope recipient
       (requires a domain mailbox retriever) and deliver to a variety of
       maildirs, mbox files, external MDAs, or other destinations based
       on regular expressions matching the recipient address of each
       message. Messages not matching any of the regular expressions are
       delivered to a default "postmaster" destination.
     * MultiGuesser -- sort messages according to addresses found in the
       message's header fields and deliver to a variety of maildirs, mbox
       files, external MDAs, or other destinations based on regular
       expressions matching those addresses. Messages not matching any of
       the regular expressions are delivered to a default "postmaster"
       destination.
     * MDA_qmaillocal -- use qmail-local to deliver messages according to
       instructions in a .qmail file.
       
Maildir

   The Maildir destination delivers to a qmail-style maildir.
   
   The Maildir destination takes one required parameter:
     * path (string) -- the path to the maildir, ending in slash (/).
       This value will be expanded for leading ~ or ~USER and environment
       variables in the form $VARNAME or ${VARNAME}. You might want to
       deliver messages to a maildir named Maildir in your home
       directory; you could do this with a configuration like this:
[destination]
type = Maildir
path = ~/Maildir/

   The Maildir destination also takes one optional parameters:
     * user (string) -- on Unix-like systems, if supplied, getmail will
       change the effective UID to that of the named user before
       delivering messages to the maildir. Note that this typically
       requires root privileges. getmail will not deliver to maildirs as
       root, so this "optional" parameter is required in that situation.
       
Mboxrd

   The Mboxrd destination delivers to an mboxrd-format mbox file with
   fcntl-type file locking. The file must already exist and appear to be
   a valid mboxrd file before getmail will try to deliver to it --
   getmail will not create the file if it does not exist.
   
   You should ensure that all other programs accessing any the mbox file
   expect mboxrd-format mbox files and fcntl-type file locking; failure
   to do so can cause mbox corruption. Note that delivering to mbox files
   over NFS can be unreliable and should be avoided; this is the case
   with any MDA.
   
   The Mboxrd destination takes one required parameter:
     * path (string) -- the path to the mbox file. This value will be
       expanded for leading ~ or ~USER and environment variables in the
       form $VARNAME or ${VARNAME}. You might want to deliver messages to
       an mbox file named inbox in your home directory; you could do this
       with a configuration like this:
[destination]
type = Mboxrd
path = ~/inbox

   The Mboxrd destination also takes one optional parameters:
     * user (string) -- on Unix-like systems, if supplied, getmail will
       change the effective UID to that of the named user before
       delivering messages to the mboxrd file. Note that this typically
       requires root privileges. getmail will not deliver to mbox files
       as root, so this "optional" parameter is required in that
       situation.
       
MDA_external

   MDA_external delivers messages by running an external program (known
   as a message delivery agent, or MDA). Some typical MDAs include
   maildrop and procmail.
   
   The MDA_external destination takes one required parameter:
     * path (string) -- the path to the command to run. This value will
       be expanded for leading ~ or ~USER and environment variables in
       the form $VARNAME or ${VARNAME}.
       
   The MDA_external destination also takes several optional parameters:
     * arguments (tuple of quoted strings) -- arguments to be supplied to
       the command. The following substrings will be substituted with the
       equivalent values from the message:
          + %(sender) -- envelope return-path address
       If the message is retrieved with a multidrop retriever class, the
       message recipient (and parts of it) are also available with the
       following replacement substrings:
          + %(recipient) -- envelope recipient address
          + %(local) -- local-part of the envelope recipient address
          + %(domain) -- domain-part of the envelope recipient address
       The default value of the arguments parameter is (), so no
       arguments are supplied to the command.
     * unixfrom (boolean) -- whether to include a Unix-style mbox From_
       line at the beginning of the message supplied to the command.
       Defaults to false. Some MDAs expect such a line to be present and
       will fail to operate if it is missing.
     * user (string) -- if supplied, getmail will change the effective
       UID to that of the named user. Note that this typically requires
       root privileges.
     * group (string) -- if supplied, getmail will change the effective
       GID to that of the named group. Note that this typically requires
       root privileges.
     * allow_root_commands (boolean) -- if set, getmail will run external
       commands even if it is currently running with root privileges. The
       default is false, which causes getmail to raise an exception if it
       is asked to run an external command as root. Note that setting
       this option has serious security implications. Don't use it if you
       don't know what you're doing. I strongly recommend against running
       external processes as root.
       
   If an external MDA writes anything to stderr, getmail will consider
   the delivery to have encountered an error. getmail will leave the
   message on the server and proceed to the next message. You must
   configure any MDA you use not to emit messages to stderr except on
   errors -- please see the documentation for your MDA for details; this
   should be the default mode of operation for any sane MDA.
   
   A basic invocation of an external MDA might look like this:
[destination]
type = MDA_external
path = /path/to/mymda
arguments = ("--log-errors", )

   Something more complex might look like this:
[destination]
type = MDA_external
path = /path/to/mymda
# Switch to fred's UID and the mail group GID before delivering his mail
user = fred
group = mail
arguments = ("--strip-forbidden-attachments", "--recipient=%(recipient)")

MultiDestination

   MultiDestination doesn't do any message deliveries itself; instead, it
   lets you specify a list of one or more other destinations which it
   will pass each message to. You can use this to deliver each message to
   several different destinations.
   
   The MultiDestination destination takes one required parameter:
     * destinations (tuple of quoted strings) -- the destinations which
       the messages will be passed to. A destination is a string that
       refers to another configuration file section by name (shortcuts
       for maildirs and mboxrd files are also provided; see below), like
       this:
destinations = ('[other-destination-1]', '[other-destination-2]')

[other-destination-1]
type = Mboxrd
path = /var/spool/mail/alice
user = alice

[other-destination-2]
type = Maildir
path = /home/joe/Maildir/
user = joe
       Because Maildir and Mboxrd destinations are common, you can
       specify them directly as a shortcut if they do not require a user
       parameter. If the string (after expansion; see below) starts with
       a dot or slash and ends with a slash, it specifies the path of a
       Maildir destination, while if it starts with a dot or a slash and
       does not end with a slash, it specifies the path of a Mboxrd
       destination.
       For instance, you can deliver mail to two maildirs with the
       following:
destinations = ('~/Mail/inbox/', '~/Mail/archive/current/')
       Each destination string is first expanded for leading ~ or ~USER
       and environment variables in the form $VARNAME or ${VARNAME}.
       
   Some examples:
     * To deliver to a maildir named Maildir in the home directory of
       user jeff, when getmail is run as that user:
[destination]
type = MultiDestination
destinations = ("~jeff/Maildir/", )
     * To deliver to an mboxrd file:
[destination]
type = MultiDestination
destinations = ("/var/spool/mail/alice", )
     * To deliver with an external MDA:
[destination]
type = MultiDestination
destinations = ("[procmail-as-bob]", )

[procmail-as-bob]
type = MDA_external
path = /path/to/procmail
arguments = ('~bob/.procmailrc', '-f', '%(sender)')
user = bob
       
   Of course, the whole point of MultiDestination is to allow you to
   specify multiple destinations, like this:
[destination]
type = MultiDestination
destinations = (
    "~jeff/Mail/inbox",
    "[procmail-as-jeff]",
    "/var/mail-archive/incoming"
    )

[procmail-as-jeff]
type = MDA_external
path = /path/to/procmail
arguments = ('~jeff/.procmailrc', '-f', '%(sender)')
user = jeff

MultiSorter

   MultiSorter compares the envelope recipient address of messages
   against a list of user-supplied regular expressions and delivers the
   message to the destination (maildir, mboxrd file, or other) associated
   with any matching patterns. A message can match multiple patterns and
   therefore be delivered to multiple matching destinations. Any message
   which matches none of the patterns is delivered to a default
   destination for the postmaster.
   
   Because MultiSorter requires the envelope recipient to operate, it
   must be used with a domain mailbox retriever. If you instead want to
   do some basic message sorting based on addresses found in the message
   header (using getmail as a combination retriever and basic filtering
   MDA), see the MultiGuesser destination class below.
   
   The MultiSorter destination takes one required parameter:
     * default (string) -- the destination for messages which aren't
       matched by any of the "locals" regular expressions. The
       destination can be a maildir, mboxrd file, or other destination.
       See MultiDestination for an explanation of how the type of
       destination is interpreted from this value.
       
   The MultiSorter destination also takes one optional parameter:
     * locals (tuple of 2-tuples) -- zero or more regular expression -
       destination pairs. Messages will be delivered to each destination
       for which the envelope recipient matches the given regular
       expression. The regular expression and destination are supplied as
       two quoted strings in a tuple; locals is then a tuple of such
       pairs of strings. Destinations are specified in the same manner as
       with the "default" parameter, above.
       
   Note that if you don't understand regular expressions, you don't need
   to worry about it. In general, an email address is a regular
   expression that matches itself. The only significant times this isn't
   the case is when the address contains odd punctuation characters like
   ^, $, or [. Handy hints:
     * the regular expression . (dot) matches anything
     * matches can occur anywhere in the address. If you want to only
       match at the beginning, start your expression with the ^
       character. If you only want to match the whole address, also end
       your expression with a dollar sign $.
       
   Using regular expressions:
     * The regular expression joe@example.org matches the addresses
       joe@example.org, joe@example.org.net, and heyjoe@example.org.
     * The regular expression ^jeff@ matches the addresses
       jeff@example.org and jeff@example.net, but not
       otherjeff@example.org.
     * The regular expression sam matches the addresses sam@example.org,
       samantha@example.org, asam@example.org, and
       chris@isam.example.net.
       
   Some examples:
     *
          + Deliver mail matching jeff@example.net to ~jeff/Maildir/
          + Deliver mail matching alice@anything to ~alice/inbox
          + Deliver all other mail to ~bob/Maildir/
[destination]
type = MultiSorter
default = [bob-default]
locals = (
    ('jeff@example.net', '[jeff]'),
    ('alice@', '[alice]')
    )

[jeff]
type = Maildir
path = ~jeff/Maildir/
user = jeff

[alice]
type = Mboxrd
path = ~alice/inbox
user = alice

[bob-default]
type = Maildir
path = ~bob/Maildir/
user = bob
     *
          + Deliver mail for jeff, bob, and alice to maildirs in their
            home directories
          + Deliver copies of all messages to samantha's mail archive
          + Deliver copies of all messages to a program that logs certain
            information. This program should run as the user log, and
            command arguments should tell it to record the info to
            /var/log/mail/info
[destination]
type = MultiSorter
default = doesn't matter, this won't be used, as locals will always match
locals = (
    ('^jeff@'), '[jeff]'),
    ('^bob@'), '[bob]'),
    ('^alice@'), '[alice]'),
    ('.'), '[copies]'),
    ('.'), '[info]')
    )

[alice]
type = Maildir
path = ~alice/Maildir/
user = alice

[bob]
type = Maildir
path = ~bob/Maildir/
user = bob

[jeff]
type = Maildir
path = ~jeff/Maildir/
user = jeff

[copies]
type = Maildir
path = ~samantha/Mail/archive/copies/
user = samantha

[info]
type = MDA_external
path = /path/to/infologger
arguments = ('--log=/var/log/mail/info', '--sender=%(sender)', '--recipient=%(r
ecipient))
user = log
       
MultiGuesser

   MultiGuesser compares addresses found in the message header against a
   list of user-supplied regular expressions and delivers the message to
   the destination (maildir, mboxrd file, or other) associated with any
   matching patterns. A message can match multiple patterns and therefore
   be delivered to multiple matching destinations. Any message which
   matches none of the patterns is delivered to a default destination for
   the postmaster. In this fashion, you can do basic mail filtering and
   sorting with getmail without using an external filtering message
   delivery agent (MDA) (such as maildrop or procmail).
   
   MultiGuesser is similar to MultiSorter, except that it does not
   operate on the envelope recipient address, and therefore does not
   require a domain mailbox retriever. Because it is "guessing" at the
   intended recipient of the message based on the contents of the message
   header, it is fallible -- for instance, the address of a recipient of
   a mailing list message may not appear in the header of the message at
   all. If your locals regular expression patterns are only looking for
   that address, MultiGuesser will then have to deliver it to the
   destination specified as the default recipient.
   
   This functionality is very similar to the guessing functionality of
   getmail version 2, which was removed in version 3. MultiGuesser
   extracts a list of addresses from the message header like this:
    1. it looks for addresses in any Delivered-To: header fields.
    2. if no addresses have been found, it looks for addresses in any
       Envelope-To: header fields.
    3. if no addresses have been found, it looks for addresses in any
       X-Envelope-To: header fields.
    4. if no addresses have been found, it looks for addresses in any
       Apparently-To: header fields.
    5. if no addresses have been found, it looks for addresses in any
       Resent-to: or Resent-cc: header fields (or Resent-bcc:, which
       shouldn't be present).
    6. if no addresses have been found, it looks for addresses in any To:
       or cc: header fields (or bcc:, which shouldn't be present).
       
   The MultiGuesser destination takes one required parameter:
     * default (string) -- see MultiSorter for definition.
       
   The MultiGuesser destination also takes one optional parameter:
     * locals (tuple of 2-tuples) -- see MultiSorter for definition.
       
   Examples:
   
   If you have a simple POP3 account (i.e. it's not a multidrop mailbox)
   and you want to deliver your personal mail to your regular maildir,
   but deliver mail from a couple of mailing lists (identified by the
   list address appearing in the message header) to separate maildirs,
   you could use a MultiGuesser configuration like this:
[destination]
type = MultiGuesser
default = ~/Maildir/
locals = (
    ("list-address-1@list-domain-1", "~/Mail/mailing-lists/list-1/"),
    ("list-address-2@list-domain-2", "~/Mail/mailing-lists/list-2/"),
    )

   See MultiSorter above for other examples of getmail rc usage; the only
   difference is the type parameter specifying the MultiGuesser
   destination.
   
MDA_qmaillocal

   MDA_qmaillocal delivers messages by running the qmail-local program as
   an external MDA. qmail-local uses .qmail files to tell it what to do
   with messages. If you're not already familiar with qmail, you don't
   need to use this destination class.
   
   The MDA_qmaillocal destination takes several optional parameters:
     * qmaillocal (string) -- path to the qmail-local program. The
       default value is /var/qmail/bin/qmail-local.
     * user (string) -- supplied to qmail-local, and also tells getmail
       to change the current effective UID to that of the named user
       before running qmail-local. Note that this typically requires root
       privileges. The default value is the account name of the current
       effective UID.
     * group (string) -- if supplied, getmail will change the effective
       GID to that of the named group before running qmail-local. Note
       that this typically requires root privileges.
     * homedir (string) -- supplied to qmail-local. The default value is
       the home directory of the account with the current effective UID.
     * localdomain (string) -- supplied to qmail-local as its domain
       argument. The default value is the fully-qualified domain name of
       the local host.
     * defaultdelivery (string) -- supplied to qmail-local as its
       defaultdelivery argument. The default value is ./Maildir/.
     * conf-break (string) -- supplied to qmail-local as its dash
       argument. The default value is -.
     * localpart_translate (2-tuple of quoted strings) -- if supplied,
       the recipient address of the message (which is used to construct
       the local argument (among others) to qmail-local) will have any
       leading instance of the first string replaced with the second
       string. This can be used to remap recipient addresses, trim
       extraneous prefixes (such as the qmail virtualdomain prepend
       value), or perform other tasks. The default value is ('', '')
       (i.e., no translation).
     * strip_delivered_to (boolean) -- if set, Delivered-To: header
       fields will be removed from the message before handing it to
       qmail-local. This may be necessary to prevent qmail-local falsely
       detecting a looping message if (for instance) the system
       retrieving messages otherwise believes it has the same domain name
       as the retrieval server. Inappropriate use of this option may
       cause message loops. The default value is False.
     * allow_root_commands (boolean) -- if set, getmail will run
       qmail-local even if it is currently running with root privileges.
       The default is false, which causes getmail to raise an exception
       if it is asked to run an external command as root. Note that
       setting this option has serious security implications. Don't use
       it if you don't know what you're doing. I strongly recommend
       against running external processes as root.
       
   A basic invocation of qmail-local might look like this:
[destination]
type = MDA_qmaillocal
user = joyce

   Something more complex might look like this:
[destination]
type = MDA_qmaillocal
user = joyce
# The mail domain isn't the normal FQDN of the server running getmail
localdomain = host.example.net
# Trim the server's virtualdomain prepend value from message recipient before
# sending it to qmail-local
localpart_translate = ('mailhostaccount-', '')

Creating the [options] section

   The optional options section of the rc file can be used to alter
   getmail's default behaviour. The parameters supported in this section
   are as follows:
     * verbose (integer) -- controls getmail's verbosity. If set to 2,
       getmail prints messages about each of its actions. If set to 1, it
       prints messages about retrieving and deleting messages (only). If
       set to 0, getmail will only print warnings and errors. Default: 1.
     * read_all (boolean) -- if set, getmail retrieves all available
       messages. If unset, getmail only retrieves messages it has not
       seen before. Default: True.
     * delete (boolean) -- if set, getmail will delete messages after
       retrieving and successfully delivering them. If unset, getmail
       will leave messages on the server after retrieving them. Default:
       False.
     * delete_after (integer) -- if set, getmail will delete messages
       this number of days after first seeing them, if they have been
       retrieved and delivered. This, in effect, leaves messages on the
       server for a configurable number of days after retrieving them.
       Note that the delete parameter has higher priority; if both are
       set, the messages will be deleted immediately. Default: 0, which
       means not to enable this feature.
     * max_message_size (integer) -- if set, getmail will not retrieve
       messages larger than this number of bytes. Default: 0, which means
       not to enable this feature.
     * max_messages_per_session (integer) -- if set, getmail will process
       a maximum of this number of messages before closing the session
       with the server. This can be useful if your network or the server
       is particuarly unreliable. Default: 0, which means not to enable
       this feature.
     * delivered_to (boolean) -- if set, getmail adds a Delivered-To:
       header field to the message. If unset, it will not do so. Default:
       True. Note that this field will contain the envelope recipient of
       the message if the retriever in use is a multidrop retriever;
       otherwise it will contain the string "unknown".
     * received (boolean) -- if set, getmail adds a Received: header
       field to the message. If unset, it will not do so. Default: True.
     * message_log (string) -- if set, getmail will record a log of its
       actions to the named file. The value will be expanded for leading
       ~ or ~USER and environment variables in the form $VARNAME or
       ${VARNAME}. Default: '' (the empty string), which means not to
       enable this feature.
     * message_log_syslog (boolean) -- if set, getmail will record a log
       of its actions using the system logger. Note that syslog is
       inherently unreliable and can lose log messages. Default: False.
       
   Most users will want to either enable the delete option (to delete
   mail after retrieving it), or disable the read_all option (to only
   retrieve previously-unread mail).
   
   The verbose, read_all, and delete parameters can be overridden at run
   time with commandline options.
   
[options] example

   To configure getmail to operate quietly, to retrieve only new mail, to
   delete messages after retrieving them, and to log its actions to a
   file, you could provide the following in your getmail rc file(s):
[options]
verbose = 0
read_all = false
delete = true
message_log = ~/.getmail/log

Creating the [filter-something] sections

   The filter-something section(s) of the rc file (which are not
   required) tell getmail to process messages in some way after
   retrieving them, but before delivering them to your destinations.
   Filters can tell getmail to drop a message (i.e. not deliver it at
   all), add information to the message header (i.e. for a spam-
   classification system or similar), or modify message content (like an
   antivirus system stripping suspected MIME parts from messages).
   
   You can specify any number of filters; provide a separate rc file
   section for each, naming each of them filter-something. They will be
   run in collated order, so it's likely simplest to name them like this:
     * [filter-1]
     * [filter-2]
     * [filter-3]
       
   Begin with the section header line as follows:
[filter-something]

   Then, include a type string parameter to tell getmail what type of
   filter. The possible values are:
     * Filter_classifier -- run the message through an external program,
       and insert the output of the program into
       X-getmail-filter-classifier: header fields in the message.
       Messages can be dropped by having the filter return specific exit
       codes.
     * Filter_external -- supply the message to an external program,
       which can then modify the message in any fashion. The program must
       print the modified message to stdout. getmail reads the modified
       message from the program in this fasion before proceeding to the
       next filter or destination. Messages can be dropped by having the
       filter return specific exit codes.
     * Filter_TMDA -- run the message through the tmda-filter program for
       use with the Tagged Message Delivery Agent (TMDA) package. If
       tmda-filter returns 0, the message will be passed to the next
       filter (or destination). If it returns 99, the message will be
       dropped, and TMDA is responsible for sending a challenge message,
       queuing the original, etc., as with normal TMDA operation in a
       .qmail, .courier, or .forward file.
       
   If a filter writes anything to stderr, getmail will consider the
   delivery to have encountered an error. getmail will leave the message
   on the server and proceed to the next message. You must configure any
   filter you use not to emit messages to stderr except on errors --
   please see the documentation for your filter program for details; this
   should be the default mode of operation for any sane filter.
   
Filter_classifier

   Filter_classifier runs the message through an external program,
   placing the output of that program into X-getmail-filter-classifier:
   header fields. It can also cause messages to be dropped by exiting
   with a return code listed in the exitcodes_drop parameter.
   
   Filter_classifier has one required parameter:
     * path (string) -- the path to the command to run. This value will
       be expanded for leading ~ or ~USER and environment variables in
       the form $VARNAME or ${VARNAME}.
       
   In addition, Filter_classifier takes the following optional
   parameters:
     * arguments (tuple of quoted strings) -- arguments to be supplied to
       the command. The following substrings will be substituted with the
       equivalent values from the message:
          + %(sender) -- envelope return-path address
       If the message is retrieved with a multidrop retriever class, the
       message recipient (and parts of it) are also available with the
       following replacement substrings:
          + %(recipient) -- envelope recipient address
          + %(local) -- local-part of the envelope recipient address
          + %(domain) -- domain-part of the envelope recipient address
       The default value of the arguments parameter is (), so no
       arguments are supplied to the command.
     * unixfrom (boolean) -- whether to include a Unix-style mbox From_
       line at the beginning of the message supplied to the command.
       Default: False.
     * user (string) -- if supplied, getmail will change the effective
       UID to that of the named user. Note that this typically requires
       root privileges.
     * group (string) -- if supplied, getmail will change the effective
       GID to that of the named group. Note that this typically requires
       root privileges.
     * allow_root_commands (boolean) -- if set, getmail will run external
       commands even if it is currently running with root privileges. The
       default is false, which causes getmail to raise an exception if it
       is asked to run an external command as root. Note that setting
       this option has serious security implications. Don't use it if you
       don't know what you're doing. I strongly recommend against running
       external processes as root.
     * exitcodes_drop (tuple of integers) -- if the filter returns an
       exit code in this list, the message will be dropped. The default
       is (99, 100).
     * exitcodes_keep (tuple of integers) -- if the filter returns an
       exit code other than those in exitcodes_drop and exitcodes_keep,
       getmail assumes the filter encountered an error. getmail will then
       not proceed, so that the message is not lost. The default is (0,
       ).
       
Filter_external

   Filter_external runs the message through an external program, and
   replaces the message with the output of that program, allowing the
   filter to make arbitrary changes to messages. It can also cause
   messages to be dropped by exiting with a return code listed in the
   exitcodes_drop parameter.
   
   Filter_external has one required parameter:
     * path (string) -- see Filter_classifier for definition.
       
   In addition, Filter_external takes the following optional parameters:
     * arguments (tuple of quoted strings) -- see Filter_classifier for
       definition.
     * unixfrom (boolean) -- see Filter_classifier for definition.
     * user (string) -- see Filter_classifier for definition.
     * group (string) -- see Filter_classifier for definition.
     * allow_root_commands (boolean) -- see Filter_classifier for
       definition.
     * exitcodes_drop (tuple of integers) -- see Filter_classifier for
       definition.
     * exitcodes_keep (tuple of integers) -- see Filter_classifier for
       definition.
       
Filter_TMDA

   Filter_external runs the message through the external program
   tmda-filter, allowing the use of the Tagged Message Delivery Agent
   (TMDA) package. As TMDA relies on the message envelope, this filter
   requires the use of a multidrop retriever class to function. It sets
   the three environment variables SENDER, RECIPIENT, and EXT prior to
   running tmda-filter.
   
   I've tested this filter, and it Works For Me(TM), but I'm not a
   regular TMDA user. I would appreciate any feedback about its use from
   TMDA users.
   
   Filter_TMDA has no required parameters. It has the following optional
   parameters:
     * path (string) -- the path to the tmda-filter binary. Default:
       /usr/local/bin/tmda-filter. This value will be expanded for
       leading ~ or ~USER and environment variables in the form $VARNAME
       or ${VARNAME}.
     * user (string) -- see Filter_classifier for definition.
     * group (string) -- see Filter_classifier for definition.
     * allow_root_commands (boolean) -- see Filter_classifier for
       definition.
     * conf-break (string) -- this value will be used to split the
       local-part of the envelope recipient address to determine the
       value of the EXT environment variable. For example, if the
       envelope sender address is sender-something@host.example.org, and
       the envelope recipient address is user-ext-ext2@host.example.net,
       and conf-break is set to -, getmail will set the environment
       variables SENDER to "sender-something@host.example.org", RECIPIENT
       to "user-ext-ext2@host.example.net", and EXT to "ext-ext2".
       Default: "-".
       
[filter-something] examples

   You might filter spam messages in your MUA based on information added
   to the message header by a spam-classification program. You could have
   that information added to the message header with a filter
   configuration like this:
[filter-3]
type = Filter_classifier
path = /path/to/my-classifier
arguments = ('--message-from-stdin', '--report-to-stdout')
user = nobody

   You might use a program to prevent users from accidentally destroying
   their data by stripping suspected attachments from messages. You could
   have that information added to the message header with a filter
   configuration like this:
[filter-3]
type = Filter_external
path = /path/to/my-mime-filter
arguments = ('--message-from-stdin', '--remove-all-but-attachment-types=text/pl
ain,text/rfc822')
user = nobody

   You might use TMDA to challenge messages from unknown senders. If the
   default parameters are fine for your configuration, this is as simple
   as:
[filter-3]
type = Filter_TMDA

getmail rc file examples

   Several examples of different getmail rc configuration are available
   in the included file getmailrc-examples.
   
Running getmail

   To use getmail, simply run the script getmail, which is typically
   installed in /usr/local/bin/ by default. getmail will read the default
   getmail rc file (getmailrc) from the default configuration/data
   directory (~/.getmail/) and begin operating.
   
   You can modify this behaviour by supplying commandline options to
   getmail.
   
Commandline options

   getmail understands the following options:
     * --version -- show getmail's version number and exit
     * --help or -h -- show a brief usage summary and exit
     * --getmaildir=DIR or -gDIR -- use DIR for configuration and data
       files
     * --rcfile=FILE or -rFILE -- read getmail rc file FILE instead of
       the default. The file path is assumed to be relative to the
       getmaildir directory unless this value starts with a slash (/).
       This option can be given multiple times to have getmail retrieve
       mail from multiple accounts.
     * --dump -- read rc files, dump configuration, and exit (debugging)
     * --trace -- print extended debugging information
       
   In addition, the following commandline options can be used to override
   any values specified in the [options] section of the getmail rc files:
     * --verbose or -v -- operate more verbosely. Can be given multiple
       times.
     * --quiet or -q -- print only warnings or errors while running
     * --delete or -d -- delete messages after retrieving
     * --dont-delete or -l -- do not delete messages after retrieving
     * --all or -a -- retrieve all messages
     * --new or -n -- retrieve only new (unseen) messages
       
   For instance, if you want to retrieve mail from two different mail
   accounts, create a getmail rc file for each of them (named, say,
   getmailrc-account1 and getmailrc-account2) and put them in ~/.getmail/
   . Then run getmail as follows:
$ getmail --rcfile getmailrc-account1 --rcfile getmailrc-account2

   If those files were located in a directory other than the default, and
   you wanted to use that directory for storing the data files as well,
   you could run getmail as follows:
$ getmail --getmaildir /path/to/otherdir --rcfile getmailrc-account1 --rcfile g
etmailrc-account2

Using getmail as an MDA

   getmail includes helper scripts which allow you to use it to deliver
   mail from other programs to maildirs or mboxrd files.
   
Using the getmail_maildir MDA

   The getmail_maildir script can be used as an MDA from other programs
   to deliver mail to maildirs. It reads the mail message from stdin, and
   delivers it to a maildir path provided as an argument on the
   commandline. This path must (after expansion by the shell, if
   applicable) start with a dot or slash and end with a slash.
   
   getmail_maildir uses the contents of the SENDER environment variable
   to construct a Return-Path: header field and the contents of the
   RECIPIENT environment variable to construct a Delivered-To: header
   field at the top of the message.
   
   getmail_maildir also accepts the options --verbose or -v which tell it
   to print a status message on success. The default is to operate
   silently unless an error occurs.
   
Example

   You could deliver a message to a maildir named Maildir located in your
   home directory by running the following command with the message on
   stdin:
$ getmail_maildir $HOME/Maildir/

Using the getmail_mbox MDA

   The getmail_mbox script can be used as an MDA from other programs to
   deliver mail to mboxrd-format mbox files. It reads the mail message
   from stdin, and delivers it to an mbox path provided as an argument on
   the commandline. This path must (after expansion by the shell, if
   applicable) start with a dot or slash and not end with a slash.
   
   getmail_maildir uses the contents of the SENDER environment variable
   to construct a Return-Path: header field and mbox From_ line and the
   contents of the RECIPIENT environment variable to construct a
   Delivered-To: header field at the top of the message.
   
   getmail_mbox also accepts the options --verbose or -v which tell it to
   print a status message on success. The default is to operate silently
   unless an error occurs.
   
Example

   You could deliver a message to an mboxrd-format mbox file named inbox
   located in a directory named mail in your home directory by running
   the following command with the message on stdin:
$ getmail_mbox $HOME/mail/inbox
