1MPOP(1) General Commands Manual MPOP(1)
2
6 mpop - A POP3 client
7
9 Mail retrieval mode (default):
10 mpop [option...] [--] [account...]
11 mpop --host=host [option...]
12 Server information mode:
14 mpop [option...] --serverinfo [account...]
15 mpop --host=host [option...] --serverinfo
16
18 In mail retrieval mode of operation, mpop retrieves mails from one or
19 more POP3 mailboxes, optionally does some filtering, and delivers them
20 through a mail delivery agent (MDA) or to maildir folders, mbox files,
21 or Exchange pickup directories. Mails that were successfully delivered
22 before will not be retrieved a second time, even if errors occur or
23 mpop is terminated in the middle of a session.
24 In server information mode, mpop prints information about one or more
25 POP3 servers.
26 If no account names are given on the command line, the one named
27 default will be used.
28
30 The standard sendmail exit codes are used, as defined in sysexits.h.
31
33 Options override configuration file settings, for every used account.
34 General Options
36 --version
38 Print version information. This includes information
39 about the library used for TLS/SSL support (if any), the
40 library used for authentication, and the authentication
41 mechanisms supported by this library.
42 --help Print help.
44 -P, --pretend
46 Print the configuration settings that would be used, but
47 do not take further action. An asterisk (`*') will be
48 printed instead of your password.
49 -d, --debug
51 Print lots of debugging information, including the whole
52 conversation with the POP3 server. Be careful with this
53 option: the (potentially dangerous) output will not be
54 sanitized, and your password may get printed in an easily
55 decodable format!
56 This option implies --half-quiet, because the progress
57 output would interfere with the debugging output.
58 Changing the mode of operation
60 -S, --serverinfo
62 Print information about the POP3 server(s) and exit. This
63 includes information about supported features (pipelin‐
64 ing, authentication methods, TOP command, ...), about
65 parameters (time for which mails will not be deleted,
66 minimum time between logins, ...), and about the TLS cer‐
67 tificate (if TLS is active).
68 Configuration options
70 -C, --file=conffile
72 Use the given file instead of ~/.mpoprc as configuration
73 file.
74 --host=hostname
76 Use this POP3 server with settings from the command line;
77 do not use any configuration file data. You cannot use
78 both this option and account names on the command line.
79 --port=number
81 Set the port number to connect to. See the port command
82 below.
83 --timeout=(off|seconds)
85 Set a network timeout. See the timeout command below.
86 --pipelining=(auto|on|off)
88 Enable or disable POP3 pipelining. See the pipelining
89 command below.
90 --received-header[=(on|off)]
92 Enable or disable the Received header. See the
93 received_header command below.
94 --auth[=(on|method)]
96 Set the authentication method to automatic (with "on") or
97 manually choose an authentication method. See the auth
98 command below.
99 --user=[username]
101 Set or unset the user name for authentication. See the
102 user command below.
103 --passwordeval=[eval]
105 Set your password for authentication to the output (std‐
106 out) of the execution of eval.
107 --tls[=(on|off)]
109 Enable or disable TLS/SSL encryption. See the tls command
110 below.
111 --tls-starttls[=(on|off)]
113 Enable or disable the POP3 STLS command for TLS encryp‐
114 tion. See the tls_starttls command below.
115 --tls-trust-file=[file]
117 Set or unset a trust file for TLS encryption. See the
118 tls_trust_file command below.
119 --tls-crl-file=[file]
121 Set or unset a certificate revocation list (CRL) file for
122 TLS. See the tls_crl_file command below.
123 --tls-fingerprint=[fingerprint]
125 Set ot unset the fingerprint of a trusted TLS certifi‐
126 cate. See the tls_fingerprint command below.
127 --tls-key-file=[file]
129 Set or unset a key file for TLS encryption. See the
130 tls_key_file command below.
131 --tls-cert-file=[file]
133 Set or unset a cert file for TLS encryption. See the
134 tls_cert_file command below.
135 --tls-certcheck[=(on|off)]
137 Enable or disable server certificate checks for TLS
138 encryption. See the tls_certcheck command below.
139 --tls-force-sslv3[=(on|off)]
141 Force TLS/SSL version SSLv3. See the tls_force_sslv3 com‐
142 mand below.
143 --tls-min-dh-prime-bits=[bits]
145 Set or unset minimum bit size of the Diffie-Hellmann (DH)
146 prime. See the tls_min_dh_prime_bits command below.
147 --tls-priorities=[priorities]
149 Set or unset TLS priorities. See the tls_priorities com‐
150 mand below.
151 Options specific to mail retrieval mode
153 -q, --quiet
155 Do not print status or progress information.
156 -Q, --half-quiet
158 Print status but not progress information.
159 -a, --all-accounts
161 Query all accounts in the configuration file.
162 -A, --auth-only
164 Authenticate only; do not retrieve mail. Useful for SMTP-
165 after-POP.
166 -s, --status-only
168 Print number and size of mails in each account only; do
169 not retrieve mail.
170 -n, --only-new[=(on|off)]
172 Process only new messages. See the only_new command
173 below.
174 -k, --keep[=(on|off)]
176 Do not delete mails from POP3 servers, regardless of
177 other options or settings. See the keep command below.
178 --killsize=(off|size)
180 Set or unset kill size. See the killsize command below.
181 --skipsize=(off|size)
183 Set or unset skip size. See the skipsize command below.
184 --filter=[program]
186 Set a filter which will decide whether to retrieve, skip,
187 or delete each mail by investigating the mail's headers.
188 See the filter command below.
189 --delivery=method,method_arguments...
191 How to deliver messages received from this account. See
192 the delivery command below. Note that a comma is used
193 instead of a blank to separate the method from its argu‐
194 ments.
195 --uidls-file=filename
197 File to store UIDLs in. See the uidls_file command below.
198
200 mpop normally uses a configuration file (~/.mpoprc by default) that
201 contains information about your POP3 accounts.
202 Skip to the EXAMPLES section for a quick start.
204 The configuration file is a simple text file. Empty lines and comment
206 lines (whose first non-blank character is `#') are ignored. The file
207 must have no more permissions than user read/write.
208 Every other line must contain a command and may contain an argument to
209 that command.
210 The argument may be enclosed in double quotes ("), for example if its
211 first or last character is a blank.
212 If the first character of a filename is the tilde (~), this tilde will
213 be replaced by $HOME.
214 If a command accepts the argument on, it also accepts an empty argument
215 and treats that as if it was on.
216 Commands are as follows:
218 defaults
220 Set defaults. The following configuration commands will set
221 default values for all following account definitions.
222 account name [:account[,...]]
224 Start a new account definition with the given name. The current
225 default values are filled in.
226 If a colon and a list of previously defined accounts is given
227 after the account name, the new account, with the filled in
228 default values, will inherit all settings from the accounts in
229 the list.
230 host hostname
232 The POP3 server to retrieve mails from. The argument may be a
233 host name or a network address. Every account definition must
234 contain this command.
235 port number
237 The port that the POP3 server listens on. The default is 110,
238 unless TLS without STARTTLS is used, in which case it is 995.
239 timeout (off|seconds)
241 Set or unset a network timeout, in seconds. The default is 180
242 seconds. The argument off means that no timeout will be set,
243 which means that the operating system default will be used.
244 pipelining (auto|on|off)
246 Enable or disable POP3 pipelining. The default is auto, which
247 means that mpop enables pipelining for POP3 servers that adver‐
248 tize this capability, and disables it for all other servers. See
249 also --serverinfo.
250 It is always safe to disable pipelining. It is not recommended
251 to force pipelining for servers that are not known to support
252 it.
253 Pipelining works by sending up to PIPELINE_MAX commands to the
254 server, then begin to read its answers, and refill the command
255 pipeline when the number of unanswered commands drops to PIPE‐
256 LINE_MIN. PIPELINE_MIN and PIPELINE_MAX are compile time con‐
257 tants.
258 received_header [(on|off)]
260 Enable or disable the Received header. By default, mpop prepends
261 a Received header to the mail during delivery. This is required
262 by the RFCs if the mail is subsequently further delivered e.g.
263 via SMTP, and it is a good idea in all other cases. Neverthe‐
264 less, if you absolutely have to, you can disable the Received
265 header with this command.
266 delivery method method_arguments...
268 How to deliver messages received from this account.
269 delivery mda command
271 Deliver the mails through a mail delivery agent (MDA).
272 All occurences of %F in the command will be replaced with
273 the envelope from address of the current message (or
274 MAILER-DAEMON if none is found). Note that this address
275 is guaranteed to contain only letters a-z and A-Z, digits
276 0-9, and any of ".@_-+/", even though that is only a sub‐
277 set of what is theoretically allowed in a mail address.
278 Other characters, including those interpreted by the
279 shell, are replaced with "_". Nevertheless, you should
280 put %F into single quotes: '%F'.
281 Use "delivery mda /usr/bin/procmail -f '%F' -d $USER" for
282 the procmail MDA.
283 Use "delivery mda /usr/sbin/sendmail -oi -oem -f '%F' --
284 $USER" to let your MTA handle the mail.
285 Use "delivery mda /usr/local/bin/msmtp --host=localhost
286 --from='%F' -- $USER@`hostname`.`dnsdomainname`" to pass
287 the mail to your MTA via SMTP. (This is what fetchmail
288 does by default.)
289 delivery maildir directory
291 Deliver the mails to the given maildir directory. The
292 directory must exist and it must be a valid maildir
293 directory; mpop will not create directories. This deliv‐
294 ery type only works on file systems that support hard
295 links.
296 delivery mbox mbox-file
298 Deliver the mails to the given file in mbox format. The
299 file will be locked with fcntl(2). mpop uses the MBOXRD
300 mbox format variant; see the documentation of the mbox
301 format.
302 delivery exchange directory
304 Deliver the mails to the given Exchange pickup directory.
305 The directory must exist.
306 If the delivery method needs to parse the mail headers for an
308 envelope from address (the mda method if the command contains
309 %F, and the mbox method), then it needs to create a temporary
310 file to store the mail headers (but not the body) in. See
311 $TMPDIR in the FILES / ENVIRONMENT section.
312 uidls_file filename
314 The file to store UIDLs in. These are needed to identify new
315 messages. %U in the filename will be replaced by the username
316 of the current account. %H in the filename will be replaced by
317 the hostname of the current account. If the filename contains
318 directories that do not exist, mpop will create them. mpop
319 locks this file for exclusive access when accessing the associ‐
320 ated POP3 account.
321 The default value is "~/.mpop_uidls/%U_at_%H". You can also use
322 a single UIDLS file for multiple accounts, but then you cannot
323 poll more than one of these accounts at the same time.
324 auth [(on|method)]
326 This command chooses the POP3 authentication method. With the
327 argument on, mpop will choose the best one available for you
328 (see below). This is the default.
329 You probably need to set a username (with user) and password
330 (with password). If no password is set but one is needed during
331 authentication, mpop will try to find it. First, if passwordeval
332 is set, it will evaluate that command. If passwordeval is not
333 set, mpop will try to find the password in ~/.netrc. If that
334 fails, it will try to find it in SYSCONFDIR/netrc (use --version
335 to find out what SYSCONFDIR is on your platform). If that fails,
336 it will try to get it from a system specific keychain (if avail‐
337 able). If that fails but a controlling terminal is available,
338 mpop will prompt you for it.
339 Currently supported keyrings are the Gnome Keyring and the Mac
340 OS X Keychain. The script mpop-gnome-tool.py can be used to
341 manage Gnome Keyring passwords for mpop. To manage Mac OS X Key‐
342 chain passwords, use the Keychain Access GUI application. The
343 account name is same as the mpop user argument. The keychain
344 item name is pop3://<hostname> where <hostname> matches the mpop
345 host argument.
346 Available methods are user, apop, plain, login, cram-md5,
347 digest-md5, scram-sha-1, gssapi, external, login, and ntlm.
348 Note that one or more of these methods may be unavailable due to
349 lack of support in the underlying authentication library. Use
350 the --version option to find out which methods are supported.
351 The user, plain and login methods send your authentication data
352 in cleartext over the net, and the apop and ntlm methods are
353 vulnerable to attacks. These methods should therefore only be
354 used together with the tls command.
355 If you don't choose the method yourself, mpop chooses the best
356 secure method that the POP3 server supports. Secure means that
357 your authentication data will not be sent in cleartext over the
358 net. For TLS encrypted connections, every authentication method
359 is secure in this sense. If TLS is not active, only gssapi,
360 scram-sha-1, digest-md5, and cram-md5 are secure in this sense.
361 The external method is special: the actual authentication hap‐
362 pens outside of the SMTP protocol, typically by sending a TLS
363 client certificate (see the tls_cert_file command). The external
364 method merely confirms that this authentication succeeded for
365 the given user (or, if no user name is given, confirms that
366 authentication succeeded). This authentication method is not
367 chosen automatically; you have to request it manually.
368 user login
370 Set your user name for POP3 authentication.
371 password secret
373 Set your password for POP3 authentication. If no password is
374 set but one is needed during authentication, mpop will try to
375 find it. First, if passwordeval is set, it will evaluate that
376 command. If passwordeval is not set, mpop will try to find the
377 password in ~/.netrc. If that fails, it will try to find it in
378 SYSCONFDIR/netrc (use --version to find out what SYSCONFDIR is
379 on your platform). If that fails, it will try to get it from a
380 system specific keychain (if available). If that fails but a
381 controlling terminal is available, mpop will prompt you for it.
382 passwordeval [eval]
384 Set your password for authentication to the output (stdout) of
385 the execution of eval.
386 ntlmdomain [domain]
388 Set a domain for the ntlm authentication method. The default is
389 to use no domain (equivalent to an empty argument), but some
390 servers seem to require one, even if it is an arbitrary string.
391 tls [(on|off)]
393 This command enables or disables TLS (also known as SSL)
394 encrypted connections to the POP3 server. Not every server sup‐
395 ports this, and many that support it require the additional com‐
396 mand tls_starttls off.
397 With TLS/SSL, the connection with the POP3 server will be pro‐
398 tected against eavesdroppers and man-in-the-middle attacks. To
399 use TLS/SSL, it is required to either use the tls_trust_file
400 command (highly recommended) or to disable tls_certcheck.
401 tls_starttls [(on|off)]
403 This command chooses the TLS/SSL variant: with STARTTLS (on,
404 default) or POP3-over-TLS (off). Most servers support the latter
405 variant, which is also commonly referred to as "POP3 with SSL".
406 tls_trust_file file
408 This command activates strict server certificate verification.
409 The filename must be the absolute path name of a file in PEM
410 format containing one or more certificates of trusted Certifica‐
411 tion Authorities (CAs).
412 On Debian based systems, you can install the ca-certificates
413 package and use the file /etc/ssl/certs/ca-certificates.crt.
414 An empty argument disables this feature.
415 tls_fingerprint [fingerprint]
417 This command sets or unsets the fingerprint of a particular TLS
418 certificate. This certificate will then be trusted, regardless
419 of its contents. This can be used to trust broken certificates
420 (e.g. with a non-matching hostname) or in situations where
421 tls_trust_file cannot be used for some reason.
422 You can give either an SHA1 (recommended) or an MD5 fingerprint
423 in the format 01:23:45:67:...
424 You can use --serverinfo --tls --tls-certcheck=off to get the
425 peer certificate's fingerprints.
426 tls_crl_file [file]
428 This command sets or unsets a certificate revocation list (CRL)
429 file for TLS, to be used during strict server certificate veri‐
430 fication as enabled by the tls_trust_file command. This allows
431 the verification procedure to detect revoked certificates.
432 tls_key_file file
434 This command (together with the tls_cert_file command) enables
435 mpop to send a client certificate to the POP3 server if
436 requested.
437 The filename must be the absolute path name of a file in PEM
438 format containing a private key. Be sure that this file is only
439 readable by yourself!
440 An empty argument disables this feature.
441 tls_cert_file file
443 This command (together with the tls_key_file command) enables
444 mpop to send a client certificate to the POP3 server if
445 requested.
446 The filename must be the absolute path name of a file in PEM
447 format containing a certificate.
448 An empty argument disables this feature.
449 tls_certcheck [(on|off)]
451 This command enables or disables checks for the server certifi‐
452 cate.
453 WARNING: When the checks are disabled, TLS/SSL sessions will be
454 vulnerable to man-in-the-middle attacks!
455 tls_force_sslv3 [(on|off)]
457 Force TLS/SSL version SSLv3. This might be needed to use SSL
458 with some old and broken servers. Do not use this unless you
459 have to.
460 tls_min_dh_prime_bits [bits]
462 Set or unset the minimum number of Diffie-Hellman (DH) prime
463 bits that mpop will accept for TLS sessions. The default is set
464 by the TLS library and can be selected by using an empty argu‐
465 ment to this command. Only lower the default (for example to
466 512 bits) if there is no other way to make TLS work with the
467 remote server.
468 tls_priorities [priorities]
470 Set the priorities for TLS sessions. The default is set by the
471 TLS library and can be selected by using an empty argument to
472 this command. Currently this command only works with suffi‐
473 ciently recent GnuTLS releases. See the GnuTLS documentation of
474 the gnutls_priority_init function for a description of the pri‐
475 orities string.
476 only_new [(on|off)]
478 By default, mpop processes only new messages (new messages are
479 those that were not already successfully retrieved in an earlier
480 session). If this option is turned off, mpop will process all
481 messages.
482 keep [(on|off)]
484 Keep all mails on the POP3 server, never delete them. The
485 default behaviour is to delete mails that have been successfully
486 retrieved or filtered by kill filters.
487 killsize (off|size)
489 Mails larger than the given size will be deleted (unless the
490 keep command is used, in which case they will just be skipped).
491 The size argument must be zero or greater. If it is followed by
492 a `k' or an `m', the size is measured in kibibytes/mebibytes
493 instead of bytes. Note that some POP3 servers report slightly
494 incorrect sizes for mails; see NOTES below.
495 When killsize is set to 0 and keep is set to on, then all mails
496 are marked as retrieved, but no mail gets deleted from the
497 server. This can be used to synchronize the UID list on the
498 client to the UID list on the server.
499 skipsize (off|size)
501 Mails larger than the given size will be skipped (not down‐
502 loaded). The size argument must be zero or greater. If it is
503 followed by a `k' or an `m', the size is measured in
504 kibibytes/mebibytes instead of bytes. Note that some POP3
505 servers report slightly incorrect sizes for mails; see NOTES
506 below.
507 filter [command]
509 Set a filter which will decide whether to retrieve, skip, or
510 delete each mail by investigating the mail's headers. The POP3
511 server must support the POP3 TOP command for this to work; see
512 option --serverinfo above. An empty argument disables filtering.
513 All occurences of %F in the command will be replaced with the
514 envelope from address of the current message (or MAILER-DAEMON
515 if none is found). Note that this address is guaranteed to con‐
516 tain only letters a-z and A-Z, digits 0-9, and any of ".@_-+/",
517 even though that is only a subset of what is theoretically
518 allowed in a mail address. Other characters, including those
519 interpreted by the shell, are replaced with "_". Nevertheless,
520 you should put %F into single quotes: '%F'.
521 All occurences of %S in the command will be replaced with the
522 size of the current mail as reported by the POP3 server.
523 The mail headers (plus the blank line separating the headers
524 from the body) will be piped to the command. Based on the return
525 code, mpop decides what to do with the mail:
526 0: proceed normally; no special action
527 1: delete the mail; do not retrieve it
528 2: skip the mail; do not retrieve it
529 Return codes greater than or equal to 3 mean that an error
530 occured. The sysexits.h error codes may be used to give informa‐
531 tion about the kind of the error, but this is not necessary.
532
534 There are three filtering commands available. They will be executed in
535 the following order:
536 killsize
537 skipsize
538 filter
539 If a filtering command applies to a mail, the remaining filters will
540 not be executed.
541
543 Configuration file
544 # Default values for all accounts.
546 defaults
547 # Activate TLS.
548 tls on
549 # Enable full TLS certificate checks.
550 tls_trust_file /etc/ssl/certs/ca-certificates.crt
551 # Use the POP3-over-TLS variant instead of the STARTTLS variant.
552 # This is often called "POP3 with SSL". Most servers support this.
553 tls_starttls off
554 # Use the procmail mail delivery agent.
555 delivery mda "/usr/bin/procmail -f '%F' -d $USER"
556 # For Sendmail:
557 #delivery mda "/usr/sbin/sendmail -oi -oem -f '%F' -- $USER"
558 # For msmtp (delivery via SMTP):
559 #delivery mda "/usr/bin/msmtp --host=localhost --from='%F' -- $USER"
560 # Delivery to a maildir folder:
561 #delivery maildir ~/Mail/incoming
562 # Delivery to a MBOX mail folder:
563 #delivery mbox ~/Mail/new
564 # Delivery to an Exchange pickup directory:
565 #delivery exchange c:\exchange\pickup
566 # Two pop3 mailboxes at the provider.
568 account provider1
569 host mx.provider.example
570 user john_smith
571 password secret
572 # Copy the settings from the previous account, and only override the
573 # settings that differ.
574 account provider2 : provider1
575 user joey
576 password secret2
577 # A freemail service.
579 account freemail
580 host pop.freemail.example
581 user 1238476
582 passwordeval gpg -d ~/.mpop.password.gpg
583 # Set a default account (optional).
585 account default : provider1
586 Filtering with SpamAssassin
589 The command filter "/path/to/spamc -c > /dev/null" will delete all
591 mails that SpamAssassin thinks are spam. Since no message body is
592 passed to SpamAssassin, you should disable all body-specific tests in
593 the SpamAssassin configuration file; for example set use_bayes 0.
594 If your mail provider runs SpamAssassin for you, you just have to check
596 for the result. The following script can do that when used as an mpop
597 filter:
598 #!/bin/sh
599 if [ "`grep "^X-Spam-Status: Yes"`" ]; then
600 exit 1 # kill this message
601 else
602 exit 0 # proceed normally
603 fi
604 Since the filter command is passed to a shell, you can also use this
605 directly:
606 filter if [ "`grep "^X-Spam-Status: Yes"`" ]; then exit 1; else exit 0;
607 fi
608
611 ~/.mpoprc
612 Default configuration file.
613 ~/.mpop_uidls
615 Default directory to store UIDLs files in.
616 ~/.netrc and SYSCONFDIR/netrc
618 The netrc file contains login information. If a password is not
619 found in the configuration file, mpop will search it in ~/.netrc
620 and SYSCONFDIR/netrc before prompting the user for it. The syn‐
621 tax of netrc files is described in netrc(5) or ftp(1).
622 $USER, $LOGNAME
624 These variables override the user's login name. $LOGNAME is only
625 used if $USER is unset. The user's login name is used for
626 Received headers.
627 $TMPDIR
629 Directory to create temporary files in. If this is unset, a sys‐
630 tem specific default directory is used.
631
633 Some POP3 servers still do not support the UIDL command. In this case,
634 mpop cannot recognize messages that were already successfully
635 retrieved, and will treat all messages as new. Use the --serverinfo
636 option to find out if a server supports the UIDL command.
637 Some POP3 servers count end-of-line characters as two bytes (CRLF)
638 instead of one (LF), so that the size of a mail as reported by the POP3
639 server is slightly larger than the actual size. This has the following
640 consequences: The size filters are not accurate. Do not rely on exact
641 size filtering. The progress output may display inaccurate (slightly
642 too low) percentage values for the first mail retrieved from a POP3
643 server. mpop will detect this after the first mail has been read and
644 will display corrected values for subsequent mails.
645
647 mpop was written by Martin Lambers <marlam@marlam.de>
648 Other authors are listed in the AUTHORS file in the source distribu‐
649 tion.
650
652 procmail(1), spamassassin(1), fetchmail(1), getmail(1), netrc(5) or
653 ftp(1), mbox(5), fcntl(2)
654 2011-01 MPOP(1)