This manual was last updated June 6, 2007 for version 1.0.10 of mpop.
Copyright (C) 2005, 2006, 2007 Martin Lambers
This program, including this manual, is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.This program, including this manual, is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
mpop is a POP3 client.
In its default mode of operation, it retrieves mails from one or more POP3 mailboxes, optionally does some filtering, and delivers them through a mail delivery agent (MDA) or to maildir folders or mbox files. Mails that were successfully delivered before will not be retrieved a second time, even if errors occur or mpop is terminated in the middle of a session.
The best way to start is probably to have a look at the Examples section. See Examples.
In addition to the mail retrieval mode, mpop can be used in server information mode. In this mode, mpop prints as much information as it can get about a given POP3 server (greeting, supported features, login delay, maximum mail size, ...).
Normally, a configuration file contains information about which POP3 server to use and how to use it, but almost all settings can also be configured on the command line.
POP3 server information is organized in accounts. Each account describes one POP3 server: host name, authentication settings, TLS settings, and so on. Each configuration file can define multiple accounts.
Supported features include:
If it exists and is readable, a user configuration file will be loaded
(~/.mpoprc by default). This file must have no more permissions
than user read/write. Configuration file settings can be changed by command
line options.
A configuration file is a simple text file. Empty lines and comment lines (whose first non-blank character is '#') are ignored. Every other line must contain a command and may contain an argument to that command. The argument may be enclosed in double quotes (").
If the first character of a filename is the tilde (~), this tilde will be
replaced by $HOME.
If a command accepts the argument `on', it also accepts an empty argument and treats that as if it was `on'.
Commands form groups. Each group starts with the `account' command and defines the settings for one POP3 server.
See Examples.
See Authentication.
~/.netrc, and if that fails, will prompt you for it.
See Authentication.
See Mail retrieval mode.
%F in the command will be replaced with the envelope
from address of the current message (or MAILER-DAEMON if none is found). Note
that this address is guaranteed to contain only letters a-z and
A-Z, digits 0-9, and any of .@_-+/, even though that is
only a subset of what is theoretically allowed in a mail address. Other
characters, including those interpreted by the shell, are replaced with
_. Nevertheless, you should put %F into single quotes:
'%F'.delivery mda "/usr/bin/procmail -f '%F' -d $USER" for the procmail
MDA.delivery mda "/usr/sbin/sendmail -oi -oem -f '%F' -- $USER" to let
your MTA handle the mail.delivery mda /usr/local/bin/msmtp --host=localhost --from='%F' --
$USER@`hostname`.`dnsdomainname`" to pass the mail to your MTA via SMTP.
(This is what fetchmail does by default.)
fcntl(2). mpop uses the MBOXRD mbox format variant; see the
documentation of the mbox format.
%F, and the mbox method),
then it needs to create a temporary file to store the mail headers (but not the
body) in. See $TMPDIR in Environment / Files.
%U in the filename will be replaced by the username of the current
account. %H in the filename will be replaced by the hostname of the
current account. If the filename contains directories that do not exist, mpop
will create them. mpop locks this file for exclusive access when accessing the
associated POP3 account.~/.mpop_uidls/%U_at_%H. You can also use a single
UIDLS file for multiple accounts, but then you cannot poll more than one of
these accounts at the same time.
%F in the command will be replaced with the envelope
from address of the current message (or MAILER-DAEMON if none is found).
Note that this address is guaranteed to contain only letters a-z and
A-Z, digits 0-9, and any of .@_-+/, even though that is
only a subset of what is theoretically allowed in a mail address. Other
characters, including those interpreted by the shell, are replaced with
_. Nevertheless, you should put %F into single quotes:
'%F'.%S in the command will be replaced with the size of
the current mail as reported by the POP3 server.sysexits.h error codes may be used to give information about the kind of
the error, but this is not necessary. See Filtering.
mpop [option...] [--] [account...]mpop [option...] --serverinfo [account...]The standard exit codes from sysexits.h are used.
~/.mpoprc'~/.mpop_uidls'~/.netrc'.netrc file contains login information. If a password is not found
in the configuration file, msmtp will search it in .netrc before
prompting the user for it. The syntax of .netrc is described in the
netrc(5) or ftp(1) manual page.
$USER, $LOGNAME'$LOGNAME is only used if
$USER is unset. The user's login name is used for Received
headers.
$TMPDIR'Options override configuration file settings. The following options are accepted:
Most options in this category correspond to a configuration file command. Please refer to Configuration file for detailed information.
~/.mpoprc as the configuration file.
Transport Layer Security (TLS) is a new name for Secure Socket Layer (SSL). The TLS 1.0 protocol is an updated version of the SSL 3.0 protocol. TLS and SSL mean the same thing.
Quoting from RFC2246 - the TLS 1.0 protocol specification:
"The TLS protocol provides communications privacy over the Internet.
The protocol allows client/server applications to communicate in a way that
is designed to prevent eavesdropping, tampering, or message forgery."
POP3 servers can use TLS in one of two modes:
When TLS is started, the server sends a certificate to identify itself. This certificate contains information about the certificate owner, the certificate issuer, and the activation and expiration times of the certificate. This information can be displayed in server information mode. See Server information mode.
To use TLS, it is required to either enable full server certificate verification using the `tls_trust_file' command or `--tls-trust-file' option, or to disable all certificate checks using `tls_certcheck off' or `--tls-certcheck=off'. WARNING: When certificate checks are disabled, TLS/SSL sessions are vulnerable to man-in-the-middle attacks! See tls_trust_file, –tls-trust-file, tls_certcheck, –tls-certcheck.
If your system has a file that collects all system-wide trusted CA certificates, it is easiest to just use this in the `defaults' section of your configuration file. On Debian-based systems, for example, the adequate command would be `tls_trust_file /etc/ssl/certs/ca-certificates.crt'.
But you can also find out manually which CA certificate you need to trust. The following example works as of 2007-04-18.
For the Gmail POP server, you first issue the following command:
$ mpop --serverinfo --host=pop.gmail.com --tls=on --tls-starttls=off \
--tls-certcheck=off
The option `--tls-starttls=off' is needed for Gmail, but may not be necessary for other servers. The option `--tls-certcheck=off' allows mpop to accept any certificate, so that it can print some information about it.
According to the output of this command, the issuer of the server certificate is "Equifax Secure Certificate Authority". This means that you have to trust the Equifax CA to use full TLS security. You can download the appropriate certificate from http://www.geotrust.com/resources/root_certificates/index.asp (Equifax was bought by GeoTrust). The file you need for the `tls_trust_file' command is Equifax_Secure_Certificate_Authority.cer.
The following command should now succeed:
$ mpop --serverinfo --host=pop.gmail.com --tls=on --tls-starttls=off \
--tls-trust-file=Equifax_Secure_Certificate_Authority.cer
If the server requests it, the client can send a certificate, too. This allows the server to verify the identity of the client. See the EXTERNAL mechanism in Authentication. The `tls_key_file'/`tls_cert_file' commands or the `--tls-key-file'/`--tls-cert-file' options can be used to set a client certificate. See tls_key_file/–tls-key-file, tls_cert_file/–tls-cert-file. Note that GnuTLS will only send a client certificate if it matches one of the CAs advertised by the server. If you set a client certificate but it is not send to the server, probably does not match any CA that the server trusts.
POP3 servers require a client to authenticate itself before it is allowed to retrieve mail.
Multiple authentication methods exist. Most POP3 servers support only some of them. Some methods send authentication data in plain text (or nearly plain text) to the server, and some others are vulnerable to attacks. These methods should only be used when TLS is active to prevent others from stealing the password. See Transport Layer Security.
By default, mpop chooses a method automatically, and it will never choose one that puts the authentication data at risk. See below for details.
mpop supports the following authentication methods:
It depends on the underlying authentication library and its version whether a particular method is supported or not. Use --version to find out which methods are supported by your version of mpop.
Authentication data can be set with the `user' and `password' commands
or with the `--user' option. See user, password, –user.
If no password is set but one is needed during authentication, mpop will try to
find it in ~/.netrc, and if that fails, mpop will prompt you for it.
The authentication method can be chosen with the `auth' command or `--auth' option, but it is usually sufficient to just use the `on' argument to let mpop choose the method itself. See auth, –auth.
If mpop chooses the method itself, it will never choose an insecure method. If TLS is active, all methods are considered secure in this context, because the connection to the server is protected by TLS. If TLS is not active, only the CRAM-MD5, DIGEST-MD5, and GSSAPI methods are considered secure in this context, because all the others methods put the authentication data at risk.
If you really want to risk your authentication data, you have to force mpop to do that by manually setting the authentication method while TLS is off.
A POP3 client that sends multiple POP3 commands at once to a POP3 server before starting to read the server's answers is using POP3 pipelining. Since the client does not have to wait for the server's answer before sending the next command, and the server does not have to wait for the next command from the client, pipelining can speed up a POP3 session substantially.
Pipelining in mpop works by sending up to `PIPELINE_MAX' commands to the server, then begin to read its answers, and refill the command pipeline when the number of unanswered commands drops to `PIPELINE_MIN'. `PIPELINE_MIN' and `PIPELINE_MAX' are compile time constants.
By default, mpop will enable pipelining automatically if the server supports the CAPA command and advertizes the pipelining capability, and disable it for all other servers. See Server information mode.
You can change this behaviour with the `pipelining' command or `--pipelining' option. See pipelining, –pipelining. It is always safe to disable pipelining. It is not recommended to force pipelining for servers that are not known to support it.
Some POP3 servers still do not support the UIDL command. In this case, mpop cannot recognize messages that were already successfully retrieved, and will treat all messages as new. Use the `--serverinfo' option to find out if a server supports the UIDL command.
Some POP3 servers count end-of-line characters as two bytes (CRLF) instead of one (LF), so that the size of a mail as reported by the POP3 server is slightly larger than the actual size. This has the following consequences: The size filters are not accurate. Do not rely on exact size filtering. The progress output may display inaccurate (slightly too low) percentage values for the first mail retrieved from a POP3 server. mpop will detect this after the first mail has been read and will display corrected values for subsequent mails.
In this mode, mpop retrieves mail from one or more POP3 servers. It delivers each of them using the method that was given with the `delivery' command or `--delivery' option. See delivery, –delivery.
While retrieving the mail, mpop displays approximate progress information, which can be turned off with the `--quiet' option; see –quiet.
If the delivery succeeded, the mail is deleted from the POP3 server by default. The `keep' command and `--keep' option can prevent the deletion of mails; see keep, –keep.
Important note: Some POP3 servers will delete mails without any user interaction. See EXPIRE in Server information mode. mpop can do nothing about that.
If you don't want to download certain mails, but skip them or delete them directly, you can do filtering based on the mail headers. See Filtering.
If you just want to know if you have new mails (and how many), use the `--status-only' option. See –status-only.
If you just want to authenticate to the POP3 server, but don't want to look at your mails, use the `--auth-only' option. See –auth-only. This can be useful for sending mail through SMTP servers that require SMTP-after-POP (aka POP-before-SMTP).
Before mpop delivers a mail, it prepends a Received header to it. This is necessary if the delivery method transmits the mail to an SMTP server, for example. mpop does not change the contents of the mail in any other way.
In server information mode, mpop prints as much information about the POP3 server as it can get and then exits.
The POP3 features that can be detected are:
[LOGIN-DELAY]: The login delay period hast not yet expired.
[IN-USE]: Authentication succeeded but the mailbox is currently
in use, possibly by another POP3 session.
[LOGIN-DELAY]: The login delay period hast not yet expired.
[IN-USE]: Authentication succeeded but the mailbox is currently
in use, possibly by another POP3 session.
[SYS/TEMP]: Temporary system failure; try again later.
[SYS/PERM]: Permanent system failure; ask the administrator.
[AUTH]: Incorrect user name or password or some other problem with
the user's credentials.
If TLS is activated for server information mode, the following information will be printed about the POP3 server's TLS certificate (if available):
There are three filtering commands available. They will be executed in the following order:
If a filtering command applies to a mail, the remaining filters will not be executed.
The POP3 server must support the POP3 TOP command (Server information mode) for filtering with a filter command: It is used to read the mail headers (plus the blank line separating the header from the body) and pipe them to the filter command.
Note that, if the filter decides that the mail should be retrieved, the complete mail has to be downloaded, including the headers, so the headers will be downloaded twice. This is because there's no way in POP3 to download just the mail body. Sometimes this overhead surpasses the savings of the filtering.
The filter command looks at the mail headers and signals with its exit code what mpop should do with the mail:
sysexits.h error codes may be used to give information about the kind
of the error, but this is optional.
Since the filter command will be passed to a shell, you can use all shell command constructs in addition to just calling a script or program. This allows flexible filter constructs. See Filtering with SpamAssassin.
Some POP3 servers count end-of-line characters as two bytes (CRLF) instead of one (LF), so that the size of a mail as reported by the POP3 server is slightly larger than the actual size. The filters use the size values reported by the POP3 server since they cannot know the actual size in advance. Thus you cannot rely on exact size filtering.
#
# Default values for all accounts.
#
defaults
# Activate TLS.
tls on
# Enable full TLS certificate checks.
tls_trust_file /etc/ssl/certs/ca-certificates.crt
# Use the POP3-over-TLS variant instead of the STARTTLS variant.
# This is also known as "POP3 with SSL". Most servers support this.
tls_starttls off
# Use the procmail mail delivery agent.
delivery mda "/usr/bin/procmail -f '%F' -d $USER"
# For Sendmail:
#delivery mda "/usr/sbin/sendmail -oi -oem -f '%F' -- $USER"
# For msmtp (delivery via SMTP):
#delivery mda "/usr/bin/msmtp --host=localhost --from='%F' -- $USER"
# Delivery to a maildir folder:
#delivery maildir ~/Mail/incoming
# Delivery to a MBOX mail folder:
#delivery mbox ~/Mail/new
#
# Two pop3 mailboxes at the provider.
#
account provider1
host mx.provider.example
user john_smith
password secret
# Copy the settings from the previous account, and only override the
# settings that differ.
account provider2 : provider1
user joey
password secret2
#
# A freemail service.
#
account freemail
host pop.freemail.example
user 1238476
password pass
# The service runs SpamAssassin, so test each mail for the "X-Spam-Status: Yes"
# header, and delete all mails with this header before downloading them.
filter if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0; fi
#
# Set a default account (optional).
#
account default : provider1
Use the following to delete all mails that SpamAssassin classifies as spam:
filter "/path/to/spamc -c > /dev/null"
Since no message body is passed to SpamAssassin, you should disable all body-specific tests in the SpamAssassin configuration file; for example set use_bayes 0.
If your mail provider runs SpamAssassin for you, you just have to check for the result. The following script can do that when used as an mpop filter:
#!/bin/sh
if [ "`grep "^X-Spam-Status: Yes"`" ]; then
exit 1 # kill this message
else
exit 0 # proceed normally
fi
Since the filter command is passed to a shell, all shell constructs are usable, so you can also use this directly:
filter if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0; fi
The homepage of mpop is http://mpop.sourceforge.net/; the SourceForge project page is at http://sourceforge.net/projects/mpop/.
The mailing lists mpop-users can be accessed from the project page.
Please send any questions, suggestions, and bug reports either to the mailing
list or to Martin Lambers (marlam@marlam.de, OpenPGP key:
http://www.marlam.de/key.txt).
If you send a bug report, please include the output of mpop --version.