NAME

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

SYNOPSIS

       imap-dl [-v|--verbose] configfile...

DESCRIPTION

       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 imap-dl.

       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.

OPTIONS

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

CONFIGFILE OPTIONS

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

       retriever.server is the dns name of the mailserver.

       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".

       retriever.username is the username of the IMAP account.

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

       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.)

       destination.path is the location of the target maildir.

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

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

       options.on_size_mismatch can be set to error, none, or 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: error).

EXAMPLE CONFIGFILE

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

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

           [destination]
           path = /home/foo/Maildir

           [options]
           delete = True

LIMITATIONS

       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.

       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.

       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.

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

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

SEE ALSO

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

AUTHOR

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