getmail Frequently Asked Questions (FAQ)

These are the Frequently Asked Questions about getmail. If your question is not answered here or in the documentation, please subscribe to the mailing list.

About this document

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.

Table of Contents

  1. About getmail
  2. Error messages
  3. getmail configuration
  4. Other errors
  5. How do I ...

About getmail

What is getmail?

getmail is a POP3 mail retriever, with support for both ordinary and domain (or multidrop) POP3 mailboxes. It is written in Python, and licensed under the GNU General Public License version 2.

Why did you write getmail? Why not just use fetchmail?

I do not like some of the design choices which were made with fetchmail. getmail does things a little differently, and for my purposes, better. In addition, most people find getmail easier to configure and use than fetchmail. Perhaps most importantly, getmail cannot lose retrieved mail, while fetchmail (in its default configuration) can.

In addition, all fetchmail versions released before 20 June 2001 contain a buffer overflow, which can be remotely exploited (see www.securityfocus.com/bid/2877 for details). getmail is not vulnerable to buffer overflows, because buffers in Python are dynamically sized.

How can I get support for getmail?

getmail is Free Software. As such, it comes with no warranty. However, I will do my best to support getmail on a voluntary basis through the getmail mailing list. If you are using getmail in a commercial or other environment where problems cost money, consider contacting me privately for commercial support.

If you have questions about getmail, the first step is to read the documentation, and the remainder of the Frequently Asked Questions. If your question isn't answered there, search the getmail mailing list archives at http://marc.theaimsgroup.com/?l=getmail&r=1&w=2.

If you still haven't found an answer to your question, please subscribe to the mailing list by sending a blank email to <getmail-subscribe @ discworld.dnsalias.org>. If you post your question there, I will see it. As an additional bonus, your question may be answered by another member of the list.

I think I found a bug! How do I report it?

Ideally, you should join the mailing list. Send your bug report there. You should include the following information: If you absolutely cannot sign up for the mailing list, send the report to me directly. I may not be able to respond to all reports privately, but I will try to address any bugs I find out about this way.

Does getmail rewrite mail headers when it retrieves mail?

No -- rewriting message header fields is bad. getmail will add a new Received: header field and a new Delivered-To: header field, but does not rewrite existing headers. You can disable the creation of these header fields.

How does getmail decide what local recipients to deliver a message to?

getmail first extracts everything it can find which looks like an email address in certain headers in the message. It then compares each address in that list to any configured local recipient address patterns. Any of these that match get exactly one copy of the message, even if they match multiple addresses. If none match, it is delivered to the default delivery instruction (postmaster directive).

The default headers that getmail examines for addresses are: These can be changed with the recipient_header directive.

Error Messages

getmail complains about "incomplete format string" ...

Double any percent signs you have in your getmailrc file -- i.e., if your password is "foo%bar", then actually specify it as "foo%%bar".

getmail complains about "error in getmailrc file (expected option value, got ... )"

You have a syntax error in your getmailrc file. Empty option values are not allowed. If you want to specify an empty string as an option value, you have to quote it:
foo = ""

getmail complains about "Error reading default getmailrc file", but I've checked everything and it's fine. What's wrong?

What version of Python are you running? Versions earlier than 1.5.2 can cause this problem. Upgrade to Python 1.5.2 or later.

getmail complains about "configuration error in getmailrc file (/path/to/getmailrc): file is group- or world-writable". What's wrong?

Your getmailrc configuration file is group- or world-writable. For security reasons, getmail refuses to run with a group- or world-writable getmailrc file. Change the permissions on that file.

When I start getmail, I get the error "SyntaxWarning: name 'timeoutsocket' is assigned to before global declaration". What's wrong?

Nothing -- it's a warning, not an error. This is a check for certain possible problems by the Python interpreter in Python version 2.0 and above. In this case, the test is wrong. To skip the test, add "-W ignore" to the invocation of Python. Change the wrapper script included with getmail to do this. Thanks to Errol Casey for the tip on this.

My 'net connection is via PPP/SLIP/modem, and when it's down, my cron'd getmail throws an "error: host not found" exception.

Upgrade to the latest version of getmail to solve this problem.

getmail configuration

What is a "domain mailbox"?

A domain (or multidrop) mailbox is a POP3 mailbox which receives mail for all users in a given domain. Normal mailboxes contain mail for a single user (like jason@myisp.co.uk); some Internet Service Providers which provide webhosting or other services will provide a POP3 mailbox which receives mail for all addresses in a given domain (i.e. mail for service@smallcompany.net, sales@smallcompany.net, and indeed anything@smallcompany.net ends up in the same POP3 mailbox).

getmail provides a method of retrieving mail from a domain mailbox and distributing it among the various users automatically. See the documentation sections on header field pattern matching delivery targets, recipient header field specification, default delivery target, and POP3 domain mailboxes.

Do I have to run sendmail or another MTA to use getmail?

No. getmail delivers directly to Maildirs, mboxes, or via arbitrary MDAs, and never injects mail via SMTP, so no MTA is necessary. P.S. If you're currently running sendmail, consider switching to qmail if you need a full MTA, or nullmailer if you relay all your mail through your ISP's smarthost. Both of them are better and more secure than sendmail.

I've got a simple POP3 account. Do I need "local=..." configuration variables?

No, you don't need them. They might be useful to you if the MTA on the POP3 server supports extension addresses (i.e. qmail). But in general, you will only need to use a postmaster directive.

Other getmail errors

I've configured getmail to deliver to my Maildir, but it won't do it. Why?

Double-check your getmailrc file. Starting with version 2.0, Maildir specifications must include a trailing slash. For example,
postmaster = /home/adam/Maildir
is incorrect (getmail will think this is an mbox delivery target). The correct method is:
postmaster = /home/adam/Maildir/

I've configured getmail to deliver to my mbox file, but it won't do it. Why?

The problem is one or more of the following:

I've configured getmail to deliver to a command (external MDA), but it complains that the command exited 0 but wrote to stderr. Why?

Command deliveries must exit 0 and not write anything to stderr to be considered a successful delivery. If you know your MDA can write to stderr on success, give your command a --quiet option (if it supports it) or discard or redirect stderr in the command specification of the delivery target.

Why does getmail retrieve all my messages when I've told it to only retrieve new mail?

Your POP3 mail server is probably broken. getmail requires that the server support the POP3 UIDL command to uniquely identify messages. If the server doesn't support it, getmail cannot tell which messages it has already seen, and therefore retrieves all messages.

getmail delivered two copies of the same message to one delivery target!

No, it didn't. What happened was that there were two almost-identical messages retrieved from the POP3 mailbox. The target received one copy of each of the two messages. This will happen if the mailbox is a domain mailbox, and the same address is specified in To: and cc: or bcc: recipients by the original message sender. If you wish to suppress the duplicates, there are two methods:

How do I ...

How do I stop getmail adding a Delivered-To: header to email?

Use the no_delivered_to configuration directive.

How do I stop getmail adding a Received: header to email?

Use the no_received configuration directive.

How do I make getmail deliver messages to a program?

As of version 2.1.0, getmail can deliver messages to a program (pipe delivery). Specify the delivery target as "|path-to-command". You should probably use full paths (e.g. "/usr/bin/maildrop"). As a basic security precaution, getmail will refuse to deliver to programs if it is running as root.
Warning: if you don't know what you're doing, you can shoot yourself in the foot with this option.

How do I make getmail deliver messages by re-injecting with SMTP?

You don't. getmail doesn't do this, to prevent lost mail, mail loops, and bounces if getmail or your Mail Transfer Agent is misconfigured. getmail has native support for delivering to qmail-style Maildirs and mboxrd-format mbox files, as well as to commands (pipe delivery). Therefore you shouldn't need to re-inject retrieved messages. Note that advanced users might read this and get ideas.

How do I run getmail in "daemon" mode?

Use your system's cron utility to run getmail periodically if you wish to have mail retrieved automatically at intervals. This is precisely what cron is designed to do; there's no need to add special code to getmail to do this.

How do I use TMDA with getmail?

TMDA is the Tagged Message Delivery Agent, an excercise in preventing spam from ever reaching your inbox.

To make getmail export the environment variables which TMDA needs, you must use local directives in your getmailrc file. You can then optionally set the extension_sep and extension_depth directives.

For example, if getmail determines the envelope recipient to be domain-user-ext1-ext2@otherdomain.tld, extension_sep is set to -, and extension_depth is set to 1, then getmail will set EXT to user-ext1-ext2. If extension_depth is 2, it will instead set EXT to ext1-ext2.

You will then need a wrapper around TMDA to use in a command delivery target which conditionally delivers the message based on TMDA's exit code. getmail does not include such a wrapper; you will need to write it or find it yourself.

Note that getmail will only be able to determine the envelope recipient address (and extension part of that address) reliably if the MTA at the POP3 server is configured to record the envelope recipient in a message header field (i.e. as qmail does with Delivered-To:), and you have configured getmail to only look at that header field with the recipient_header directive.