Provided by: mpop_1.0.28-1_amd64 
NAME
mpop - A POP3 client
SYNOPSIS
Mail retrieval mode (default):
mpop [option...] [--] [account...]
mpop --host=host [option...]
Server information mode:
mpop [option...] --serverinfo [account...]
mpop --host=host [option...] --serverinfo
DESCRIPTION
In mail retrieval mode of operation, mpop 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, mbox
files, or Exchange pickup directories. 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.
In server information mode, mpop prints information about one or more POP3 servers.
If no account names are given on the command line, the one named default will be used.
EXIT STATUS
The standard sendmail exit codes are used, as defined in sysexits.h.
OPTIONS
Options override configuration file settings, for every used account.
General Options
--version
Print version information. This includes information about the library used for TLS/SSL
support (if any), the library used for authentication, and the authentication mechanisms
supported by this library.
--help Print help.
-P, --pretend
Print the configuration settings that would be used, but do not take further action. An
asterisk (`*') will be printed instead of your password.
-d, --debug
Print lots of debugging information, including the whole conversation with the POP3 server.
Be careful with this option: the (potentially dangerous) output will not be sanitized, and
your password may get printed in an easily decodable format!
This option implies --half-quiet, because the progress output would interfere with the
debugging output.
Changing the mode of operation
-S, --serverinfo
Print information about the POP3 server(s) and exit. This includes information about
supported features (pipelining, authentication methods, TOP command, ...), about parameters
(time for which mails will not be deleted, minimum time between logins, ...), and about the
TLS certificate (if TLS is active).
Configuration options
-C, --file=conffile
Use the given file instead of ~/.mpoprc as configuration file.
--host=hostname
Use this POP3 server with settings from the command line; do not use any configuration file
data. You cannot use both this option and account names on the command line.
--port=number
Set the port number to connect to. See the port command below.
--timeout=(off|seconds)
Set a network timeout. See the timeout command below.
--pipelining=(auto|on|off)
Enable or disable POP3 pipelining. See the pipelining command below.
--received-header[=(on|off)]
Enable or disable the Received header. See the received_header command below.
--auth[=(on|method)]
Set the authentication method to automatic (with "on") or manually choose an authentication
method. See the auth command below.
--user=[username]
Set or unset the user name for authentication. See the user command below.
--passwordeval=[eval]
Set your password for authentication to the output (stdout) of the execution of eval.
--tls[=(on|off)]
Enable or disable TLS/SSL encryption. See the tls command below.
--tls-starttls[=(on|off)]
Enable or disable the POP3 STLS command for TLS encryption. See the tls_starttls command
below.
--tls-trust-file=[file]
Set or unset a trust file for TLS encryption. See the tls_trust_file command below.
--tls-crl-file=[file]
Set or unset a certificate revocation list (CRL) file for TLS. See the tls_crl_file command
below.
--tls-fingerprint=[fingerprint]
Set ot unset the fingerprint of a trusted TLS certificate. See the tls_fingerprint command
below.
--tls-key-file=[file]
Set or unset a key file for TLS encryption. See the tls_key_file command below.
--tls-cert-file=[file]
Set or unset a cert file for TLS encryption. See the tls_cert_file command below.
--tls-certcheck[=(on|off)]
Enable or disable server certificate checks for TLS encryption. See the tls_certcheck
command below.
--tls-force-sslv3[=(on|off)]
Force TLS/SSL version SSLv3. See the tls_force_sslv3 command below.
--tls-min-dh-prime-bits=[bits]
Set or unset minimum bit size of the Diffie-Hellmann (DH) prime. See the
tls_min_dh_prime_bits command below.
--tls-priorities=[priorities]
Set or unset TLS priorities. See the tls_priorities command below.
Options specific to mail retrieval mode
-q, --quiet
Do not print status or progress information.
-Q, --half-quiet
Print status but not progress information.
-a, --all-accounts
Query all accounts in the configuration file.
-A, --auth-only
Authenticate only; do not retrieve mail. Useful for SMTP-after-POP.
-s, --status-only
Print number and size of mails in each account only; do not retrieve mail.
-n, --only-new[=(on|off)]
Process only new messages. See the only_new command below.
-k, --keep[=(on|off)]
Do not delete mails from POP3 servers, regardless of other options or settings. See the
keep command below.
--killsize=(off|size)
Set or unset kill size. See the killsize command below.
--skipsize=(off|size)
Set or unset skip size. See the skipsize command below.
--filter=[program]
Set a filter which will decide whether to retrieve, skip, or delete each mail by
investigating the mail's headers. See the filter command below.
--delivery=method,method_arguments...
How to deliver messages received from this account. See the delivery command below. Note
that a comma is used instead of a blank to separate the method from its arguments.
--uidls-file=filename
File to store UIDLs in. See the uidls_file command below.
USAGE
mpop normally uses a configuration file (~/.mpoprc by default) that contains information about your POP3
accounts.
Skip to the EXAMPLES section for a quick start.
The configuration file is a simple text file. Empty lines and comment lines (whose first non-blank
character is `#') are ignored. The file must have no more permissions than user read/write.
Every other line must contain a command and may contain an argument to that command.
The argument may be enclosed in double quotes ("), for example if its first or last character is a blank.
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 are as follows:
defaults
Set defaults. The following configuration commands will set default values for all following
account definitions.
account name [:account[,...]]
Start a new account definition with the given name. The current default values are filled in.
If a colon and a list of previously defined accounts is given after the account name, the new
account, with the filled in default values, will inherit all settings from the accounts in the
list.
host hostname
The POP3 server to retrieve mails from. The argument may be a host name or a network address.
Every account definition must contain this command.
port number
The port that the POP3 server listens on. The default is 110, unless TLS without STARTTLS is used,
in which case it is 995.
timeout (off|seconds)
Set or unset a network timeout, in seconds. The default is 180 seconds. The argument off means
that no timeout will be set, which means that the operating system default will be used.
pipelining (auto|on|off)
Enable or disable POP3 pipelining. The default is auto, which means that mpop enables pipelining
for POP3 servers that advertize this capability, and disables it for all other servers. See also
--serverinfo.
It is always safe to disable pipelining. It is not recommended to force pipelining for servers
that are not known to support it.
Pipelining 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 contants.
received_header [(on|off)]
Enable or disable the Received header. By default, mpop prepends a Received header to the mail
during delivery. This is required by the RFCs if the mail is subsequently further delivered e.g.
via SMTP, and it is a good idea in all other cases. Nevertheless, if you absolutely have to, you
can disable the Received header with this command.
delivery method method_arguments...
How to deliver messages received from this account.
delivery mda command
Deliver the mails through a mail delivery agent (MDA).
All occurences of %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'.
Use "delivery mda /usr/bin/procmail -f '%F' -d $USER" for the procmail MDA.
Use "delivery mda /usr/sbin/sendmail -oi -oem -f '%F' -- $USER" to let your MTA handle the
mail.
Use "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.)
delivery maildir directory
Deliver the mails to the given maildir directory. The directory must exist and it must be a
valid maildir directory; mpop will not create directories. This delivery type only works on
file systems that support hard links.
delivery mbox mbox-file
Deliver the mails to the given file in mbox format. The file will be locked with fcntl(2).
mpop uses the MBOXRD mbox format variant; see the documentation of the mbox format.
delivery exchange directory
Deliver the mails to the given Exchange pickup directory. The directory must exist.
If the delivery method needs to parse the mail headers for an envelope from address (the mda
method if the command contains %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 the FILES / ENVIRONMENT section.
uidls_file filename
The file to store UIDLs in. These are needed to identify new messages. %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.
The default value is "~/.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.
auth [(on|method)]
This command chooses the POP3 authentication method. With the argument on, mpop will choose the
best one available for you (see below). This is the default.
You probably need to set a username (with user) and password (with password). If no password is
set but one is needed during authentication, mpop will try to find it. First, if passwordeval is
set, it will evaluate that command. If passwordeval is not set, mpop will try to find the password
in ~/.netrc. If that fails, it will try to find it in SYSCONFDIR/netrc (use --version to find out
what SYSCONFDIR is on your platform). If that fails, it will try to get it from a system specific
keychain (if available). If that fails but a controlling terminal is available, mpop will prompt
you for it.
Currently supported keyrings are the Gnome Keyring and the Mac OS X Keychain. The script mpop-
gnome-tool.py can be used to manage Gnome Keyring passwords for mpop. To manage Mac OS X Keychain
passwords, use the Keychain Access GUI application. The account name is same as the mpop user
argument. The keychain item name is pop3://<hostname> where <hostname> matches the mpop host
argument.
Available methods are user, apop, plain, scram-sha-1, cram-md5, gssapi, external, digest-md5,
login, and ntlm. Note that one or more of these methods may be unavailable due to lack of support
in the underlying authentication library. Use the --version option to find out which methods are
supported.
The user, plain and login methods send your authentication data in cleartext over the net, and the
apop, digest-md5, and ntlm methods are vulnerable to attacks. These methods should therefore only
be used together with the tls command.
If you don't choose the method yourself, mpop chooses the best secure method that the POP3 server
supports. Secure means that your authentication data will not be sent in cleartext over the net.
For TLS encrypted connections, every authentication method is secure in this sense. If TLS is not
active, only gssapi, scram-sha-1, and cram-md5 are secure in this sense.
The external method is special: the actual authentication happens outside of the SMTP protocol,
typically by sending a TLS client certificate (see the tls_cert_file command). The external method
merely confirms that this authentication succeeded for the given user (or, if no user name is
given, confirms that authentication succeeded). This authentication method is not chosen
automatically; you have to request it manually.
user login
Set your user name for POP3 authentication.
password secret
Set your password for POP3 authentication. If no password is set but one is needed during
authentication, mpop will try to find it. First, if passwordeval is set, it will evaluate that
command. If passwordeval is not set, mpop will try to find the password in ~/.netrc. If that
fails, it will try to find it in SYSCONFDIR/netrc (use --version to find out what SYSCONFDIR is on
your platform). If that fails, it will try to get it from a system specific keychain (if
available). If that fails but a controlling terminal is available, mpop will prompt you for it.
passwordeval [eval]
Set your password for authentication to the output (stdout) of the execution of eval.
ntlmdomain [domain]
Set a domain for the ntlm authentication method. The default is to use no domain (equivalent to an
empty argument), but some servers seem to require one, even if it is an arbitrary string.
tls [(on|off)]
This command enables or disables TLS (also known as SSL) encrypted connections to the POP3 server.
Not every server supports this, and many that support it require the additional command
tls_starttls off.
With TLS/SSL, the connection with the POP3 server will be protected against eavesdroppers and man-
in-the-middle attacks. To use TLS/SSL, it is required to either use the tls_trust_file command
(highly recommended) or to disable tls_certcheck.
tls_starttls [(on|off)]
This command chooses the TLS/SSL variant: with STARTTLS (on, default) or POP3-over-TLS (off). Most
servers support the latter variant, which is also commonly referred to as "POP3 with SSL".
tls_trust_file file
This command activates strict server certificate verification.
The filename must be the absolute path name of a file in PEM format containing one or more
certificates of trusted Certification Authorities (CAs).
On Debian based systems, you can install the ca-certificates package and use the file
/etc/ssl/certs/ca-certificates.crt.
An empty argument disables this feature.
tls_fingerprint [fingerprint]
This command sets or unsets the fingerprint of a particular TLS certificate. This certificate
will then be trusted, regardless of its contents. This can be used to trust broken certificates
(e.g. with a non-matching hostname) or in situations where tls_trust_file cannot be used for some
reason.
You can give either an SHA1 (recommended) or an MD5 fingerprint in the format 01:23:45:67:...
You can use --serverinfo --tls --tls-certcheck=off to get the peer certificate's fingerprints.
tls_crl_file [file]
This command sets or unsets a certificate revocation list (CRL) file for TLS, to be used during
strict server certificate verification as enabled by the tls_trust_file command. This allows the
verification procedure to detect revoked certificates.
tls_key_file file
This command (together with the tls_cert_file command) enables mpop to send a client certificate
to the POP3 server if requested.
The filename must be the absolute path name of a file in PEM format containing a private key. Be
sure that this file is only readable by yourself!
An empty argument disables this feature.
tls_cert_file file
This command (together with the tls_key_file command) enables mpop to send a client certificate to
the POP3 server if requested.
The filename must be the absolute path name of a file in PEM format containing a certificate.
An empty argument disables this feature.
tls_certcheck [(on|off)]
This command enables or disables checks for the server certificate.
WARNING: When the checks are disabled, TLS/SSL sessions will be vulnerable to man-in-the-middle
attacks!
tls_force_sslv3 [(on|off)]
Force TLS/SSL version SSLv3. This might be needed to use SSL with some old and broken servers. Do
not use this unless you have to.
tls_min_dh_prime_bits [bits]
Set or unset the minimum number of Diffie-Hellman (DH) prime bits that mpop will accept for TLS
sessions. The default is set by the TLS library and can be selected by using an empty argument to
this command. Only lower the default (for example to 512 bits) if there is no other way to make
TLS work with the remote server.
tls_priorities [priorities]
Set the priorities for TLS sessions. The default is set by the TLS library and can be selected by
using an empty argument to this command. Currently this command only works with sufficiently
recent GnuTLS releases. See the GnuTLS documentation of the gnutls_priority_init function for a
description of the priorities string.
only_new [(on|off)]
By default, mpop processes only new messages (new messages are those that were not already
successfully retrieved in an earlier session). If this option is turned off, mpop will process all
messages.
keep [(on|off)]
Keep all mails on the POP3 server, never delete them. The default behaviour is to delete mails
that have been successfully retrieved or filtered by kill filters.
killsize (off|size)
Mails larger than the given size will be deleted (unless the keep command is used, in which case
they will just be skipped). The size argument must be zero or greater. If it is followed by a `k'
or an `m', the size is measured in kibibytes/mebibytes instead of bytes. Note that some POP3
servers report slightly incorrect sizes for mails; see NOTES below.
When killsize is set to 0 and keep is set to on, then all mails are marked as retrieved, but no
mail gets deleted from the server. This can be used to synchronize the UID list on the client to
the UID list on the server.
skipsize (off|size)
Mails larger than the given size will be skipped (not downloaded). The size argument must be zero
or greater. If it is followed by a `k' or an `m', the size is measured in kibibytes/mebibytes
instead of bytes. Note that some POP3 servers report slightly incorrect sizes for mails; see
NOTES below.
filter [command]
Set a filter which will decide whether to retrieve, skip, or delete each mail by investigating the
mail's headers. The POP3 server must support the POP3 TOP command for this to work; see option
--serverinfo above. An empty argument disables filtering.
All occurences of %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'.
All occurences of %S in the command will be replaced with the size of the current mail as reported
by the POP3 server.
The mail headers (plus the blank line separating the headers from the body) will be piped to the
command. Based on the return code, mpop decides what to do with the mail:
0: proceed normally; no special action
1: delete the mail; do not retrieve it
2: skip the mail; do not retrieve it
Return codes greater than or equal to 3 mean that an error occured. The sysexits.h error codes may
be used to give information about the kind of the error, but this is not necessary.
FILTERING
There are three filtering commands available. They will be executed in the following order:
killsize
skipsize
filter
If a filtering command applies to a mail, the remaining filters will not be executed.
EXAMPLES
Configuration file
# 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 often called "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
# Delivery to an Exchange pickup directory:
#delivery exchange c:\exchange\pickup
# 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
passwordeval gpg -d ~/.mpop.password.gpg
# Set a default account (optional).
account default : provider1
Filtering with SpamAssassin
The command filter "/path/to/spamc -c > /dev/null" will delete all mails that SpamAssassin thinks are
spam. 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, you can also use this directly:
filter if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0; fi
FILES / ENVIRONMENT
~/.mpoprc
Default configuration file.
~/.mpop_uidls
Default directory to store UIDLs files in.
~/.netrc and SYSCONFDIR/netrc
The netrc file contains login information. If a password is not found in the configuration file,
mpop will search it in ~/.netrc and SYSCONFDIR/netrc before prompting the user for it. The syntax
of netrc files is described in netrc(5) or ftp(1).
$USER, $LOGNAME
These variables override the user's login name. $LOGNAME is only used if $USER is unset. The
user's login name is used for Received headers.
$TMPDIR
Directory to create temporary files in. If this is unset, a system specific default directory is
used.
NOTES
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.
AUTHOR
mpop was written by Martin Lambers <marlam@marlam.de>
Other authors are listed in the AUTHORS file in the source distribution.
SEE ALSO
procmail(1), spamassassin(1), fetchmail(1), getmail(1), netrc(5) or ftp(1), mbox(5), fcntl(2)
2013-04 MPOP(1)