A pop3 client
mpop [option...] [--] [account...]
mpop --host=host [option...]
mpop [option...] --serverinfo [account...]
mpop --host=host [option...] --serverinfo
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.
The standard sendmail exit codes are used, as defined in sysexits.h.
Options override configuration file settings, for every used account.
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.
Print help.
Print the configuration settings that would be used, but do not take further action. An asterisk (`*') will be printed instead of your password.
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.
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).
Use the given file instead of ~/.mpoprc as configuration file.
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.
Set the port number to connect to. See the port command below.
Set a network timeout. See the timeout command below.
Enable or disable POP3 pipelining. See the pipelining command below.
Enable or disable the Received header. See the received_header command below.
Set the authentication method to automatic (with "on") or manually choose an authentication method. See the auth command below.
Set or unset the user name for authentication. See the user command below.
Set your password for authentication to the output (stdout) of the execution of eval.
Enable or disable TLS/SSL encryption. See the tls command below.
Enable or disable the POP3 STLS command for TLS encryption. See the tls_starttls command below.
Set or unset a trust file for TLS encryption. See the tls_trust_file command below.
Set or unset a certificate revocation list (CRL) file for TLS. See the tls_crl_file command below.
Set ot unset the fingerprint of a trusted TLS certificate. See the tls_fingerprint command below.
Set or unset a key file for TLS encryption. See the tls_key_file command below.
Set or unset a cert file for TLS encryption. See the tls_cert_file command below.
Enable or disable server certificate checks for TLS encryption. See the tls_certcheck command below.
Force TLS/SSL version SSLv3. See the tls_force_sslv3 command below.
Set or unset minimum bit size of the Diffie-Hellmann (DH) prime. See the tls_min_dh_prime_bits command below.
Set or unset TLS priorities. See the tls_priorities command below.
Do not print status or progress information.
Print status but not progress information.
Query all accounts in the configuration file.
Authenticate only; do not retrieve mail. Useful for SMTP-after-POP.
Print number and size of mails in each account only; do not retrieve mail.
Process only new messages. See the only_new command below.
Do not delete mails from POP3 servers, regardless of other options or settings. See the keep command below.
Set or unset kill size. See the killsize command below.
Set or unset skip size. See the skipsize command below.
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.
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.
File to store UIDLs in. See the uidls_file command below.
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:
Set defaults. The following configuration commands will set default values for all following account definitions.
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.
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.
The port that the POP3 server listens on. The default is 110, unless TLS without STARTTLS is used, in which case it is 995.
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.
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.
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.
How to deliver messages received from this account.
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.)
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.
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.
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.
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.
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.
Set your user name for POP3 authentication.
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.
Set your password for authentication to the output (stdout) of the execution of eval.
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.
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.
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".
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.
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.
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.
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.
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.
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!
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.
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.
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.
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 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.
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.
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.
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.
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.
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
Default configuration file.
Default directory to store UIDLs files in.
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).
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.
Directory to create temporary files in. If this is unset, a system specific default directory is used.
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.
mpop was written by Martin Lambers <[email protected]>
Other authors are listed in the AUTHORS file in the source distribution.
procmail(1), spamassassin(1), fetchmail(1), getmail(1), netrc(5) or ftp(1), mbox(5), fcntl(2)