getmail

POP3 mail retriever with reliable Maildir delivery

4 April 2000

Table of Contents

• 1 About getmail
• 2 The getmail FAQ
• 3 Getting getmail
• 4 Using getmail
  • 4.1 Installing getmail
  • 4.2 Running getmail
    • 4.2.1 Retrieving mail on a one-time basis
    • 4.2.2 Retrieving mail on a regular basis
  • 4.3 Commandline Options for getmail
  • 4.4 Configuration File Options for getmail
• 5 Support for Domain Mailboxes
• 6 Current Version
• 7 Reporting bugs, feature requests, and support requests

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:
   • `identifier' is not currently used by getmail. Identifiers must be unique, and should be meaningful to you.
   • `account' is your POP3 account name.
   • `host' is the fully-qualified domain name of the POP3 server (e.g. `mailhost.isp.com'.
   • `port' is optional and defaults to the standard POP3 port (110). @item{password} is optional. If not supplied, getmail will prompt for passwords.
   • `destinationpath[:username]' is the path to the destination `Maildir' or `mbox' file, optionally followed by a colon and a system username (from `/etc/passwd' on the system you are running getmail on). If `:username' is present, files created in `Maildir's will have their ownership changed to the UID and default GID of that system user. This is useful, for example, if you are running getmail as `root' but delivering to another user's `Maildir'.
   • `delete' is optional, and controls whether getmail deletes the mail from the POP3 server after retrieving it. Valid values include `yes' and `no'. `delete' defaults to `no'.
   • `readall' is optional, and controls whether getmail retrieves all mail, or only unread mail for that account. Valid values include `yes' and `no'. `readall' defaults to 'yes'.
   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.

• Commandline options which apply to all operations:
  • `-v' or `--verbose'
    Output more information during operation.
  • `-q' or `--quiet'
    Output less information during operation.
  • `-h' or `--help'
    Output basic usage information.
  • `-r' or `--rcfile <file>'
    Use `file' instead of the default `.getmailrc' configuration file.
  • `-c' or `--configdir <dir>'
    Use `dir' as the configuration/data directory instead of the default `$HOME/.getmail' configuration/data directory.
  • `-i' or `--ignoreconfig'
    Do not read any configuration file.
  • `--dump'
    Do not fetch mail; just dump configuration and commandline information for debugging.
• Commandline options which apply only to mail retrieval for accounts specified on the commandline:
  • `-a' or `--all'
    Retrieve all messages, including messages getmail has previously retrieved.
  • `-n' or `--new'
    Retrieve only messages getmail has not previously retrieved.
  • `-d' or `--delete'
    Delete mail from the POP3 server after retrieving.
  • `-l' or `--dont-delete'
    Leave mail on the POP3 server after retrieving.

4.4 Configuration File Options for getmail

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

• Section Name
  A unique identifier for one POP3 account to retrieve mail from, enclosed in square brackets.
  e.g.

  [Joe's home account]
  

• POP3 Account Type
  The identifier `type', followed by `=' and one of `mailbox' or `domainbox'.
  This indicates whether getmail should deliver all mail from this account into a single destination (type `mailbox'), or deliver to various destinations based on the contents of the headers of each retrieved emssage (type `domainbox'). This is optional and may be omitted for `mailbox' account types.
  e.g.

  type=domainbox
  

• POP3 Account Name
  The identifier `account', followed by `=' and the actual account name.
  e.g.

  account=joe.smith
  

• POP3 Hostname
  The identifier `host', followed by `=' and the actual POP3 hostname.
  e.g.

  host=mailhost.isp.net
  

• Port Number
  The identifier `port', followed by `=' and the POP3 port number to use.
  It may be omitted if the POP3 server runs on the standard port (110).
  e.g.

  port=8110
  

• Destination Maildir or mbox
  The identifier `destination', followed by `=' and a complete path to a `Maildir' or `mbox' file to which messages will be delivered for the associated account, optionally followed by `:' and a system username from `/etc/passwd'. If `:username' is present, files created in `Maildir's will have their ownership changed to the UID and default GID of that system user. This is useful, for example, if you are running getmail as `root' but delivering to another user's `Maildir'.
  If the POP3 mailbox is a domain mailbox, this specifies the default delivery destination which will be used when none of the supplied user addresses are found in a retrieved email.
  e.g.

  destination=/home/username/Maildir/
  destination=/home/username/Maildir/:username
  destination=/users/a-f/username/mboxfile
  

• POP3 Account Password
  The identifier `password', followed by `=' and the actual account password.
  This is optional. If omitted, getmail will prompt for the password when run.
  e.g.

  password=mypoppassword
  

• Delete Option
  The identifier `delete', followed by `=' and one of `yes' or `no'.
  This indicates whether getmail should delete the mail from the POP3 server after retrieving it. This is optional, and defaults to `no'.
  e.g.

  delete=yes
  

• Read All Option
  The identifier `readall', followed by `=' and one of `yes' or `no'.
  This indicates whether getmail should retrieve all mail from this account, or just messages which it has not previously seen. This is optional, and defaults to `no'. Note that this option is meaningless if getmail is deleting mail after retrieving it.
  e.g.

  readall=yes
  

• Domain Mailbox Destinations
  All other `option=value' pairs in a given section will be treated as destinations in a domain mailbox, in the form of email address, `=', and a destination path which is a `Maildir' or `mbox' file. Note that getmail now forces all email addresses to lower case. This is optionally followed by a colon (`:') and a system username. If the username is provided, message files created in a Maildir for this recipient will have their ownership (UID and GID) changed to match the UID and GID associated with that system account. Note that this only works if getmail runs with `root' privileges. Typically you would set the username to be the same as the owner of the Maildir getmail is delivering to.
  e.g.

  john.smith-lists-weasel-farming@isp.net=/users/jsmith/Mail/list-weasels
  john.smith-lists-perl@isp.net=/users/jsmith/Mail/list-perl
  john.smith-home@isp.net=/users/jsmith/Mail/personal
  info@mycompany.com=/users/rharrington/Mail/info-requests/:rharrington
  

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.