getmail

POP3 mail retriever with reliable Maildir delivery

4 April 2000

Charles Cazabon <getmail @ discworld.dyndns.org>


Table of Contents


1 About getmail

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.

getmail is Copyright (C) 2000 Charles Cazabon.
Licensed under the GNU General Public License version 2. See the file `COPYING' for license details.

2 The getmail FAQ

There is now a FAQ available about getmail. Read it here.

3 Getting getmail

There are links to download getmail at the bottom of this document. You can skip directly to them by clicking here.

4 Using getmail

4.1 Installing getmail

getmail is a Python script. Ensure the Python interpreter is installed (version 1.5.1 or higher is recommended; at the time of this writing, the current version was 1.5.2. See www.python.org for details). Put the script somewhere with executable permissions (probably 0755). A simpler Python script which invokes the main getmail script can be used to reduce startup time:

#!/usr/bin/python
import getmail
getmail.main ()

This allows the Python interpreter to cache the contents of the getmail script in a `.pyc' file. Python will not write these `.pyc' files for a script invoked on the commandline. The rest of this file assumes you have a getmail file which invokes getmail.py. If you don't want this, you can make it a symbolic link, or invoke getmail as getmail.py, or rename the main script.

4.2 Running getmail

Run getmail with the `-h' or `--help' options for help.

4.2.1 Retrieving mail on a one-time basis

To retrieve mail for accounts on a one-time basis, run with arguments as follows:

getmail [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

`destination' can be either a `Maildir' or an `mbox' file. getmail auto-detects `Maildir's, and assumes regular files are `mbox' files.

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 maildirs, by specifying multiple arguments:

getmail.py [options] user1@mailhost1.net:8110,$HOME/Maildir,password user2@mailhost2.com,$HOME/user2mbox

Note in this case, `mailhost2' is on the standard POP3 port and the user will be prompted only for user2's password.

4.2.2 Retrieving mail on a regular basis

To use getmail to retrieve from the same accounts on a regular basis, and to be able to retrieve only mail messages which getmail has not previously retrieved, set up getmail as follows:

  1. Create a `.getmail/' directory in your home directory. If you want to call it something else or have it in a different location, set the environment variable `GETMAIL' to be the location of the directory.
  2. Create a file `.getmailrc' in the above directory. This file is similar in format to an 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]
    account=username
    host=popmailhost
    port=port
    password=password
    destination=destinationpath[:username]
    delete=value
    readall=value
    
    The options can be specified in any order. Blank lines are ignored, as is anything after a `#' symbol. Leading and trailing whitespace on the option names and values is ignored. To preserve leading or trailing whitespace on an option value (such as a POP password), surround it with either single or double quotes. The meaning of the individual options in each section are as follows: See the included example.getmailrc file for more details.
  3. Run getmail with no options to retrieve all mail for accounts specified in the .getmailrc file. Use option `-n' or `--new' for only unread mail. Use option `-v' or `--verbose' to see what's going on.
  4. You can specify personal default options in the environment variable `GETMAILOPTS'. To make getmail always be verbose, and always delete retrieved mail from the server, set it to something like `--verbose --delete'. Again, you can set this every time you login in your `.bash_profile' or `.bashrc' file if you use the bash shell.

4.3 Commandline Options for getmail

getmail understands the following commandline options.

4.4 Configuration File Options for getmail

getmail understands the following options in it's configuration file (e.g. `.getmailrc').

5 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. This type of operation is not 100% reliable, unfortunately, because of the way many MTAs implement domain mailboxes. getmail tries to work around this by supporting (among other methods) the `Delivered-To: ' header implemented by more reliable MTAs (like qmail).

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 check `X-Envelope-To:'. If that header does not exist, it will look 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. If getmail fails to find any email addresses by this point, it will look in `Received:' 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.

Note that the configuration file parser was completely rewritten for version 0.99, so that it removes most of the restrictions that were previously present.

The configuration file section for a domain mailbox should look like this:

[Section title]
type = domainbox               # whitespace is OK around the `='
  account=pop3username         # so is leading and trailing whitespace
host=pophost.domain
password = "  pop_password with leading whitespace"
destination=/path/to/default_delivery_destination[:username]
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]

See the file `example.getmailrc' for more details about configuration files.

More details are available in the file `USAGE'.

6 Current Version

The current version of getmail should be available at www.qcc.sk.ca/~charlesc/software/getmail/.

7 Reporting bugs, feature requests, and support requests

To report a bug, make a feature request, or get support with getmail, please send email to me at <getmail @ discworld.dyndns.org>.


This document was generated on 4 April 2000 using the texi2html translator version 1.51a.