                    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:
     * getmail version
     * Python version
     * any error message which getmail displayed
     * the output from running getmail with your normal options plus "--dump"
     * if your problem is getmail not determining the proper local recipient,
       please include the output of running getmail with your normal options
       plus "--trace", showing the retrieval of one problematic message.
   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:
     * Delivered-To
     * Envelope-To
     * Apparently-To
     * X-Envelope-To
     * Resent-To
     * Resent-cc
     * Resent-bcc
     * To
     * cc
     * bcc
     * Received
   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:
     * The user getmail is running as doesn't have write permission to the
       mbox file you specified.
     * The path you specified is actually a symlink to the mbox file. getmail
       refuses to deliver to an mbox if it is a symlink. Specify the path to
       the actual file instead.
     * The path you specified doesn't exist. getmail won't create an mbox
       file. `touch` the file first, to create a 0-byte file.
     * The file does not appear to be an mbox file. It has to either start
       with the five character string "From " or be a zero-length file. The
       mboxrd specification demands this.

    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:
     * Have the POP3 server record the envelope recipient address in a header
       field (like qmail does with Delivered-To:), and then use local
       directives and the recipient_header directive to tell getmail to sort
       mail based on this information.
     * Use the eliminate_duplicates directive.

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. 
