getmail documentation

This is the documentation for getmail version 6.

getmail is Copyright © 1998-2019 by Charles Cazabon <charlesc-getmail @ pyropus.ca>
and © 2020 by Roland Puntaier <roland.puntaier @ gmail.com>

getmail is licensed under the GNU General Public License version 2 (only).

Table of Contents

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:

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:

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.

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:

All retriever types also take several optional parameters:

All IMAP retriever types also take the following optional parameters:

SSL Client Parameters

All SSL-enabled retriever types also take the following options, to allow specifying the use of a particular client key and client certificate in establishing a connection to the server.

SSL Certificate Validation and Server Parameters

All SSL-enabled POP and IMAP retriever types also take the following options, allowing you to require validation of the server's SSL certificate, or to check the server's certificate fingerprint against a known good value, or to control the specific SSL cipher used during the connection.

Note: using these features, including server certificate validation, requires using Python 2.6 or Python 2.7 or higher with getmail. If you use an earlier version of Python, these features will not work, and no server certificate validation will be performed. Also note that these features are not currently implemented for SPDS retrievers; I would be interested in hearing from SPDS users who desire these features.

SimplePOP3Retriever

The SimplePOP3Retriever class takes the common retriever parameters above, plus the following optional parameters:

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:

SimpleIMAPRetriever

The SimpleIMAPRetriever class takes the common retriever parameters above, plus the following optional parameters:

SimplePOP3SSLRetriever

The SimplePOP3SSLRetriever class takes the common retriever parameters above, plus the following optional parameters:

BrokenUIDLPOP3SSLRetriever

The BrokenUIDLPOP3SSLRetriever class takes the common retriever parameters above, plus the following optional parameters:

SimpleIMAPSSLRetriever

The SimpleIMAPSSLRetriever class takes the common retriever parameters above, plus the following optional parameters:

MultidropPOP3Retriever

The MultidropPOP3Retriever class takes the common retriever parameters above, plus the following required parameter:

The MultidropPOP3Retriever also takes the following optional parameters:

MultidropPOP3SSLRetriever

The MultidropPOP3SSLRetriever class takes the common retriever parameters above, plus the following required parameter:

The MultidropPOP3SSLRetriever class alo takes the following optional parameters:

MultidropSDPSRetriever

The MultidropSDPSRetriever class takes the common retriever parameters above, plus the following optional parameters:

MultidropIMAPRetriever

The MultidropIMAPRetriever class takes the common retriever parameters above, plus the following required parameter:

The MultidropIMAPRetriever class also takes the following optional parameters:

MultidropIMAPSSLRetriever

The MultidropIMAPSSLRetriever class takes the common retriever parameters above, plus the following required parameter:

The MultidropIMAPSSLRetriever class also takes following optional parameters:

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

The Maildir destination delivers to a qmail-style maildir. The maildir must already exist, and must contain all of the subdirectories required by the maildir format. getmail will not create the maildir if it does not exist. If you're not familiar with the maildir format, the requirements in a nutshell are: it must be a directory containing three writable subdirectories cur, new, and tmp, and they must all reside on the same filesystem.

The Maildir destination takes one required parameter:

The Maildir destination also takes two optional parameters:

Mboxrd

The Mboxrd destination delivers to an mboxrd-format mbox file with either fcntl-type (lockf) or flock-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. If you want to create a new mboxrd file for getmail to use, simply create a completely empty (0-byte) file.

You must ensure that all other programs accessing any the mbox file expect mboxrd-format mbox files and the same type of file locking that you configure getmail to use; failure to do so can cause mbox corruption. If you do not know what type of file locking your system expects, ask your system administrator. If you are the system administrator and don't know what type of file locking your system expects, do not use Mboxrd files; use Maildirs instead. 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:

The Mboxrd destination also takes two optional parameters:

MDA_external

MDA_external delivers messages by running an external program (known as a message delivery agent, or MDA) and feeding it the message on its standard input. Some typical MDAs include maildrop and procmail.

The MDA_external destination takes one required parameter:

The MDA_external destination also takes several optional parameters:

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:

Some examples:

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 getmail's best guess as to the envelope recipient of the message, see the MultiGuesser destination class below.

The MultiSorter destination takes one required parameter:

The MultiSorter destination also takes one optional parameter:

Important note: if your regular expression contains backslashes (by themselves, or as part of an escaped character or symbol like \n or \W ), you need to tell the parser that this expression must be parsed "raw" by prepending the string with an "r": 

locals = (
    (r'jeff\?\?\?@.*', '[jeff]'),
    ('alice@', '[alice]')
    )

locals = (
    ('jeff@.*', '[jeff]'),
    (r'alice\D+@', '[alice]')
    )

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:

Using regular expressions:

Some examples:

MultiGuesser

MultiGuesser tries to guess what the envelope recipient address of the message might have been, by comparing 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), if and only if the message recipient is the criteria you want to filter on.

If you want to filter based on arbitrary message critera, like "What address is in the To: header field?" or "Who is the message from?", then use the filtering MDA of your choice, called from a getmail MDA_external destination.

MultiGuesser is similar to MultiSorter, except that it does not operate on the true 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:

The MultiGuesser destination also takes one optional parameter:

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:

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:

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:

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:

By default, 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. Optionally, if you know your filter can emit warnings on stderr under non-error conditions, you can set the ignore_stderr option.

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:

In addition, Filter_classifier takes the following optional parameters:

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:

In addition, Filter_external takes the following optional parameters:

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™, 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:

[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/plain,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:

If you are using a single getmailrc file with an IMAP server that understands the IDLE extension from RFC 2177, you can use the --idle=MAILBOX option to specify that getmail should wait on the server to notify getmail of new mail in the specified mailbox after getmail is finished retrieving mail.

In addition, the following commandline options can be used to override any values specified in the [options] section of the getmail rc files:

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 getmailrc-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

Using getmail_fetch to retrieve mail from scripts

getmail includes the getmail_fetch helper script, which allows you to retrieve mail from a POP3 server without the use of a configuration file. It is primarily intended for use in automated or scripted environments, but can be used to retrieve mail normally.

See the getmail_fetch manual page for details on the use of getmail_fetch.