                             getmail Documentation

   This is the formal documentation for getmail. If your question is not
   answered here or in the Frequently Asked Questions, please subscribe to
   the mailing list.

About this document

   The official location of this document is
   http://www.qcc.ca/~charlesc/software/getmail-2.0/docs.html. For easy
   navigation, all headings in the HTML version of this document are links to
   their parent heading.

User-contributed documentation

   Fredrik Steen, maintainer of the Debian package for getmail, has written a
   man page for getmail. It is available at
   http://people.debian.org/~stone/getmail/manpage/getmail.1.

                               Table of Contents

   1. Installing getmail
   2. Configuring getmail
          * Configuration file
          * POP3 account types
               * Regular POP3 mailboxes
               * POP3 domain mailboxes
          * Message delivery targets
   3. getmailrc directives
   4. Running getmail
   5. Commandline options

Installing getmail

   1. Download getmail.
   2. Unpack the tarball:

 tar xzf getmail-version.tar.gz

   3. Copy the contents to a suitable location:

 mkdir /usr/lib/getmail
 cp -a getmail-version/* /usr/lib/getmail/
            

       You can install getmail in your home directory or elsewhere if you
       prefer.
   4. Copy the getmail helper script to a location in your PATH, and ensure
       it is executable:

 cp -a getmail-version/getmail /usr/bin/
 chmod 755 /usr/bin/getmail

       If you used an installation path other than that in step 3 above, edit
       the value of GETMAILDIR in this file.

Configuring getmail

   1. Create a getmail configuration/data directory in your home directory:

 mkdir ~/.getmail

       You can use another path or directory name, but getmail assumes this
       name by default. If you choose something different, you will need to
       specify its name on the getmail command line with the --getmaildir
       option.
   2. Create a configuration file named getmailrc in the directory you
       created in step 1 above. You can use another file name or path, but
       getmail assumes this name by default. If you choose something
       different, you will need to specify its name on the getmail command
       line with the --rcfile option.

       See the section Configuration file below for details.

  Configuration file

   A getmail configuration file (typically named getmailrc, and located in
   $HOME/.getmail/) looks similar to an MS-Windows .INI file. For security
   reasons, your getmailrc file must not be group- or world-writable. getmail
   will refuse to run if it finds your getmailrc file is writable by others.

   The file is broken into sections; the special section "[default]" supplies
   default values for various options. Each additional section describes one
   POP3 mailbox you wish to retrieve mail from, and how to deliver mail to
   local users.

   Each section starts with a label enclosed in square brackets:

 [section name]

   This is then followed by lines in the format of name = value:

 option_name = option_value

   Option values that contain a percent sign (%) must be escaped with another
   percent sign. For instance, this:

 user = jeffj%domain.tld

   is not valid. Instead, you would specify it like this:

 user = jeffj%%domain.tld

   getmail ignores whitespace surrounding the "=" sign. The following lines
   are equivalent:

 account = joe.bloggs
 account=joe.bloggs
 account=   joe.bloggs

   The "#" symbol starts a comment; everything after it on the line is
   ignored. You can use this to keep notes to yourself in your getmailrc
   file:

 account = jeff.friesen:mymail.example.net         # This virtual host needs ':' instead of '@'

   Option values containing whitespace must be quoted with either single or
   double quotes:

 password = "long password containing spaces"
 password = 'long password containing spaces'

   Option values containing single or double quote characters can be quoted
   with the other character:

 password = "this is a more 'secure' password"
 password = 'joe "bloggy" bloggs'

   To un-set an option taking a string value, set it to the empty string:

 message_log = ""         # Previously set to /var/log/getmail; turn it off for this account

   A getmail configuration file must begin with a [default] section. Options
   which are set in this section will serve as default values for the rest of
   the sections in the file; they can be overridden for a later section by
   specifying the same option with a different value. An example [default]
   section might look like this:

 [default]

 verbose = 1                     # Print status messages to stdout
 timeout = 120                   # We're on a good network; time out POP3 connections after 120 seconds
 readall = 0                     # Only retrieve new messages
 delete = 0                      # But don't delete them from the server when we're done
 message_log = /var/log/getmail  # Log retrieval and delivery here

   Other sections in a getmail configuration file represent POP3 accounts to
   retrieve mail from, one per account. The section name is unimportant, but
   must be unique. An example account section might look like this:

 [Home ISP account]
 server = mailhost.isp.tld
 username = brenda.bjorn
 password = "my mail password"
 postmaster = ~brendab/Maildir/  # Deliver all mail to the Maildir in my home directory

   When getmail tries to determine the value of an option, it looks at the
   following, in order:
   1. Options specified on the command line
   2. Options specified in an account section of the getmail configuration
       file
   3. Options specified in the [default] section of the getmail
       configuration file
   4. getmail's built-in default value
   The first match determines getmail's behaviour. To demonstrate, we'll
   examine a fairly complex getmailrc:

 [default]
 verbose = 0
 timeout = 120
 readall = 1
 delete = 1
 message_log = ""
 postmaster = ~magnus/Mail/postmaster/

 [Home account]
 server = pop.mail.example.com
 port = 8110
 timeout = 600
 account = magnus.leitner
 password = "F45 82dLa"
 readall = 0
 delete = 0
 postmaster = ~magnus/Mail/personal/
 verbose = 1

 [Work account 1]
 server = vhost.example.net
 account = smallcompany
 password = "trailing_spaces  "
 local = info@company.net,~bob/Mail/info
 local = sales@company.net,~bob/Mail/sales
 local = bob.jackson@company.net,~bob/Mail/mbox
 local = marcia.smith@company.net,~marcia/Mail/mbox
 local = magnus.leitner@company.net,~magnus/Mail/inbox/

 [Work account 2]
 server = mail.company.tld
 account = othercompany
 password = FHj873k34l
 local = info@othercompany.net,~magnus/Mail/info/
 local = sales@othercompany.net,~magnus/Mail/sales/
 local = magnus.leitner@company.net,~magnus/Mail/inbox/

   In this example, getmail will:
     * operate in quiet mode when retrieving mail from Work account 1 and
       Work account 2, but verbose mode when retrieving mail from Home
       account.
     * Retrieve all mail from the two work accounts, deleting it from the
       server after retrieval. From the home account, it will retrieve only
       new mail, and will leave it on the server after delivery.
     * All mail from work account 2 is being delivered to user Magnus;
       however, local directives with patterns are being used to sort mail
       into various sub-folders.
     * The POP3 servers for the two work accounts run on the default POP3
       port (110). The home account server is running on port 8110.
   There are other values that differ between the configurations as well. For
   details on the configuration directives that can be used in a getmail
   configuration file, see the section on Configuration Directives.

  POP3 Account types

   There are two different types of POP3 email accounts: regular mailboxes,
   and domain mailboxes.

    Regular mailbox

   This is a typical POP3 mailbox provided by an ISP for a single user. It
   receives mail addressed to a single user (say,
   shannon.fotheringham@aqua.myisp.tld). For this type of account, the
   minimum configuration would be something like this:

 [My Aqua Account]
 server = mailhost.aqua.myisp.tld
 username = shannon.fotheringham
 postmaster = ~shannonf/Maildir/

   This postmaster directive tells getmail to deliver all mail to Shannon's
   Maildir. Since a password was not configured, getmail will prompt the user
   for it when run.

    Domain mailbox

   This type of POP3 account is typically provided by an ISP to a small
   company or organization. It receives mail addressed to any user in a given
   domain -- for example, mail to info@smallcompany.tld,
   tgrieg@smallcompany.tld, and sales@smallcompany.tld all ends up in the
   same POP3 domain mailbox. getmail includes features to enable retrieval of
   mail from this type of account, filter it according to who the mail was
   addressed to, and deliver it to different destinations. A minimal
   configuration with this type of setup would be something like this:

 [Company domain mailbox]
 server = mailhost.largeisp.tld
 username = small.company
 password = RRt49slP32m
 postmaster = ~tgrieg/Mail/postmaster-maildir/
 local = tgrieg@smallcompany.tld,~tgrieg/Mail/personal-maildir/
 local = info@smallcompany.tld,~bobf/Maildir/
 local = sales@smallcompany.tld,~darlab/mbox

   The local directives tell getmail to deliver mail for those users to their
   various mail spools on the system, and the postmaster directive tells
   getmail to deliver any mail which doesn't match any of the local
   directives somewhere else.

  Message Delivery Targets

   In a getmailrc file, postmaster and local directives contain message
   delivery targets, which instruct getmail to delivery messages in a
   particular manner. A message delivery target may be a qmail-style Maildir,
   an mboxrd-style mbox file, or an arbitrary command (such as an external
   Message Delivery Agent or MDA).

   Target Type      Syntax                          Notes                     
   Maildir     /path/to/Maildir/ Maildir targets must have a trailing slash   
   mbox        /path/to/mbox     getmail expects mboxrd-style mbox files      
               |/path/to/command Command deliveries must start with a pipe    
   Command     [arguments]       (|). Remember to quote values containing     
                                 whitespace.                                  

   For command deliveries, getmail provides the following environment
   variable:
     * SENDER contains the envelope sender address as extracted from the
       Return-Path: header field, or "#@[]" if not found or empty.
   If you are using local directives for message filtering, getmail also
   provides the following environment variables for command deliveries:
     * RECIPIENT contains the envelope recipient address as extracted from
       the header fields configured with the recipient_header directives.
     * EXT contains the extension part of a user extension address (if any)
       as configured by the extension_sep and extension_depth directives.
   Note the following restrictions:
     * getmail refuses to run external commands when running as root.
     * If an external command writes to stderr, getmail will consider the
       delivery a failure. If you know your MDA can write to stderr on a
       successful delivery, either supply a --quiet option to the MDA (if it
       supports such), or throw away or redirect stderr in one of the
       following manners:

 postmaster = "|/path/to/mda [options] 2>/dev/null"
 postmaster = "|/path/to/mda [options] 2>&1"

       This will, of course, also work with delivery targets in local
       directives.
     * getmail will not create Maildirs or mbox files if they do not exist.
       You must create them prior to having getmail deliver mail to them. Use
       maildirmake to create empty Maildirs; use touch to create empty mbox
       files.
     * getmail will not deliver to an mbox symlink. Specify the path to the
       actual mbox file instead.
     * Do not deliver to mbox files located on an NFS filesystem. This is
       unsafe and can corrupt your mbox file -- this applies to all MDAs, not
       just getmail. Use Maildirs instead; they are immune to such problems
       and do not require any locking. See http://cr.yp.to/proto/maildir.html
       for details.
     * getmail requires write access to any mbox file or Maildir you wish to
       deliver mail to. This can be done my making the Maildirs or mbox files
       group-writable by the group you run getmail under, for example. There
       are other ways as well.
   Leading tilde characters (~) on paths will be expanded -- i.e.
   ~jason/Maildir/ likely becomes /home/jason/Maildir/ on most systems.

getmailrc Directives

   getmail understands the following getmailrc directives:

          Directive         Optional?      Default             Summary        
   POP3 Server Configuration
   server                   No        None              POP3 server hostname  
   port                     Yes       110               POP3 server TCP port  
                                                        number                
   timeout                  Yes       180 seconds       POP3 server TCP       
                                                        timeout               
   Account Configuration    
   username                 No        None              POP3 account username 
   password                 Yes       Prompt for        POP3 account password 
                                      password          
                                                        Use POP3 APOP         
   use_apop                 Yes       0 (No)            authentication if     
                                                        available             
   Message Formatting       
                                                        Suppress addition of  
   no_delivered_to          Yes       0 (No)            Delivered-To: header  
                                                        field                 
                                                        Suppress addition of  
   no_received              Yes       0 (No)            Received: header      
                                                        field                 
   Message Delivery Targets 
   postmaster               No        None              Default message       
                                                        delivery target       
                                                        Header field          
   local                    Yes       None              pattern-matching      
                                                        delivery target       
                                      Delivered-To,                           
                                      Envelope-To,                            
                                      Apparently-To,    Extract recipient     
   recipient_header         Yes       X-Envelope-To,    names from listed
                                      Resent-To,        mail header fields
                                      Resent-cc,        
                                      Resent-bcc, To,   
                                      cc, bcc, Received 
                                                        Allow looser or more  
   relaxed_address_match    Yes       0                 relaxed matching of   
                                                        email addresses.      
                                                        User extension        
   extension_sep            Yes       -                 address separator     
                                                        character             
   extension_depth          Yes       1                 User extension        
                                                        address base length   
   Message Retrieval        
                                                        Retrieve all          
   readall                  Yes       1 (Yes)           messages, or only     
                                                        previously unseen     
                                                        messages              
                                                        Do not retrieve       
   max_message_size         Yes       0 (No limit)      messages larger than  
                                                        this setting          
   max_messages_per_session Yes       0 (No limit)      Do not retrieve more  
                                                        than X messages       
                                                        Eliminate duplicate   
   eliminate_duplicates     Yes       0 (No)            messages from POP3    
                                                        mailbox               
   delete                   Yes       0 (No)            Delete messages after 
                                                        retrieval             
   delete_after             Yes       0 (No)            Delete messages X     
                                                        days after retrieval  
   getmail Behaviour        
   verbose                  Yes       1 (Yes)           Show status messages  
                                                        while running         
   message_log              Yes       None              Log message retrieval 
                                                        and delivery to file  

  POP3 Server Configuration

   The following directives are specified in getmailrc sections other than
   [default], and are used to configure which POP3 servers getmail will
   retrieve mail from.

  POP3 Server Hostname

   Function               Specify POP3 server to connect to. 
   Syntax                 server = hostname.domain.tld       
   Optional               No                                 
   Default                None                               
   Commandline equivalent None                               
   Examples               server = pop3.isp.com              

  POP3 TCP Port

   Function               Specify TCP port on POP3 server to connect to. 
   Syntax                 port = portnumber                              
   Optional               Yes                                            
   Default                110 (Default POP3 port)                        
   Commandline equivalent None                                           
   Examples               port = 8110                                    

  POP3 TCP timeout

Function    Specify the TCP timeout to use with an account.                              
Syntax      timeout = value (seconds)                                                    
Optional    Yes                                                                          
Default     180                                                                          
Commandline --timeout = value (seconds)                                                  
equivalent  
Examples    timeout = 360                                                                
            The TCP timeout capabilities are enabled by the timeoutsocket.py module by   
            Timothy O'Malley. A copy of timeoutsocket.py is included with getmail;       
            however, getmail will continue to function (without this capability) if the  
            timeoutsocket module is not present.                                         
                                                                                         
            timeoutsocket.py Copyright 2000,2001 by Timothy O'Malley <timo@alum.mit.edu> 
                                                                                         
                           All Rights Reserved                                           
                                                                                         
            Permission to use, copy, modify, and distribute this software                
            and its documentation for any purpose and without fee is hereby              
            granted, provided that the above copyright notice appear in all              
Note        copies and that both that copyright notice and this permission               
            notice appear in supporting documentation, and that the name of              
            Timothy O'Malley  not be used in advertising or publicity                    
            pertaining to distribution of the software without specific, written         
            prior permission.                                                            
                                                                                         
            Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS                
            SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY                
            AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR                
            ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES                
            WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,                      
            WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS               
            ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR                      
            PERFORMANCE OF THIS SOFTWARE.                                                

  POP3 Account Configuration

   The following directives are specified in getmailrc sections other than
   [default], and are used to configure which POP3 accounts getmail will
   retrieve mail from.

  POP3 account username

   Function               Specify the account name for the POP3 server. 
   Syntax                 username = user                               
   Optional               No                                            
   Default                None                                          
   Commandline equivalent None                                          
   Examples               username = joe.bloggs                         
                          username = joe.bloggs:vhost.example.net       

  POP3 account password

   Function               Specify password to use with POP3 account        
   Syntax                 password = password                              
   Optional               Yes                                              
   Default                Prompt for password                              
   Commandline equivalent None                                             
   Examples               password = "long password containing whitespace" 
                          password = foo_bar                               

  POP3 APOP authentication

   Function               Use POP3 APOP authentication if available. Falls    
                          back to USER/PASS authentication if not supported.  
   Syntax                 use_apop = bool                                     
   Optional               Yes                                                 
   Default                0 (USER/PASS authentication)                        
   Commandline equivalent None                                                
   Examples               use_apop = 1                                        
                          use_apop = 0                                        

  Message Formatting

   The following directives are specified in any getmailrc section, and are
   used to configure how getmail will format messages that it retrieves.

  Delivered-To: header field suppression

   Function               Suppress the addition of a Delivered-To: header     
                          field to messages that getmail retrieves.           
   Syntax                 no_delivered_to = bool                              
   Optional               Yes                                                 
   Default                0 (No)                                              
   Commandline equivalent None                                                
   Examples               no_delivered_to = 1                                 
                          no_delivered_to = 0                                 

  Received: header field suppression

   Function               Suppress the addition of a Received: header field   
                          to messages that getmail retrieves.                 
   Syntax                 no_received = bool                                  
   Optional               Yes                                                 
   Default                0 (No)                                              
   Commandline equivalent None                                                
   Examples               no_received = 1                                     
                          no_received = 0                                     

  Message Delivery Targets

   The following directives are specified in any getmailrc section, and are
   used to configure where getmail will deliver retrieved messages. Also see
   the section on message delivery targets.

  Default delivery target

                          Specify the default delivery target for all         
   Function               retrieved messages which are not handled by a       
                          matching local directive.                           
   Syntax                 postmaster = target                                 
   Optional               No                                                  
   Default                None                                                
   Commandline equivalent None                                                
                          postmaster = /home/joe/Maildir/                     
   Examples               postmaster = ~brenda/mbox                           
                          postmaster = "|/usr/local/bin/my_mda -f foo -a all  
                          -b gone /home/postmaster/.mdarc"                    

  Header field pattern matching delivery target

               Specify the destination for retrieved messages which appear to 
               be addressed to a given user. getmail will match the specified 
               Perl-compatible extended regular expression against all        
               apparent email addresses found in the header fields specified  
               with the recipient_header directive. If a match is found, the  
               message will be delivered to the specified target. If multiple 
               local directives contain matching patterns, each matching      
               target will receive a copy of the message. If there are no     
   Function    local directives, or no match is found, the message will be    
               delivered according to the default delivery target.            
                                                                              
               If you do not understand Perl-compatible regular expressions,  
               just use email addresses here. They will work in virtually all 
               cases.                                                         
                                                                              
               Use multiple local directives to filter mail retrieved from a  
               domain mailbox to multiple local user accounts.                
   Syntax      local = pattern,target                                         
   Optional    Yes                                                            
   Default     None                                                           
   Commandline None                                                           
   equivalent  
               local = joe@isp.tld,~joe/Maildir/                              
               local = brenda@homeisp.tld,/home/brenda/Mail/personal/         
   Examples    local = brenda@workisp.tld,/home/brenda/Mail/work/             
               local = "^(joe|fred)@company\.(tld|dom.tld)$,|/path/to/mda     
               -opts"                                                         

  Recipient header field specification

                          Extract recipient addresses from listed header      
                          field. These fields will be used to find local      
                          recipient email addresses when using local          
                          directives. To specify multiple recipient header    
                          fields, use multiple recipient_header directives.   
                                                                              
   Function               This directive is mostly useful if the POP3 server  
                          records envelope recipient addresses in a specific  
                          header field (i.e. Delivered-To: or                 
                          X-Envelope-To:), and you wish to process mail from  
                          a domain mailbox, sorting and delivering it to      
                          multiple local user accounts using local            
                          directives.                                         
   Syntax                 recipient_header = fieldname                        
   Optional               Yes                                                 
                          Delivered-To, Envelope-To, Apparently-To,           
   Default                X-Envelope-To, Resent-To, Resent-cc, Resent-bcc,    
                          To, cc, bcc, Received                               
   Commandline equivalent None                                                
   Examples               recipient_header = Delivered-To                     
                          recipient_header = X-Envelope-To                    

  Relaxed email address detection

                          Allow looser or more relaxed matching of email      
                          addresses. Set this to 1 to enable. When enabled,   
   Function               any string will be considered a valid email         
                          address; otherwise, it must contain an at-sign (@), 
                          and the domain must contain a dot (.) followed by   
                          arbitrary text.                                     
   Syntax                 relaxed_address_match = value                       
   Optional               Yes                                                 
   Default                0 (Stricter matching)                               
   Commandline equivalent None                                                
   Examples               relaxed_address_match = 1                           
                          relaxed_address_match = 0                           

  User address extension separator character

                          Determine which part of a recipient address is the  
                          extension to the base address.                      
                                                                              
                          This directive is mostly useful if the POP3 server  
                          records envelope recipient addresses in a specific  
                          header field (i.e. Delivered-To: or                 
                          X-Envelope-To:), and you wish to deliver mail using 
                          TMDA or another filtering MDA.                      
                                                                              
                          If you are using a local directive to configure     
                          delivery of mail per-recipient, getmail will export 
   Function               the detected envelope recipient address in the      
                          environment variable RECIPIENT. It will then split  
                          the local-part of the address at the first          
                          occurrence of this character (default: "-"), and    
                          export anything after it as the environment         
                          variable EXT.                                       
                                                                              
                          Note that you will still need a wrapper script      
                          around your filtering MDA; getmail will consider a  
                          delivery failed if the MDA returns non-zero. This   
                          is left as an excercise for the reader/user of      
                          TMDA.                                               
   Syntax                 extension_sep = character                           
   Optional               Yes                                                 
   Default                -                                                   
   Commandline equivalent None                                                
   Examples               extension_sep = +                                   
                          extension_sep = -                                   

  User address extension base length/depth

                          Determine which part of a recipient address is the  
                          extension to the base address.                      
                                                                              
                          This directive is mostly useful if the POP3 server  
                          records envelope recipient addresses in a specific  
                          header field (i.e. Delivered-To: or                 
                          X-Envelope-To:), and you wish to deliver mail using 
   Function               TMDA or another filtering MDA.                      
                                                                              
                          If you are using a local directive to configure     
                          delivery of mail per-recipient, getmail will export 
                          the detected envelope recipient address in the      
                          environment variable RECIPIENT. It will then remove 
                          the base part of the address at the extension_depth 
                          occurrence of the extension separator character.    
   Syntax                 extension_depth = count                             
   Optional               Yes                                                 
   Default                1                                                   
   Commandline equivalent None                                                
   Examples               extension_depth = 2                                 

  Message Retrieval

   The following directives are specified in any getmailrc section, and are
   used to configure how getmail will retrieve messages.

  Retrieve new messages / retrieve all messages

                          Select whether to retrieve all messages, or only    
   Function               messages which have previously not been seen by     
                          getmail.                                            
   Syntax                 readall = bool                                      
   Optional               Yes                                                 
   Default                1 (Retrieve all messages)                           
   Commandline equivalent --all (readall = 1)                                 
                          --new (readall = 0)                                 
   Examples               readall = 1                                         
                          readall = 0                                         

  Maximum message size to retrieve

                          Specify a maximum message size to retrieve.         
   Function               Messages larger than this will be left on the       
                          server and not retrieved.                           
   Syntax                 max_message_size = value (bytes)                    
   Optional               Yes                                                 
   Default                0 (No limit)                                        
   Commandline equivalent None                                                
   Examples               max_message_size = 2000000                          
                          max_message_size = 150000                           

  Maximum message size to retrieve

                          Specify a maximum message size to retrieve.         
   Function               Messages larger than this will be left on the       
                          server and not retrieved.                           
   Syntax                 max_message_size = value (bytes)                    
   Optional               Yes                                                 
   Default                0 (No limit)                                        
   Commandline equivalent None                                                
   Examples               max_message_size = 2000000                          
                          max_message_size = 150000                           

  Duplicate message suppression

                          When a message is sent to two recipients in the     
                          same domain mailbox, two copies are delivered to    
                          the POP3 server. If the server does not record the  
                          envelope recipient in a header field (such as       
                          Delivered-To:), each local recipient may receive    
                          two copies of the message in their mailbox.         
   Function               Enabling eliminate_duplicates will work around this 
                          problem.                                            
                                                                              
                          Note that the correct solution is to have the POP3  
                          server record the envelope recipient address in a   
                          header field in the message, and then use the       
                          recipient_header directive to filter only using the 
                          contents of that field.                             
   Syntax                 eliminate_duplicates = bool                         
   Optional               Yes                                                 
   Default                0 (Do not eliminate duplicates)                     
   Commandline equivalent None                                                
   Examples               eliminate_duplicates = 1                            
                          eliminate_duplicates = 0                            

  Delete messages after retrieval

   Function               Delete messages after retrieval. 
   Syntax                 delete = bool                    
   Optional               Yes                              
   Default                0 (Do not delete)                
   Commandline equivalent --dont-delete (delete = 0)       
                          --delete (delete = 1)            
   Examples               delete = 1                       
                          delete = 0                       

  Delete messages X days after retrieval

                          Delete messages a specified number of days after    
   Function               they are first retrieved.                           
                                                                              
                          Note: delete overrides delete_after.                
   Syntax                 delete_after = value (days)                         
   Optional               Yes                                                 
   Default                0 (Do not use delete_after)                         
   Commandline equivalent None                                                
   Examples               delete_after = 3                                    
                          delete_after = 180                                  

  getmail Behaviour

   The following directives are specified in any getmailrc section, and are
   used to control other aspects of getmail's behaviour.

  Verbosity

   Function               Specify whether getmail writes status and           
                          informational messages to stdout while running.     
   Syntax                 verbose = bool                                      
   Optional               Yes                                                 
   Default                1 (Verbose)                                         
   Commandline equivalent --verbose (verbose = 1)                             
                          --quiet (verbose = 0)                               
   Examples               verbose = 1                                         
                          verbose = 0                                         

  Message Logging

                          Specify whether getmail writes message retrieval    
   Function               and delivery information to a log file. Set to the  
                          empty string to disable logging.                    
   Syntax                 message_log = file                                  
   Optional               Yes                                                 
   Default                None                                                
   Commandline equivalent None                                                
   Examples               message_log = /var/log/getmail                      
                          message_log = ""                                    

Running getmail

   Run the getmail helper script you installed earlier:

 getmail

   By default, getmail will read in the default getmailrc file
   ($HOME/.getmail/getmailrc) and begin retrieving mail.
   You can also supply commandline options. For a brief summary of usage and
   commandline options, run:

 getmail --help

getmail Commandline Options

   getmail understands the following commandline options:

       Long Form      Short Form                   Summary                    
   --help             -h         Display usage and default option values and  
                                 exit                                         
   --getmaildir path  -g path    Use path as getmail configuration/data       
                                 directory                                    
   --rcfile file      -r file    Use file as getmailrc configuration file     
   --quiet            -q         No status output                             
   --verbose          -v         Verbose status output                        
   --message-log file -m file    Log getmail operations to file               
   --all              -a         Retrieve all messages                        
   --new              -n         Retrieve only new messages                   
   --delete           -d         Delete messages after retrieval              
   --dont-delete      -l         Do not delete messages after retrieval       
   --timeout val      -t val     Set socket timeout to val seconds            
   --trace                       Enable debugging output                      
   --dump                        Dump configuration and exit                  

  --help or -h

   Long Option          --help                                
   Short Option         -h                                    
   getmailrc equivalent None                                  
   Function             Display usage information, then exit. 

  --getmaildir or -g

   Long Option          --getmaildir path                                     
   Short Option         -g path                                               
   getmailrc equivalent None                                                  
   Function             Use path as getmail configuration/data directory.     
                        Defaults to $HOME/.getmail/                           

  --rcfile or -r

   Long Option          --rcfile filename                                     
   Short Option         -r filename                                           
   getmailrc equivalent None                                                  
   Function             Use filename as getmailrc file. Defaults to getmailrc 
                        in the getmaildir directory.                          

  --quiet or -q

   Long Option          --quiet                       
   Short Option         -q                            
   getmailrc equivalent verbose = 0                   
   Function             Produce output only on error. 

  --verbose or -v

   Long Option          --verbose                                     
   Short Option         -v                                            
   getmailrc equivalent verbose = 1                                   
   Function             Write status and progress messages to stdout. 

  --message-log

   Long Option          --message-log file                                    
   Short Option         None                                                  
   getmailrc equivalent message_log = file                                    
   Function             Log message retrieval and delivery information to     
                        file.                                                 

  --all or -a

   Long Option          --all                  
   Short Option         -a                     
   getmailrc equivalent readall = 1            
   Function             Retrieve all messages. 

  --new or -n

   Long Option          --new                                     
   Short Option         -n                                        
   getmailrc equivalent readall = 0                               
   Function             Retrieve only previously unseen messages. 

  --delete or -d

   Long Option          --delete                                     
   Short Option         -d                                           
   getmailrc equivalent delete = 1                                   
   Function             Delete messages from server after retrieval. 

  --dont-delete or -l

   Long Option          --dont-delete                             
   Short Option         -l                                        
   getmailrc equivalent delete = 0                                
   Function             Leave messages on server after retrieval. 

  --timeout or -t

   Long Option          --timeout value (seconds)         
   Short Option         -t value (seconds)                
   getmailrc equivalent timeout = value (seconds)         
   Function             Set TCP timeout to value seconds. 

  --trace

   Long Option          --trace                                        
   Short Option         None                                           
   getmailrc equivalent None                                           
   Function             Write verbose debugging information to stdout. 

  --dump

   Long Option          --dump                                                
   Short Option         None                                                  
   getmailrc equivalent None                                                  
                        Do not retrieve mail; read getmailrc file and         
   Function             commandline options, then print configuration on      
                        stdout. This information should be included in all    
                        bug reports or support requests.                      
