Fetchmail is a program that can retrieve email from remote servers for on-demand TCP/IP connections. Many users appreciate the ability to separate the process of downloading their messages located on a remote server from the process of reading and organizing their email in an MUA. Designed with the needs of dial-up users in mind, Fetchmail will connect and quickly download all of your email messages to your mail spool file using any number of protocols, including the POP3 and IMAP. It can even forward your email messages to an SMTP server, if necessary.

Before attempting to use Fetchmail, be sure that it is installed on your system. If it is not, you can install it using the fetchmail RPM on the Red Hat Linux CD-ROMs.

Fetchmail is configured for each user through the use of a .fetchmailrc file in the user's home directory. A program bundled with Fetchmail, called fetchmailconf, is very helpful for configuring a basic .fetchmailrc file that you can customize at will.

Using preferences in the .fetchmailrc file, Fetchmail will check for email on a remote server and pull it off, attempting to deliver it to port 25 on the local machine, using the local MTA to place the email in the correct user's spool file. If Procmail is available, it can then be utilized to filter the email and place it in a mailbox so that it can be read by an MUA.

Fetchmail Configuration Options

Although it is possible to pass all options on the command line necessary to check for email on a remote server when executing Fetchmail, using a .fetchmailrc file is much easier. All of your configuration options go in the .fetchmailrc file, but you can override them at the time Fetchmail is run by specifying that option on the command line.

A user's .fetchmailrc file is divided into three particular types of configuration options:

Global options go at the top of the .fetchmailrc file, followed by one or more server options, each of which designate a different email server that Fetchmail should check. User options follow server options for each user account you would like to check on that email server. Like server options, multiple user options may be specified for use with a particular server, such as when you would like to check multiple email accounts on the same server.

Server options are called into service in the .fetchmailrc file by the use of a special option verb, poll or skip, that precedes any of the server information. The poll action tells Fetchmail to use this server option when it is run, which actually checks it for email using the various user options. Any server options after a skip action, however, are not checked unless you specify this server's hostname when Fetchmail is invoked. The skip option allows you to set up test configurations in .fetchmailrc and only check using that server when specifically desired, without affecting any currently working configurations.

A sample .fetchmailrc file looks like this:

set postmaster "user1"
set bouncemail

poll pop.domain.com proto pop3
     user 'user1' there with password 'secret' is user1 here

poll mail.domain2.com
     user 'user5' there with password 'secret2' is user1 here
     user 'user7' there with password 'secret3' is user1 here

Figure 16-6. Example of a basic .fetchmailrc file

In this example, the global are options set so the user is sent email as a last resort (postmaster option) and all email errors are sent to the postmaster instead of the sender (bouncemail option). The set action tells Fetchmail that this line contains a global option. Then, two email servers are specified, one set to check using POP3, and the other for trying various protocols to find one that works. Two users are checked using the second server option, but all email found for any users is sent to user1's mail spool. This allows multiple mailboxes to be checked on multiple servers, while appearing in a single MUA inbox. Each user's specific information begins with the user action.


You do not have to place your password in the .fetchmailrc file. You can omit the with password '<password>' section. Fetchmail will then ask for your password when it is started with the fetchmail command.

While you can set up your .fetchmailrc file manually, it is much easier to let the included fetchmailconf program do it for you. However, when testing new configurations, it is usually easier to edit the .fetchmailrc file directly.

As expected with a program that services such a mature network service as email and utilizes so many protocols, Fetchmail contains many different global, server, and local options. Many of these options are rarely used or only apply to very specific situations. The fetchmail man page explains each of these options in detail, but the most common ones are listed here.

Global Options

Each global option should be placed on a single line after a set action.

  • daemon <seconds> — Tells Fetchmail to automatically use daemon-mode, where it will stay in the background and poll for mail at the interval specified.

  • postmaster — Gives Fetchmail a local user to send mail to in case of delivery problems.

  • syslog — Tells Fetchmail to start logging error and status messages in the system's log file. By default, this is /var/log/maillog.

Server Options

Place server options on their own line in .fetchmailrc after a poll or skip action.

  • auth <auth-type> — Specifies the type of authentication to be used. By default, password authentication is utilized, but some protocols support other types of authentication, including kerberos_v5, kerberos_v4, and ssh. If the any authentication type is used, Fetchmail will first try methods that do not require a password, then methods that mask your password, and finally attempt to send your password in the clear to authenticate to the server.

  • interval <number> — Tells Fetchmail to only poll this server every <number> of times that it checks for email on all configured servers. This option might be used with email servers where you rarely receive messages.

  • port <port-number> — Overrides the default port number for a specified protocol.

  • proto <protocol> — Tells Fetchmail to use a specific protocol, such as pop3 or imap, to check for messages on this server.

  • timeout <seconds> — Configures Fetchmail to give up after a certain interval of server inactivity. If this value is not set, a default of 300 seconds is assumed.

User Options

User options may be placed on their own lines beneath a server option or on the same line as the server option. In either case, the user options follow the user option (defined below).

  • fetchall — Orders Fetchmail to download all messages in the queue, including messages that have already been viewed. By default, Fetchmail only pulls down new messages.

  • fetchlimit <number> — Only allows a certain number of messages to be retrieved before stopping.

  • flush — Tells Fetchmail to delete all previously viewed messages in the queue before retrieving new messages.

  • limit <max-number-bytes> — Allows you to specify that only messages below a particular size may be retrieved. This option is useful with slow network links, when a large message will take too long to download.

  • password '<password>' — Specifies the password to be used for this user.

  • preconnect "<command>" — Tells Fetchmail to execute the specified command before retrieving messages for this user.

  • postconnect "<command>" — Tells Fetchmail to execute the specified command after retrieving messages for this user.

  • ssl — Allows Fetchmail to collect the message via an encrypted SSL connection, if the server supports this.

  • user "<username>" — Sets the username used by Fetchmail to retrieve messages. This option should be listed before any other user options.

Fetchmail Command Options

Most of the Fetchmail options that may be used on the command line, when executing the fetchmail command, mirror the .fetchmailrc configuration options. This is done so that Fetchmail may be used with or without a configuration file. Most users will not use these options on the command line, as it is easier to leave them in the .fetchmailrc file to be utilized whenever Fetchmail is run.

However, there are times when you may want to run the fetchmail command with other options for a particular purpose. As any options specified at the command line override configuration file options, you can also issue command options to temporarily override a .fetchmailrc setting that is causing an error.

Informational or Debugging Options

Certain options used after the fetchmail command can provide you with important information.

  • --configdump — Displays every possible option based on information from .fetchmailrc and Fetchmail defaults. No email is retrieved for any users when using this option.

  • -s — Executes Fetchmail in silent mode, preventing any messages, other than errors, from appearing after the fetchmail command.

  • -v — Executes Fetchmail in verbose mode, displaying every communication between Fetchmail and the remote email servers.

  • -V — Causes Fetchmail to display detailed version information, list its global options, and show settings to be used with each user, including the email protocol and authentication method. No email is retrieved for any users when using this option.

Special Options

These options are occasionally useful for overriding defaults often found in the .fetchmailrc file.

  • -a — Tells Fetchmail to download all messages from the remote email server, whether new or previously viewed. By default, Fetchmail will only download new messages.

  • -k — Causes Fetchmail to leave the messages on the remote email server after downloading them. This option overrides the default behavior of deleting messages after downloading them.

  • -l <max-number-bytes> — Tells Fetchmail to not download any messages over a particular size and leave them on the remote email server.

  • --quit — Quits the Fetchmail daemon process.

More commands and .fetchmailrc options can be found on the fetchmail man page.