summaryrefslogtreecommitdiff
path: root/imap-dl.1.pod
diff options
context:
space:
mode:
authorDaniel Kahn Gillmor <dkg@fifthhorseman.net>2020-02-08 12:37:12 -0500
committerSean Whitton <spwhitton@spwhitton.name>2020-02-14 07:23:45 -0700
commitd5d771291fb4c3996ebfc31a9964917313c6345a (patch)
treebea717665eb90ccb1d3f8b0e2ac1e6805cf5d568 /imap-dl.1.pod
parentf80ebce51666980e345b734e1c446ed5ee8a8be2 (diff)
downloadmailscripts-d5d771291fb4c3996ebfc31a9964917313c6345a.tar.gz
Add imap-dl, a simple imap downloader
getmail upstream appears to have no plans to convert to python3 in the near future. Some of us use only a minimal subset of features of getmail, and it would be nice to have something simpler, with the main complexity offloaded to the modern python3 stdlib. This patch represents a squashed series of changes from both Jameson Graef Rollins and Daniel Kahn Gillmor (dkg), though dkg is primarily responsible for any remaining bugs. Thanks to Sean Whitton for useful and significant feedback. Signed-off-by: Jameson Graef Rollins <jrollins@finestructure.net> Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
Diffstat (limited to 'imap-dl.1.pod')
-rw-r--r--imap-dl.1.pod88
1 files changed, 88 insertions, 0 deletions
diff --git a/imap-dl.1.pod b/imap-dl.1.pod
new file mode 100644
index 0000000..9fb77c3
--- /dev/null
+++ b/imap-dl.1.pod
@@ -0,0 +1,88 @@
+=encoding utf8
+
+=head1 NAME
+
+imap-dl -- a simple replacement for a minimalist user of getmail
+
+=head1 SYNOPSIS
+
+B<imap-dl> [B<-v>|B<--verbose>] B<configfile>...
+
+=head1 DESCRIPTION
+
+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 config and it
+should do the same thing.
+
+It tries to ensure that the configuration file is of the expected
+type, and otherwise it will terminate with an error. It should not
+lose e-mail messages.
+
+If there's any interest in supporting other similarly simple use cases
+for getmail, patches are welcome.
+
+=head1 OPTIONS
+
+B<-v> or B<--verbose> causes B<imap-dl> to print more details
+about what it is doing.
+
+In addition to parts of the standard B<getmail> configuration,
+B<imap-dl> supports the following keywords in the config file:
+
+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 CONFIG
+
+If you've never used getmail, you can make the simplest possible
+config file like so:
+
+=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.