This is the documentation for getmail version 4. Version 4 includes numerous changes from version 3.x; if you are using getmail version 3, please refer to the documentation included with that version of the software.
getmail is Copyright © 1998-2004 Charles Cazabon.
getmail is licensed under the GNU General Public License version 2 (only). If you wish to obtain a license to distribute getmail under other terms, please contact me directly.
Once getmail is installed, you need to configure it before you can retrieve mail with it. Follow these steps:
mkdir -m 0700 $HOME/.getmail
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.
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.
Specify a string parameter value with no special syntax:
parameter = my value
Specify an integer parameter value with no special syntax:
parameter = 4150
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
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", )
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 = ()
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"),
)
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:
If you're not sure which to use, you probably want SimplePOP3Retriever (for POP3 mail accounts) or SimpleIMAPRetriever (for IMAP mail accounts). If you don't know what type of mail account you currently have, consult the documentation your ISP or mailhost provides you with.
Specify the mail account type with one of the above values, like this:
type =
Then, include lines for any parameters and their values which are required by the retriever. The parameters and their types are documented below.
All retriever types take several common required parameters:
All retriever types also take several optional parameters:
The SimplePOP3Retriever class takes the common retriever parameters above, plus the following optional parameter:
The SimpleIMAPRetriever class takes the common retriever parameters above, plus the following optional parameters:
mailboxes = ("INBOX", "INBOX.spam",
"mailing-lists.model-railroading")
The SimplePOP3SSLRetriever class takes the common retriever parameters above, plus the following optional parameters:
The SimpleIMAPSSLRetriever class takes the common retriever parameters above, plus the following optional parameters:
The MultidropPOP3Retriever class takes the common retriever parameters above, plus the following required parameter:
envelope_recipient = delivered-to:1
The MultidropPOP3Retriever also takes the following optional parameters:
The MultidropPOP3SSLRetriever class takes the common retriever parameters above, plus the following required parameter:
The MultidropPOP3SSLRetriever class alo takes the following optional parameters:
The MultidropSDPSRetriever class takes the common retriever parameters above, plus the following optional parameters:
The MultidropIMAPRetriever class takes the common retriever parameters above, plus the following required parameter:
The MultidropIMAPRetriever class also takes the following optional parameters:
The MultidropIMAPSSLRetriever class takes the common retriever parameters above, plus the following required parameter:
The MultidropIMAPSSLRetriever class also takes following optional parameters:
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
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:
The Maildir destination delivers to a qmail-style maildir.
The Maildir destination takes one required parameter:
[destination]
type = Maildir
path = ~/Maildir/
The Maildir destination also takes one optional parameters:
The Mboxrd destination delivers to an mboxrd-format mbox file with fcntl-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.
You should ensure that all other programs accessing any the mbox file expect mboxrd-format mbox files and fcntl-type file locking; failure to do so can cause mbox corruption. 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:
[destination]
type = Mboxrd
path = ~/inbox
The Mboxrd destination also takes one optional parameters:
MDA_external delivers messages by running an external program (known as a message delivery agent, or MDA). Some typical MDAs include maildrop and procmail.
The MDA_external destination takes one required parameter:
The MDA_external destination also takes several optional parameters:
If an external MDA 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 MDA you use not to emit messages to stderr except on errors — please see the documentation for your MDA for details; this should be the default mode of operation for any sane MDA.
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 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:
destinations (tuple of quoted strings) — the destinations which the messages will be passed to. A destination is a string that refers to another configuration file section by name (shortcuts for maildirs and mboxrd files are also provided; see below), like this:
destinations = ('[other-destination-1]', '[other-destination-2]')
[other-destination-1]
type = Mboxrd
path = /var/spool/mail/alice
user = alice
[other-destination-2]
type = Maildir
path = /home/joe/Maildir/
user = joe
Because Maildir and Mboxrd destinations are common, you can specify them directly as a shortcut if they do not require a user parameter. If the string (after expansion; see below) starts with a dot or slash and ends with a slash, it specifies the path of a Maildir destination, while if it starts with a dot or a slash and does not end with a slash, it specifies the path of a Mboxrd destination.
For instance, you can deliver mail to two maildirs with the following:
destinations = ('~/Mail/inbox/', '~/Mail/archive/current/')
Each destination string is first expanded for leading ~ or ~ and environment variables in the form $ or ${}.
Some examples:
[destination]
type = MultiDestination
destinations = ("~jeff/Maildir/", )
[destination]
type = MultiDestination
destinations = ("/var/spool/mail/alice", )
[destination]
type = MultiDestination
destinations = ("[procmail-as-bob]", )
[procmail-as-bob]
type = MDA_external
path = /path/to/procmail
arguments = ('~bob/.procmailrc', '-f', '%(sender)')
user = bob
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 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 addresses found in the message header (using getmail as a combination retriever and basic filtering MDA), see the MultiGuesser destination class below.
The MultiSorter destination takes one required parameter:
The MultiSorter destination also takes one optional parameter:
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:
[destination]
type = MultiSorter
default = [bob-default]
locals = (
('jeff@example.net', '[jeff]'),
('alice@', '[alice]')
)
[jeff]
type = Maildir
path = ~jeff/Maildir/
user = jeff
[alice]
type = Mboxrd
path = ~alice/inbox
user = alice
[bob-default]
type = Maildir
path = ~bob/Maildir/
user = bob
[destination]
type = MultiSorter
default = doesn't matter, this won't be used, as locals will always match
locals = (
('^jeff@'), '[jeff]'),
('^bob@'), '[bob]'),
('^alice@'), '[alice]'),
('.'), '[copies]'),
('.'), '[info]')
)
[alice]
type = Maildir
path = ~alice/Maildir/
user = alice
[bob]
type = Maildir
path = ~bob/Maildir/
user = bob
[jeff]
type = Maildir
path = ~jeff/Maildir/
user = jeff
[copies]
type = Maildir
path = ~samantha/Mail/archive/copies/
user = samantha
[info]
type = MDA_external
path = /path/to/infologger
arguments = ('--log=/var/log/mail/info', '--sender=%(sender)', '--recipient=%(recipient))
user = log
MultiGuesser compares 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).
MultiGuesser is similar to MultiSorter, except that it does not operate on the 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:
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 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-', '')
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.
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
The filter- 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-. 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-]
Then, include a type string parameter to tell getmail what type of filter. The possible values are:
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; this should be the default mode of operation for any sane filter.
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 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_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:
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
Several examples of different getmail rc configuration are available in the included file getmailrc-examples.
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.
getmail understands the following options:
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
getmail includes helper scripts which allow you to use it to deliver mail from other programs to maildirs or mboxrd files.
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.
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/
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.
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