.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "imap-dl 1"
.TH imap-dl 1 "Debian Project" "perl v5.32.0" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
imap\-dl \-\- fetch messages from an IMAP inbox into a maildir
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBimap-dl\fR [\fB\-v\fR|\fB\-\-verbose\fR] \fBconfigfile\fR...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBimap-dl\fR tries to retrieve all messages from an \s-1IMAP\s0 inbox and put
them in a maildir.
.PP
If you use getmail to reach an \s-1IMAP\s0 server as though it were \s-1POP\s0
(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 \fBimap-dl\fR.
.PP
\&\fBimap-dl\fR 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.
.PP
If there's any interest in supporting other similarly simple use cases
for fetching messages from an \s-1IMAP\s0 account into a maildir, patches are
welcome.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fB\-v\fR or \fB\-\-verbose\fR causes \fBimap-dl\fR to print more details
about what it is doing.
.SH "CONFIGFILE OPTIONS"
.IX Header "CONFIGFILE OPTIONS"
\&\fBimap-dl\fR uses an ini-style configfile, with [Sections] which each
have keyword arguments within them.  We use the syntax \fBfoo.bar\fR here
to mean keyword \fBbar\fR in section \fBfoo\fR.  \fBimap-dl\fR inherits some
basic configuration options from \fBgetmail\fR, including the following
options:
.PP
\&\fBretriever.server\fR is the dns name of the mailserver.
.PP
\&\fBretriever.authentication\fR is either \*(L"basic\*(R" (the default, using the
\&\s-1IMAP LOGIN\s0 verb) or \*(L"gssapi\*(R" (\s-1IMAP AUTHENTICATE\s0 with \s-1GSSAPI,\s0 requires
the python3\-gssapi module). \*(L"kerberos\*(R" is an alias for \*(L"gssapi\*(R".
.PP
\&\fBretriever.username\fR is the username of the \s-1IMAP\s0 account.
.PP
\&\fBretriever.password\fR is the password for the \s-1IMAP\s0 account when
\&\fBretriever.authentication\fR is set to \*(L"basic\*(R".
.PP
\&\fBretriever.ssl_ciphers\fR is an OpenSSL cipher string to use instead of the
defaults.  (The defaults are good; this should be avoided except to work
around bugs.)
.PP
\&\fBdestination.path\fR is the location of the target maildir.
.PP
\&\fBoptions.delete\fR is a boolean, whether to delete the messages that
were successfully retreived (default: false).
.PP
In addition to parts of the standard \fBgetmail\fR configuration,
\&\fBimap-dl\fR supports the following keywords in the configfile:
.PP
\&\fBoptions.on_size_mismatch\fR can be set to \fBerror\fR, \fBnone\fR, or
\&\fBwarn\fR.  This governs what to do when the remote \s-1IMAP\s0 server claims a
different size in the message summary list than the actual message
retrieval (default: \fBerror\fR).
.SH "EXAMPLE CONFIGFILE"
.IX Header "EXAMPLE CONFIGFILE"
This configfile fetches all the mail from the given \s-1IMAP\s0 account's
inbox, and deletes the messages when they are successfully fetched:
.Sp
.Vb 4
\&    [retriever]
\&    server = mail.example.net
\&    username = foo
\&    password = sekr1t!
\&
\&    [destination]
\&    path = /home/foo/Maildir
\&
\&    [options]
\&    delete = True
.Ve
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
\&\fBimap-dl\fR is currently deliberately minimal.  It is designed to be
used by someone who treats their \s-1IMAP\s0 mailbox like a \s-1POP\s0 server.
.PP
It works with IMAP-over-TLS only, and it just fetches all messages
from the default \s-1IMAP\s0 folder.  It does not support all the various
features of getmail.
.PP
\&\fBimap-dl\fR is deliberately implemented in a modern version of python3,
and tries to use just the standard library.  It will not be backported
to python2.
.PP
\&\fBimap-dl\fR 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.
.PP
\&\fBimap-dl\fR does not know how to wait and listen for new mail using
\&\s-1IMAP IDLE.\s0  This would be a nice additional feature.
.PP
\&\fBimap-dl\fR does not yet know how to deliver to an \s-1MDA\s0 (or to
\&\fBnotmuch-insert\fR).  This would be a nice thing to be able to do.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
https://tools.ietf.org/html/rfc3501, http://pyropus.ca/software/getmail/
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\fBimap-dl\fR and this manpage were written by Daniel Kahn Gillmor,
inspired by some functionality from the getmail project.