Usage: ====== getmail is intended as a simple replacement for 'fetchmail', for those people who don't need its various and sundry configuration options, complexities, and bugs. It retrieves mail from one or more POP3 servers for one or more email accounts, and reliably delivers into a Maildir specified on a per-account basis. It can now also deliver into mbox files, although this should not be attempted over NFS. Support for domain (multidrop) mailboxes has been added. Feedback on this feature would be greatly appreciated. Bugs, questions, feature requests, and comments should be directed to me (Charles Cazabon) at . In a nutshell: -------------- 1. Ensure Python v.1.5.2 is installed. See http://www.python.org/ for details. Note that RedHat GNU/Linux 6.0 ships with v.1.5.1, which will fail. 2. Install the script 'getmail.py' somewhere with executable permissions (0755). 3. Optionally set up a symbolic link named 'getmail' pointing to the script. 4. Create a .getmail/ directory in your home directory. 5. Create a file .getmailrc in the above directory. This file has a simple syntax, similar to a standard MS-Windows .ini file. In it, place one section for each mail account you wish to retrieve mail for. The section is in this format: [identifier] # Whatever you like, just make them unique account=username # Required, your POP3 account name host=popmailhost # Required, the POP3 mailhost port=portnum # Optional, defaults to standard POP3 port (110) password=poppass # Optional, getmail will prompt for passwords destination=path # Required, path to destination Maildir or mbox delete=value # Optional, delete mail after retrieving. readall=value # Optional, retrieve all mail, not just unread. 'destination' can be either a Maildir or an mbox file. getmail auto-detects Maildirs, and assumes regular files are mboxes. 'delete' and 'readall' take values of 'yes', 'true', '1' for yes, or 'no', 'false', '0' for no. 'delete' defaults to no, readall defaults to yes. See the example.getmailrc file for more details. 6. Run getmail with no options to retrieve all mail for accounts in .getmailrc. Use option -n or --new for only unread mail. Use option -v or --verbose to see what's going on. For domain (multidrop) mailbox support, read the section at the end of this document. Basic usage for getmail.py: --------------------------- Run without arguments for help. To retrieve mail for accounts on a one-time basis, you can specify the accounts as arguments on the commandline as follows: getmail.py [options] user1@mailhost1[:port],destination1[,password1] \ user2@mailhost2[:port],destination2[,password2] For example, to retrieve mail for account 'joe' on mailhost 'mail.isp.com', running on port 8110, and deliver that mail into the maildir 'Maildir' in your home directory, run as follows: getmail.py [options] joe@mail.isp.com:8110,$HOME/Maildir,password If you omit the final ',password', getmail will prompt you for your password. You may omit the :port portion if the server runs on the standard POP3 port (110). You can retrieve mail for multiple accounts at once, delivering to different destinations, by specifying multiple arguments: getmail.py [options] user1@mailhost1.net:8110,$HOME/Maildir,password \ user2@mailhost2.com,$HOME/inbox Note in this case, mailhost2 is on the standard POP3 port and the user will be prompted only for user2's password. These arguments can also be placed in a configfile (suggested: $HOME/.getmail/.getmailrc). See above (or the example.getmailrc file included) for its format. This file can be specified on the commandline with the -r or --rcfile options. It defaults to '.getmailrc' in a directory taken from the environment variable 'GETMAIL', if it exists. If the environment variable does not exist, it will try a directory called .getmail in your home directory. Specifying a config file on the commandline overrides the environment variable. An alternate configuration directory can also be specified on the commandline. The default .getmailrc file can be skipped by supplying the --ignoreconfig or -i option. You can specify your own defaults by setting the environment variable 'GETMAILOPTS' with the options you like. For instance, setting it to "--verbose --new" will enable these two options by default. These types of default options can be overridden on the commandline. Options that getmail currently recognizes are: -a or --all retrieve all messages. This is the default. -u or --new retrieve only unread messages. -d or --delete delete mail after retrieving. -l or --dont-delete leave mail on server after retrieving. This is the default. -v or --verbose output more information. Without this, getmail will be fairly quiet. -q or --quiet output less information. To override the --verbose/-v options. -h or --help basic usage information. -i or --ignoreconfig Don't read the default .getmailrc file. -r or --rcfile read account information from This overrides the default configfile. The default is '.getmailrc' in the directory specified below. -c or --configdir Store data in instead of the default, which is taken from the environment variable 'GETMAIL' if it exists. --dump Output debugging information on your usage. If you have problems with getmail, invoke it with the options you normally use, plus --dump and send the output to me at . Support for Domain Mailboxes ---------------------------- I have added support for domain (multidrop) mailboxes. A domain mailbox is a POP3 mailbox which receives mail for multiple users. For example, all mail for anyone at mycompany.com might be delivered to a single POP3 mailbox named 'mycompany@isp.com'. getmail can be configured to retrieve mail from a domain mailbox, and deliver each message separately, to the user it was originally addressed to. It can also change the ownership of message files delivered to a Maildir on a per- recipient basis. This type of operation is not supported in a standard way by the majority of the email infrastructure, so there is the possibility of problems when attempting this. getmail tries to determine who each message was originally intended for by looking at the message headers. If the first valid header is a qmail-style "Delivered-To: " header, it will use that as the recipient. If that header does not exist, it will look for recipients in "Envelope-To: ". If that header does not exist, it will look for recipients in "X-Envelope-To: ". If that header does not exist, it will look for recipients in "Resent-To: ", "Resent-cc: ", and "Resent-bcc: " headers. If none of those headers exist, it will look for recipients in "To: ", "cc: ", and "bcc: " headers. getmail compares the recipients it finds against email addresses supplied in the .getmailrc configuration file. For each matching address it finds, getmail delivers a copy of that message to a destination Maildir or mbox file specified for that address. If it finds no matches, it delivers the message to a default destination, which should be the postmaster or other person responsible for sorting out email issues in that domain. The configuration file uses the '#' symbol to start comments and therefore cannot appear in usernames, passwords, etc in that file. The configuration file parser was written from scratch for version 0.99, so the other limitations on the file are gone. The configuration file section for a domain mailbox should look like this: [Section title] # Comments can follow lines type=domainbox account=pop3username # Leading and trailing whitespace is ignored host=pophost.domain password = " pop_password" # Whitespace surrounding the '=' is OK too. # Quote values which have leading or trailing # whitespace destination=/path/to/default_delivery_destination delete=(yes|no) readall=(yes|no) email@address = /path/to/destination[:username] email@address2 = /path/to/destination2[:username] [...] Some examples of the "email=destination" lines are: joe@smallcompany.com=/home/joe/Maildir:joe info@smallcompany.com=/home/paula/inbox:paula Note that getmail must have write access to the Maildir or mbox files which it delivers mail to. This may mean making them group-writable, or running getmail as root. If run as root, getmail will change the ownership of message files it creates in a Maildir to the UID and GID of the user specified after a colon in the destination line (if provided). getmail never forks any processes or execs any other programs, so the security implications are limited. Note, however, that any regular file specified as a destination will be appended to with messages for that destination -- getmail does not verify that a file it can write to is indeed an mbox file. This is one more reason to use Maildirs.