=encoding utf8

=head1 NAME

imap-dl -- fetch messages from an IMAP inbox into a maildir

=head1 SYNOPSIS

B<imap-dl> [B<-v>|B<--verbose>] B<configfile>...

=head1 DESCRIPTION

B<imap-dl> tries to retrieve all messages from an IMAP inbox and put
them in a maildir.

If you use getmail to reach an IMAP server as though it were POP
(retrieving from the server, storing it in a maildir and optionally
deleting), you can point this script to the getmail configfile and it
should do the same thing.  While the minimal configuration file
matches the syntax for common getmail configurations, some other
options might be specific to B<imap-dl>.

B<imap-dl> tries to ensure that the configuration file is of the
expected type, and otherwise it will terminate with an error.  It
should never lose e-mail messages.

If there's any interest in supporting other similarly simple use cases
for fetching messages from an IMAP account into a maildir, patches are
welcome.

=head1 OPTIONS

B<-v> or B<--verbose> causes B<imap-dl> to print more details
about what it is doing.

=head1 CONFIGFILE OPTIONS

B<imap-dl> uses an ini-style configfile, with [Sections] which each
have keyword arguments within them.  We use the syntax B<foo.bar> here
to mean keyword B<bar> in section B<foo>.  B<imap-dl> inherits some
basic configuration options from B<getmail>, including the following
options:

B<retriever.server> is the dns name of the mailserver.

B<retriever.authentication> is either "basic" (the default, using the
IMAP LOGIN verb) or "gssapi" (IMAP AUTHENTICATE with GSSAPI, requires
the python3-gssapi module). "kerberos" is an alias for "gssapi".

B<retriever.username> is the username of the IMAP account.

B<retriever.password> is the password for the IMAP account when
B<retriever.authentication> is set to "basic".

B<retriever.ssl_ciphers> is an OpenSSL cipher string to use instead of the
defaults.  (The defaults are good; this should be avoided except to work
around bugs.)

B<destination.path> is the location of the target maildir.

B<options.delete> is a boolean, whether to delete the messages that
were successfully retreived (default: false).

In addition to parts of the standard B<getmail> configuration,
B<imap-dl> supports the following keywords in the configfile:

B<options.on_size_mismatch> can be set to B<error>, B<none>, or
B<warn>.  This governs what to do when the remote IMAP server claims a
different size in the message summary list than the actual message
retrieval (default: B<error>).

=head1 EXAMPLE CONFIGFILE

This configfile fetches all the mail from the given IMAP account's
inbox, and deletes the messages when they are successfully fetched:

=over 4

    [retriever]
    server = mail.example.net
    username = foo
    password = sekr1t!

    [destination]
    path = /home/foo/Maildir

    [options]
    delete = True

=back

=head1 LIMITATIONS

B<imap-dl> is currently deliberately minimal.  It is designed to be
used by someone who treats their IMAP mailbox like a POP server.

It works with IMAP-over-TLS only, and it just fetches all messages
from the default IMAP folder.  It does not support all the various
features of getmail.

B<imap-dl> is deliberately implemented in a modern version of python3,
and tries to use just the standard library.  It will not be backported
to python2.

B<imap-dl> uses imaplib, which means that it does synchronous calls to
the imap server.  A more clever implementation would use asynchronous
python to avoid latency/roundtrips.

B<imap-dl> does not know how to wait and listen for new mail using
IMAP IDLE.  This would be a nice additional feature.

B<imap-dl> does not yet know how to deliver to an MDA (or to
B<notmuch-insert>).  This would be a nice thing to be able to do.

=head1 SEE ALSO

https://tools.ietf.org/html/rfc3501, http://pyropus.ca/software/getmail/

=head1 AUTHOR

B<imap-dl> and this manpage were written by Daniel Kahn Gillmor,
inspired by some functionality from the getmail project.
