This is the formal documentation for getmail. If your question is not
answered here or in the Frequently Asked Questions,
please subscribe to the mailing list.
The official location of this document is
http://www.qcc.ca/~charlesc/software/getmail-2.0/docs.html.
For easy navigation, all headings in the HTML version of this document are
links to their parent heading.
Fredrik Steen, maintainer of the Debian package for getmail, has written a
man page for getmail. It is available at http://people.debian.org/~stone/getmail/manpage/getmail.1.
-
Installing getmail
-
Configuring getmail
-
getmailrc directives
-
Running getmail
-
Commandline options
-
Download getmail.
-
Unpack the tarball:
tar xzf getmail-version.tar.gz
-
Copy the contents to a suitable location:
mkdir /usr/lib/getmail
cp -a getmail-version/* /usr/lib/getmail/
You can install getmail in your home directory or elsewhere
if you prefer.
-
Copy the getmail helper script to a location in your PATH, and
ensure it is executable:
cp -a getmail-version/getmail /usr/bin/
chmod 755 /usr/bin/getmail
If you used an installation path other than that in step 3 above,
edit the value of GETMAILDIR in this file.
-
Create a getmail configuration/data directory in your
home directory:
mkdir ~/.getmail
You can use another path or directory name, but getmail
assumes this name by default. If you choose something
different, you will need to specify its name on the getmail
command line with the --getmaildir
option.
-
Create a configuration file named getmailrc in the directory you
created in step 1 above. You can use another file name or path, but
getmail assumes this name by default. If you choose something
different, you will need to specify its name on the getmail command
line with the --rcfile option.
See the section Configuration file below
for details.
A getmail configuration file (typically named getmailrc,
and located in $HOME/.getmail/) looks similar to an MS-Windows .INI
file. For security reasons, your getmailrc file must not be group- or world-writable.
getmail will refuse to run if it finds your getmailrc file is writable by
others.
The file is broken into sections; the special section
"[default]" supplies default values for various options. Each
additional section describes one POP3 mailbox you wish to retrieve mail
from, and how to deliver mail to local users.
Each section starts with a label enclosed in square brackets:
[section name]
This is then followed by lines in the format of name = value:
option_name = option_value
Option values that contain a percent sign (%) must be escaped with another
percent sign. For instance, this:
user = jeffj%domain.tld
is not valid. Instead, you would specify it like this:
user = jeffj%%domain.tld
getmail ignores whitespace surrounding the "=" sign. The following
lines are equivalent:
account = joe.bloggs
account=joe.bloggs
account= joe.bloggs
The "#" symbol starts a comment; everything after it on the line
is ignored. You can use this to keep notes to yourself in your getmailrc
file:
account = jeff.friesen:mymail.example.net # This virtual host needs ':' instead of '@'
Option values containing whitespace must be quoted with either single or double quotes:
password = "long password containing spaces"
password = 'long password containing spaces'
Option values containing single or double quote characters can be quoted with
the other character:
password = "this is a more 'secure' password"
password = 'joe "bloggy" bloggs'
To un-set an option taking a string value, set it to the empty string:
message_log = "" # Previously set to /var/log/getmail; turn it off for this account
A getmail configuration file must begin with a [default]
section. Options which are set in this section will serve as default values
for the rest of the sections in the file; they can be overridden for a later
section by specifying the same option with a different value. An example
[default] section might look like this:
[default]
verbose = 1 # Print status messages to stdout
timeout = 120 # We're on a good network; time out POP3 connections after 120 seconds
readall = 0 # Only retrieve new messages
delete = 0 # But don't delete them from the server when we're done
message_log = /var/log/getmail # Log retrieval and delivery here
Other sections in a getmail configuration file represent POP3 accounts
to retrieve mail from, one per account. The section name is unimportant,
but must be unique. An example account section might look like this:
[Home ISP account]
server = mailhost.isp.tld
username = brenda.bjorn
password = "my mail password"
postmaster = ~brendab/Maildir/ # Deliver all mail to the Maildir in my home directory
When getmail tries to determine the value of an option, it looks at the
following, in order:
- Options specified on the command line
- Options specified in an account section of the getmail configuration file
- Options specified in the [default] section of the getmail configuration file
- getmail's built-in default value
The first match determines getmail's behaviour. To demonstrate, we'll
examine a fairly complex getmailrc:[default]
verbose = 0
timeout = 120
readall = 1
delete = 1
message_log = ""
postmaster = ~magnus/Mail/postmaster/
[Home account]
server = pop.mail.example.com
port = 8110
timeout = 600
account = magnus.leitner
password = "F45 82dLa"
readall = 0
delete = 0
postmaster = ~magnus/Mail/personal/
verbose = 1
[Work account 1]
server = vhost.example.net
account = smallcompany
password = "trailing_spaces "
local = info@company.net,~bob/Mail/info
local = sales@company.net,~bob/Mail/sales
local = bob.jackson@company.net,~bob/Mail/mbox
local = marcia.smith@company.net,~marcia/Mail/mbox
local = magnus.leitner@company.net,~magnus/Mail/inbox/
[Work account 2]
server = mail.company.tld
account = othercompany
password = FHj873k34l
local = info@othercompany.net,~magnus/Mail/info/
local = sales@othercompany.net,~magnus/Mail/sales/
local = magnus.leitner@company.net,~magnus/Mail/inbox/
In this example, getmail will:
-
operate in quiet mode when retrieving mail from
Work account 1 and Work
account 2, but verbose mode when retrieving mail from Home account.
-
Retrieve all mail from the two work accounts, deleting it from the
server after retrieval. From the home account, it will retrieve
only new mail, and will leave it on the server after delivery.
-
All mail from work account 2 is being delivered to user Magnus;
however, local directives with patterns are being used to
sort mail into various sub-folders.
-
The POP3 servers for the two work accounts run on the default
POP3 port (110). The home account server is running on port 8110.
There are other values that differ between the configurations as well.
For details on the configuration directives that can be used in a getmail
configuration file, see the section on Configuration Directives.
There are two different types of POP3 email accounts: regular mailboxes,
and domain mailboxes.
This is a typical POP3 mailbox provided by an ISP for a single user. It
receives mail addressed to
a single user (say, shannon.fotheringham@aqua.myisp.tld).
For this type of account, the minimum configuration would be something like
this:[My Aqua Account]
server = mailhost.aqua.myisp.tld
username = shannon.fotheringham
postmaster = ~shannonf/Maildir/
This postmaster directive tells getmail to deliver
all mail to Shannon's Maildir. Since a password was not configured, getmail
will prompt the user for it when run.
This type of POP3 account is typically provided by an ISP to a small company
or organization. It receives mail addressed to any user in a given domain
-- for example, mail to info@smallcompany.tld,
tgrieg@smallcompany.tld, and
sales@smallcompany.tld all ends up in the same
POP3 domain mailbox. getmail includes features to enable retrieval of
mail from this type of account, filter it according to who the mail was
addressed to, and deliver it to different destinations. A minimal
configuration with this type of setup would be something like
this:[Company domain mailbox]
server = mailhost.largeisp.tld
username = small.company
password = RRt49slP32m
postmaster = ~tgrieg/Mail/postmaster-maildir/
local = tgrieg@smallcompany.tld,~tgrieg/Mail/personal-maildir/
local = info@smallcompany.tld,~bobf/Maildir/
local = sales@smallcompany.tld,~darlab/mbox
The local directives tell getmail to deliver
mail for those users to their various mail spools on the system, and the
postmaster directive tells getmail to deliver any
mail which doesn't match any of the local directives somewhere else.
In a getmailrc file, postmaster and
local directives contain message delivery
targets, which instruct getmail to delivery messages in a particular manner.
A message delivery target may be a qmail-style Maildir, an mboxrd-style mbox
file, or an arbitrary command (such as an external Message Delivery Agent or
MDA).
Target Type | Syntax | Notes |
Maildir | /path/to/Maildir/ | Maildir targets must have a trailing slash |
mbox | /path/to/mbox | getmail expects mboxrd-style mbox files |
Command | |/path/to/command [arguments] | Command deliveries must start with a pipe (|). Remember to quote values containing whitespace. |
For command deliveries, getmail provides the following environment variable:
-
SENDER contains the envelope sender address
as extracted from the Return-Path: header field, or "#@[]"
if not found or empty.
If you are using local directives
for message filtering, getmail also provides the following environment
variables for command deliveries:
-
RECIPIENT contains the envelope recipient
address as extracted from the header fields configured with the
recipient_header
directives.
-
EXT contains the extension part of a
user extension address (if any) as configured by the
extension_sep and
extension_depth directives.
Note the following restrictions:
Leading tilde characters (~) on paths will be expanded -- i.e. ~jason/Maildir/ likely
becomes /home/jason/Maildir/ on most systems.
getmail understands the following getmailrc directives:
Directive | Optional? | Default | Summary |
server | No | None | POP3 server hostname |
port | Yes | 110 | POP3 server TCP port number |
timeout | Yes | 180 seconds | POP3 server TCP timeout |
username | No | None | POP3 account username |
password | Yes | Prompt for password | POP3 account password |
use_apop | Yes | 0 (No) | Use POP3 APOP authentication if available |
no_delivered_to | Yes | 0 (No) | Suppress addition of Delivered-To: header field |
no_received | Yes | 0 (No) | Suppress addition of Received: header field |
postmaster | No | None | Default message delivery target |
local | Yes | None | Header field pattern-matching delivery target |
recipient_header | Yes | Delivered-To, Envelope-To, Apparently-To, X-Envelope-To, Resent-To, Resent-cc, Resent-bcc, To, cc, bcc, Received | Extract recipient names from listed mail header fields |
relaxed_address_match | Yes | 0 | Allow looser or more relaxed matching of email addresses. |
extension_sep | Yes | - | User extension address separator character |
extension_depth | Yes | 1 | User extension address base length |
readall | Yes | 1 (Yes) | Retrieve all messages, or only previously unseen messages |
max_message_size | Yes | 0 (No limit) | Do not retrieve messages larger than this setting |
max_messages_per_session | Yes | 0 (No limit) | Do not retrieve more than X messages |
eliminate_duplicates | Yes | 0 (No) | Eliminate duplicate messages from POP3 mailbox |
delete | Yes | 0 (No) | Delete messages after retrieval |
delete_after | Yes | 0 (No) | Delete messages X days after retrieval |
verbose | Yes | 1 (Yes) | Show status messages while running |
message_log | Yes | None | Log message retrieval and delivery to file |
The following directives are specified in getmailrc sections other than
[default], and are used to configure which POP3 servers getmail will
retrieve mail from.
Function
|
Specify POP3 server to connect to.
|
Syntax
|
server = hostname.domain.tld
|
Optional
|
No
|
Default
|
None
|
Commandline equivalent
|
None
|
Examples
|
server = pop3.isp.com
|
Function
|
Specify TCP port on POP3 server to connect to.
|
Syntax
|
port = portnumber
|
Optional
|
Yes
|
Default
|
110 (Default POP3 port)
|
Commandline equivalent
|
None
|
Examples
|
port = 8110
|
Function
|
Specify the TCP timeout to use with an account.
|
Syntax
|
timeout = value (seconds)
|
Optional
|
Yes
|
Default
|
180
|
Commandline equivalent
|
--timeout = value (seconds)
|
Examples
|
timeout = 360
|
Note
|
The TCP timeout capabilities are enabled by the
timeoutsocket.py module by Timothy O'Malley. A copy of
timeoutsocket.py is included with getmail; however, getmail
will continue to function (without this capability) if
the timeoutsocket module is not present.
timeoutsocket.py Copyright 2000,2001 by Timothy O'Malley <timo@alum.mit.edu>
All Rights Reserved
Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Timothy O'Malley not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.
Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
|
The following directives are specified in getmailrc sections other than
[default], and are used to configure which POP3 accounts getmail will
retrieve mail from.
Function
|
Specify the account name for the POP3 server.
|
Syntax
|
username = user
|
Optional
|
No
|
Default
|
None
|
Commandline equivalent
|
None
|
Examples
|
username = joe.bloggs
username = joe.bloggs:vhost.example.net
|
Function
|
Specify password to use with POP3 account
|
Syntax
|
password = password
|
Optional
|
Yes
|
Default
|
Prompt for password
|
Commandline equivalent
|
None
|
Examples
|
password = "long password containing whitespace"
password = foo_bar
|
Function
|
Use POP3 APOP authentication if available. Falls back to
USER/PASS authentication if not supported.
|
Syntax
|
use_apop = bool
|
Optional
|
Yes
|
Default
|
0 (USER/PASS authentication)
|
Commandline equivalent
|
None
|
Examples
|
use_apop = 1
use_apop = 0
|
The following directives are specified in any getmailrc section, and are
used to configure how getmail will format messages that it retrieves.
Function
|
Suppress the addition of a Delivered-To: header field to messages
that getmail retrieves.
|
Syntax
|
no_delivered_to = bool
|
Optional
|
Yes
|
Default
|
0 (No)
|
Commandline equivalent
|
None
|
Examples
|
no_delivered_to = 1
no_delivered_to = 0
|
Function
|
Suppress the addition of a Received: header field to messages
that getmail retrieves.
|
Syntax
|
no_received = bool
|
Optional
|
Yes
|
Default
|
0 (No)
|
Commandline equivalent
|
None
|
Examples
|
no_received = 1
no_received = 0
|
The following directives are specified in any getmailrc section, and are
used to configure where getmail will deliver retrieved messages. Also see
the section on message delivery targets.
Function
|
Specify the default delivery target for all retrieved messages which
are not handled by a matching local directive.
|
Syntax
|
postmaster = target
|
Optional
|
No
|
Default
|
None
|
Commandline equivalent
|
None
|
Examples
|
postmaster = /home/joe/Maildir/
postmaster = ~brenda/mbox
postmaster = "|/usr/local/bin/my_mda -f foo -a all -b gone /home/postmaster/.mdarc"
|
Function
|
Specify the destination for retrieved messages which appear to
be addressed to a given user. getmail will match the specified
Perl-compatible extended regular expression against all apparent
email addresses found
in the header fields specified with the recipient_header
directive. If a match is found, the message will be delivered
to the specified target.
If multiple local directives contain matching patterns, each
matching target will receive a copy of the message.
If there are no local directives, or no match is found, the
message will be delivered according to the default delivery target.
If you do not understand Perl-compatible regular expressions,
just use email addresses here. They will work in virtually all
cases.
Use multiple local directives to filter mail retrieved from a
domain mailbox to multiple local user accounts.
|
Syntax
|
local = pattern,target
|
Optional
|
Yes
|
Default
|
None
|
Commandline equivalent
|
None
|
Examples
|
local = joe@isp.tld,~joe/Maildir/
local = brenda@homeisp.tld,/home/brenda/Mail/personal/
local = brenda@workisp.tld,/home/brenda/Mail/work/
local = "^(joe|fred)@company\.(tld|dom.tld)$,|/path/to/mda -opts"
|
Function
|
Extract recipient addresses from listed header field. These
fields will be used to find local recipient email addresses when
using local directives. To
specify multiple recipient header fields, use multiple
recipient_header directives.
This directive is mostly useful if the POP3 server records
envelope recipient addresses in a specific header field
(i.e. Delivered-To: or X-Envelope-To:), and you wish to process
mail from a domain mailbox, sorting and delivering it to
multiple local user accounts using local
directives.
|
Syntax
|
recipient_header = fieldname
|
Optional
|
Yes
|
Default
|
Delivered-To, Envelope-To, Apparently-To, X-Envelope-To,
Resent-To, Resent-cc, Resent-bcc, To, cc, bcc, Received
|
Commandline equivalent
|
None
|
Examples
|
recipient_header = Delivered-To
recipient_header = X-Envelope-To
|
Function
|
Allow looser or more relaxed matching of email addresses.
Set this to 1 to enable. When enabled, any string will
be considered a valid email address; otherwise, it must contain
an at-sign (@), and the domain must contain a dot (.) followed
by arbitrary text.
|
Syntax
|
relaxed_address_match = value
|
Optional
|
Yes
|
Default
|
0 (Stricter matching)
|
Commandline equivalent
|
None
|
Examples
|
relaxed_address_match = 1
relaxed_address_match = 0
|
Function
|
Determine which part of a recipient address is the extension
to the base address.
This directive is mostly useful if the POP3 server records
envelope recipient addresses in a specific header field
(i.e. Delivered-To: or X-Envelope-To:), and you wish to deliver
mail using TMDA or
another filtering MDA.
If you are using a local
directive to configure delivery of mail per-recipient,
getmail will export the detected envelope
recipient address in the environment variable RECIPIENT.
It will then split the local-part of the address at the first
occurrence of this character (default: "-"), and
export anything after it as the environment variable
EXT.
Note that you will still need a wrapper script around your
filtering MDA; getmail will consider a delivery failed if the
MDA returns non-zero. This is left as an excercise for the
reader/user of TMDA.
|
Syntax
|
extension_sep = character
|
Optional
|
Yes
|
Default
|
-
|
Commandline equivalent
|
None
|
Examples
|
extension_sep = +
extension_sep = -
|
Function
|
Determine which part of a recipient address is the extension
to the base address.
This directive is mostly useful if the POP3 server records
envelope recipient addresses in a specific header field
(i.e. Delivered-To: or X-Envelope-To:), and you wish to deliver
mail using TMDA or
another filtering MDA.
If you are using a local
directive to configure delivery of mail per-recipient,
getmail will export the detected envelope
recipient address in the environment variable RECIPIENT.
It will then remove the base part of the address at the
extension_depth occurrence of the
extension separator character.
|
Syntax
|
extension_depth = count
|
Optional
|
Yes
|
Default
|
1
|
Commandline equivalent
|
None
|
Examples
|
extension_depth = 2
|
The following directives are specified in any getmailrc section, and are
used to configure how getmail will retrieve messages.
Function
|
Select whether to retrieve all messages, or only messages which
have previously not been seen by getmail.
|
Syntax
|
readall = bool
|
Optional
|
Yes
|
Default
|
1 (Retrieve all messages)
|
Commandline equivalent
|
--all (readall = 1)
--new (readall = 0)
|
Examples
|
readall = 1
readall = 0
|
Function
|
Specify a maximum message size to retrieve. Messages larger
than this will be left on the server and not retrieved.
|
Syntax
|
max_message_size = value (bytes)
|
Optional
|
Yes
|
Default
|
0 (No limit)
|
Commandline equivalent
|
None
|
Examples
|
max_message_size = 2000000
max_message_size = 150000
|
Function
|
Specify a maximum message size to retrieve. Messages larger
than this will be left on the server and not retrieved.
|
Syntax
|
max_message_size = value (bytes)
|
Optional
|
Yes
|
Default
|
0 (No limit)
|
Commandline equivalent
|
None
|
Examples
|
max_message_size = 2000000
max_message_size = 150000
|
Function
|
When a message is sent to two recipients in the same domain
mailbox, two copies are delivered to the POP3 server. If the
server does not record the envelope recipient in a header field
(such as Delivered-To:), each local recipient may receive two copies of the message
in their mailbox. Enabling eliminate_duplicates will work around
this problem.
Note that the correct solution is to have the POP3 server record
the envelope recipient address in a header field in the message,
and then use the recipient_header
directive to filter only using the contents of that field.
|
Syntax
|
eliminate_duplicates = bool
|
Optional
|
Yes
|
Default
|
0 (Do not eliminate duplicates)
|
Commandline equivalent
|
None
|
Examples
|
eliminate_duplicates = 1
eliminate_duplicates = 0
|
Function
|
Delete messages after retrieval.
|
Syntax
|
delete = bool
|
Optional
|
Yes
|
Default
|
0 (Do not delete)
|
Commandline equivalent
|
--dont-delete (delete = 0)
--delete (delete = 1)
|
Examples
|
delete = 1
delete = 0
|
Function
|
Delete messages a specified number of days after they are first
retrieved.
Note: delete overrides delete_after.
|
Syntax
|
delete_after = value (days)
|
Optional
|
Yes
|
Default
|
0 (Do not use delete_after)
|
Commandline equivalent
|
None
|
Examples
|
delete_after = 3
delete_after = 180
|
The following directives are specified in any getmailrc section, and are
used to control other aspects of getmail's behaviour.
Function
|
Specify whether getmail writes status and informational messages
to stdout while running.
|
Syntax
|
verbose = bool
|
Optional
|
Yes
|
Default
|
1 (Verbose)
|
Commandline equivalent
|
--verbose (verbose = 1)
--quiet (verbose = 0)
|
Examples
|
verbose = 1
verbose = 0
|
Function
|
Specify whether getmail writes message retrieval and delivery
information to a log file. Set to the empty string to
disable logging.
|
Syntax
|
message_log = file
|
Optional
|
Yes
|
Default
|
None
|
Commandline equivalent
|
None
|
Examples
|
message_log = /var/log/getmail
message_log = ""
|
Run the getmail helper script you installed earlier:
getmail
By default, getmail will read in the default getmailrc file
($HOME/.getmail/getmailrc) and begin retrieving mail.
You can also supply commandline options.
For a brief summary of usage and commandline options, run:
getmail --help
getmail understands the following commandline options:
Long Option
|
--help
|
Short Option
|
-h
|
getmailrc equivalent
|
None
|
Function
|
Display usage information, then exit.
|
Long Option
|
--getmaildir path
|
Short Option
|
-g path
|
getmailrc equivalent
|
None
|
Function
|
Use path as getmail configuration/data
directory. Defaults to $HOME/.getmail/
|
Long Option
|
--rcfile filename
|
Short Option
|
-r filename
|
getmailrc equivalent
|
None
|
Function
|
Use filename as getmailrc file.
Defaults to getmailrc in the
getmaildir directory.
|
Long Option
|
--quiet
|
Short Option
|
-q
|
getmailrc equivalent
|
verbose = 0
|
Function
|
Produce output only on error.
|
Long Option
|
--verbose
|
Short Option
|
-v
|
getmailrc equivalent
|
verbose = 1
|
Function
|
Write status and progress messages to stdout.
|
Long Option
|
--message-log file
|
Short Option
|
None
|
getmailrc equivalent
|
message_log = file
|
Function
|
Log message retrieval and delivery information to file.
|
Long Option
|
--all
|
Short Option
|
-a
|
getmailrc equivalent
|
readall = 1
|
Function
|
Retrieve all messages.
|
Long Option
|
--new
|
Short Option
|
-n
|
getmailrc equivalent
|
readall = 0
|
Function
|
Retrieve only previously unseen messages.
|
Long Option
|
--delete
|
Short Option
|
-d
|
getmailrc equivalent
|
delete = 1
|
Function
|
Delete messages from server after retrieval.
|
Long Option
|
--dont-delete
|
Short Option
|
-l
|
getmailrc equivalent
|
delete = 0
|
Function
|
Leave messages on server after retrieval.
|
Long Option
|
--timeout value (seconds)
|
Short Option
|
-t value (seconds)
|
getmailrc equivalent
|
timeout = value (seconds)
|
Function
|
Set TCP timeout to value seconds.
|
Long Option
|
--trace
|
Short Option
|
None
|
getmailrc equivalent
|
None
|
Function
|
Write verbose debugging information to stdout.
|
Long Option
|
--dump
|
Short Option
|
None
|
getmailrc equivalent
|
None
|
Function
|
Do not retrieve mail; read getmailrc file and commandline options,
then print configuration on stdout. This information should
be included in all bug reports or support requests.
|