imap-dl(1)

📦
version 31 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, welcome to imap-dl — it's a User Commands manual page, and what it does is fetch messages from an IMAP inbox into a maildir. that's the whole vibe. 💖

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

imap-dl tries to retrieve all the messages from an IMAP inbox and put them in a maildir. literally all of them. no crumbs left behind. 💅

If you use getmail to reach an IMAP server as though it were POP — like, retrieving from the server, storing it in a maildir, and optionally deleting — then 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. iykyk. 🫶

imap-dl tries to ensure that the configuration file is of the expected type, and otherwise it will terminate with an error. and the important part: it should never lose e-mail messages. not one. periodt. 🎀

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. bestie we are begging you, send patches. 🙈

💅 OPTIONS 💅

  • -v or --verbose — causes imap-dl to print more details about what it is doing. it's giving main character energy, it's telling you its whole lore.

🎀 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.) > not me touching the ciphers when the defaults are literally fine 😭
  • 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. iconic behavior honestly.

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. it's a minimalist queen, she contains multitudes but only like two of them.

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. nope. never. the past is the past.

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. the way that it just sits there waiting... 😭

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. absolute legend, ate and left no crumbs. 🫶

and that's the whole page bestie!! this was rendered from imap-dl(1), perl v5.40.1, from the Debian Project — mwah, go fetch your mail, ily, bye!! 💖✨🎀🦋

📦 where this page comes from