
getmail FAQ

   The following are Frequently Asked Questions about getmail. If your
   question is not answered here, and is not answered in the
   documentation, please subscribe to the mailing list.
     _________________________________________________________________
   
  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.
   
  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.
   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, 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 cannot sign up for the mailing list, send the report to me
   directly.
   
  What is a "domain mailbox"?
  
   A domain (or multidrop) mailbox is a POP3 mailbox which holds 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 contains mail for all addresses in a given domain
   (like "service@smallcompany.net" and "sales@smallcompany.net").
   getmail provides a method of retrieving mail from a domain mailbox and
   distributing it among the various users automatically.
   
  Do I have to run sendmail or another MTA to use getmail?
  
   No. getmail delivers directly to Maildirs or mboxes, and does not
   inject 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 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. The correct method is:
   postmaster = /home/adam/Maildir/
   
  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 doesn't work if I specify an empty option value ...
  
   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 says it can't find my default config file (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 refuses to run, saying "file is group- or world-writable". What's
  wrong?
  
   Your getmailrc configuration file is group- or world-writable. That's
   a no-no. 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. 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.
   
  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 a "postmaster=..." configuration.
   
  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.
       
  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.
   
  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.
   
  My 'net connection is via PPP/SLIP/modem, and when it's down, my cron'd
  getmail throws a "error: host not found" exception.
  
   Upgrade to the latest version of getmail to solve this problem.
   
  Does getmail rewrite mail headers when it retrieves mail?
  
   No. getmail will add a new Received: header and a new Delivered-To:
   header, but does not rewrite existing headers.
   
  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.
   
  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
       
   As of version 2.0.15, these can be changed with the recipient_header
   directive.
   
  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.
   
  How do I run getmail in "daemon" mode?
  
   Use cron to run getmail periodically if you wish. I may add native
   support for a daemon mode to getmail in the future; the complete
   rewrite for version 2.0 made allowances for this.
   
  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.
   
  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 strings in Python are dynamically sized
   and do not rely on ASCII NUL to terminate them.
