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.
This section of the documentation is to be added to as getmail version 4 progresses through beta testing to release state. If you have suggestions for additions or changes to this documentation, please send them to the mailing list or me.
getmail may output various diagnostic error messages. The common ones and their meanings are given below.
You tried to run getmail 4 with a version of Python prior to Python 2.3.3. This is unsupported. If you cannot install a newer Python alongside your current version, please use getmail version 3, which supports Python 1.5.2 and later.
getmail detected an error in your configuration. Check your getmail rc file(s). getmail will do its best to point out the exact cause of the error. Some of the specific errors it may find include the following.
A class object in your getmail rc file requires the parameter , but it was not found in the appropriate section of the file.
The configuration parameter must be of type , but the supplied value does not appear to be of that type. Further information may be present in .
The getmail documentation contains descriptions of the syntax for each parameter type.
Maildir paths must start with dot or slash and end with a slash.
The specified maildir path does not appear to be a valid maildir. Check to ensure that it is a valid maildir, and that getmail has permission to write to it.
The specified mboxrd path does not appear to be a valid mboxrd file. To avoid corrupting files in the event of a user typo, getmail will not deliver messages to files that do not appear to be valid mboxrd files.
The specified mboxrd does not exist. getmail will not create mbox files; ensure they exist before trying to deliver to them.
In a multidrop retriever configuration, you specified that the envelope recipient was recorded in a header field that getmail knows does not actually record that information.
By default, getmail will not invoke external commands (in destinations or filters) when it is running with root privileges, for security reasons. See the documenation for possible solutions.
An external command was specified as being located at path , but the command executable was not found at that location.
A specified external command at path was found to not be an executable file.
A destination in the getmail rc file refers to another rc file section named , but that section was not found in the file.
getmail detected an error after retrieving a message but before delivery was successfully completed. Some of the specific errors it may find include the following.
getmail will not deliver to a maildir as the root user. You may specify an alternate user to deliver as with the user directive in the destination section of your getmailrc file, or let getmail default to the user who is the owner of the maildir.
getmail will not deliver to an mbox file as the root user. You may specify an alternate user to deliver as with the user directive in the destination section of your getmailrc file, or let getmail default to the user who is the owner of the mbox file.
The specified mbox file does not appear to be a valid mbox file.
getmail detected an operational error. getmail will do its best to point out the exact cause of the error. Common causes are failures to connect to a remote mail server, timeouts during network operations, and other transient failures.
getmail may output various diagnostic warning messages. The common ones and their meanings are given below.
getmail detected a condition which might be problematic. Some of the specific warnings it may find include the following.
A getmail rc file contained an unknown parameter. This usually indicates that you've put the parameter in the wrong section of the file (such as putting the read_all parameter in the [retriever] section instead of in the [options] section).
A message filter appeared to incorrectly remove header fields from the header of a message which it handled. getmail warns you about this so that you can check your filter for proper operation. Filters should add information to the message header or leave it alone; check the configuration for the filter program you are using.
If getmail is behaving in a manner other that you expected, see the following sections.
If getmail records a hostname other than the "right" one for your host (in its Received: trace header fields), check your /etc/hosts file and make sure the "right" name is the first hostname listed for any of the addresses of the machine.
getmail records the envelope recipient address in the Delivered-To: header field, and the envelope sender in the Return-Path: header field. If this information is not available (because you're not using a multidrop retriever class, or the MTA on the POP/IMAP server is broken, for example), getmail uses the string "unknown". You can disable the creation of the Delivered-To: header field if you wish.
The %(recipient), %(local), and %(domain) replacement strings are only replaced if the message is retrieved with a multidrop retriever class; otherwise, getmail does not "know" the recipient address of the message, and therefore cannot perform this replacement.
If getmail takes more than a few seconds to initialize, run the following command to test:
python -c "import socket; print socket.getfqdn()"
If this seems to take a similarly long period of time to complete, the delay is in finding the fully-qualified hostname of your system. The fix is to ensure you have a valid mapping of address-to-hostname for all the addresses in your system. You can do this in your /etc/hosts file, in your authoritative content DNS server, or in another system-specific manner — please contact your OS vendor (or its public support mailing list) for assistance.