=head1 NAME

lei-mail-formats - description of mail formats supported by lei

=head1 DESCRIPTION

L<lei-q(1)> supports writing to several existing mail formats
for interoperability with existing mail user agents (MUA);
below is an overview of them to help users choose.

=head1 Maildir

The default output format when given a filesystem path, it supports
parallel read-write access.  Performance is acceptable for smaller
directories, but degrades as mailboxes get larger.  Speed and
scalability are limited by kernel and filesystem performance
due to the use of small files and large number of syscalls.

See also: L<https://cr.yp.to/proto/maildir.html> and
L<https://wiki2.dovecot.org/MailboxFormat/Maildir>

=head1 Mbox family

The mbox family consists of several incompatible formats.
Locking for parallel access is supported, but may not be
compatible across tools.  With compression (e.g. L<gzip(1)>),
they require the least amount of space while offering good
read-only performance.

Keyword updates (C<Status:> and/or C<X-Status:> headers)
generally require rewriting the entire mbox.

See also:
L<https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>,
L<mbox(5)>

=head2 mboxo

The traditional BSD format.  It quotes C<From > to C<E<gt>From >,
but lines already beginning with C<E<gt>From > do not get quoted,
thus automatic reversibility is not guaranteed.  MUAs which favor
L</mboxcl> or L</mboxcl2> may convert these automatically to their
preferred format.

Truncation is undetectable unless compressed with gzip or similar.

=head2 mboxrd

An evolution of L</mboxo>, but quotes C<From > lines prefixed
with any number of C<E<gt>> characters and is thus fully
reversible.

This format is emitted by L<PublicInbox::WWW(3pm)> with gzip.
Since git 2.10, C<git am --patch-format=mboxrd> reads this
format.  C<git log> and C<git format-patch --stdout> can also
generate this format with the C<--pretty=mboxrd> switch.

As with uncompressed L</mboxo>, uncompressed mboxrd are vulnerable
to undetectable truncation.

It gracefully degrades to being treated as L</mboxo> by MUAs
unaware of the format as excessive C<E<gt>From > quoting is
recognizable to humans.

=head2 mboxcl

L</mboxo> with a C<Content-Length:> header, C<From > lines
remain quoted to retain readability with L</mboxo> and L</mboxrd> MUAs.
However, it is easy to corrupt these files when using tools
which are not aware of C<Content-Length:> and write out updates
as L</mboxo>.

L<mutt(1)> will convert L</mboxo> and L</mboxrd> to mboxcl upon opening.

See also: L<https://www.jwz.org/doc/content-length.html>

=head2 mboxcl2

Like L</mboxcl>, but without C<From > any quoting.  It is wholly
incompatible with MUAs which only handle L</mboxo> and/or L</mboxrd>.
This is format is generated by L<mutt(1)> when writing to a new
mbox.

=head1 MH

Preliminary support for reads as of 2.0.0.  Locking semantics differ
incompatibly amongst existing writers: Python and nmh appear
compatible with each other, while mutt appears racy and unsuitable
for parallel access due to rename(2) potentially clobbering the
C<.mh_sequences> file.  More info about other clients is greatly
appreciated.

Sequence numbers may be packed and reused by some writers, so lei
users may need to run L<lei-refresh-mail-sync(1)> if inotify|kevent
missed packing while L<lei-daemon(8)> wasn't running.

lei is safe for reading mlmmj archives as MH since mlmmj neither
packs nor uses a .mh_sequences file to store state.

=head1 MMDF

Not yet supported, and it's unclear if current usage/support makes
it worth supporting.

=head1 IMAP

Depending on the IMAP server software and configuration, IMAP
servers may use any (or combination) of the aforementioned
formats or a non-standard database backend.  Currently, lei
uses L<Mail::IMAPClient> which has acceptable performance
over low-latency links.  Performance over high-latency links
is currently poor.

=head1 eml

A single raw message file.  C<eml> is not an output format for lei,
but accepted by as an C<--input-format> (C<-F>) for read-only
commands such as L<lei-tag(1)> and L<lei-import(1)>.

Since C<eml> is the suffix for the C<message/rfc822> MIME type
(according to the C<mime.types> file), lei will infer the type
based on the C<.eml> suffix if C<--input-format> is unspecified

C<.patch>-suffixed files generated by L<git-format-patch(1)>
(without C<--stdout>) are C<eml> files with the addition of an
mbox C<From > header.  L<lei(1)> removes C<From > lines to treat
them as C<eml> when reading these for compatibility with
C<git-am(1)> and similar tools.

=head1 COPYRIGHT

Copyright 2021 all contributors L<mailto:meta@public-inbox.org>

License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>

=head1 SEE ALSO

L<lei(1)>, L<lei-q(1)>, L<lei-convert(1)>, L<lei-overview(7)>