From b5c73d9c198c175fa5dcf48ed6e280a0d3cfa489 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Mon, 23 Jul 2018 07:44:27 +0200 Subject: [PATCH] doc: Specify how imag-mail should look like --- doc/src/04020-module-mails.md | 281 ++++++++++++++++++++++++++++++++-- 1 file changed, 268 insertions(+), 13 deletions(-) diff --git a/doc/src/04020-module-mails.md b/doc/src/04020-module-mails.md index 3c46ae97..bfaed6ab 100644 --- a/doc/src/04020-module-mails.md +++ b/doc/src/04020-module-mails.md @@ -26,17 +26,272 @@ for the outgoing mails. The CLI of the imag-mail module is planned as follows: - imag mail track [opts...] # track a new mail, mail file passed as path - imag mail scan [opts...] # scan a maildir and track all untracked mails - imag mail box # work with the mailbox specified by , name mappings from config - imag mail list # list mails in a given mailbox for a given account or the default account - imag mail show # open new mails in the pager - imag mail thread list # list mails from a thread - imag mail thread show # open new mails from a thread in the pager or call a script with them - imag mail new # craft a new mail and safe it in the folder - imag mail compose # same as 'new' - imag mail send # send emails from the outgoing folder, optionally also move them to archive boxes - imag mail mv # move a mail to another mailbox - imag mail mv thread # move the thread of the mail to another mailbox - imag mail find # search for a mail (by header field (msgid, from, to, cc, subject, date, date-range), body, ...) +* imag mail + + Requires configuration: + * mail.outgoingbox + * mail.accounts..maildirroot + + -A, --account - Specify the "account" to use for the opperation. + A account is nothing more than a mapping of a name to a + path where the Maildirs are located. It is specified in + the imag configuration file. + For example: + + private -> ~/.mails/personal + + If none is specified, the configuration is searched for a + "maildir" setting (where all Maildirs are found in). If + there is no such setting, imag-mail fails. + (or: read in documentation for --box). + + -B, --box - Specify a temporary location for a Maildir to work with. + +* imag mail track [opts...] + Track a new mail, mail file passed as path + + --refind - re-find messages. Loads all messages which are known to imag + and compares identifiers, to update the imag-internal cache if + a mail got moved + + -O, --output-id - print the store id for the new (or in case of --refind + updated) imag entry + +* imag mail scan [opts...] + Scan a maildir and track all untracked mails + + --refind - re-find messages. Loads all messages which are known to imag + and compares identifiers, to update the imag-internal cache if + a mail got moved + + -O, --output-id - print the store id for the new (or in case of --refind + updated) imag entry + +* imag mail list + List mails in a given mailbox for a given account or the default account + + -S, --style - print messages in a certain style + Available: + - 'linewise' + - 'thread' + + -g, --grep - Filter by grepping for a pattern in body and subject + + -d, --daterange - Filter by date(range) + + -F, --filter - Filter by passed filter + + --thread - Print only messages from the same thread as the found ones + + --format= - Format mails for showing. + --format always colorizes output (specify color in config) + except when using --no-pager or piping output. + + When --tree is passed, the format is applied to the + fragment _after_ the tree graphic. + + Default mode is 'default'. + + Modes: + - 'subject': + - 'simple': : + - 'default': - : + - 'fmt:' format with passed format + + Additional formats can be specified via the configuration + file. If a format has the same name as a predefined one, + the config overrides the predefined formats. + + --color - Colorize output (default). + --no-color - Do never colorize output. + +* imag mail show + Show mail(s) - either in pager or by printing them to stdout. + + Mails are specified by message id or imag entry + + --refind - If a imag entry is passed but the mail file is not there, + try to re-find it. + + --refind-in - Same as --refind, but a path to a Maildir or a tree of + Maildirs might be passed to narrow down search space. + + -C, --concat - Open all mails in one pager (by concatenating them) + instead of one pager per message. + + --pager - Use pager to show mails (default). + + --no-pager - Do not use pager to show mails. + + --multipager - Pass all mails as arguments to one pager call instead of + calling the pager on each mail individually (default). + Only possible with --pager. + + --no-multipager - Disable --multipager. + Only possible with --pager. + + --format= - Format mails for showing. + --format always colorizes emails (specify color in config) + except when using --no-pager or piping output. + + Modes: + - 'simple': Remove headers, except + From, To, Cc, Subject, Date, + Message-Id/References/In-Reply-To + - 'simple-imag': Same as 'simple' but also show imag + entry id. + - 'print': Show everything + - 'full': Show everything and add imag entry id + - 'minimal': Remove headers, except From, To, Cc, Subject, Date, + - 'tiny': Remove headers, except From, To, Subject + - 'fmt:' format with passed format + + Additional formats can be specified via the configuration + file. If a format has the same name as a predefined one, + the config overrides the predefined formats. + + --no-format - Disable all formatting (same as --pretty=print and + disabling color output). + + --color - Colorize output (default). + --no-color - Do never colorize output. + +* imag mail new + Craft a new mail and safe it in the folder + + Requires configuration: + * mail.accounts..draftbox + * mail.accounts..outgoingbox + + --outbox - Specify the outbox for where the new mail should be stored + in, if it is not given in the config (or to override it) + + --to - Specify to whom to send. + If the specified string does not contain a valid email + address, `imag contact find` is used to find the email + address (if not suppressed via --no-autofind). + Multiple allowed. + + --cc - Specify to whom to send in CC. + If the specified string does not contain a valid email + address, `imag contact find` is used to find the email + address (if not suppressed via --no-autofind). + Multiple allowed. + + --bcc - Specify to whom to send in BCC. + If the specified string does not contain a valid email + address, `imag contact find` is used to find the email + address (if not suppressed via --no-autofind). + Multiple allowed. + + --no-autofind - Do not automatically find contacts + with `imag contact find`. + + --fcc - Specify to store a copy of the mail somewhere. + Multiple allowed. + + --subject - Specify subject. + + --gpg-sign - Sign with gpg. + + --gpg-crypt - Crypt with gpg to all recipients. + + --no-track - Do not track new mailfile with imag. + + -D, --draft - Do not safe in "outgoing" box but rather in "draft" box. + +* imag mail compose + Same as 'new'. + +* imag mail fetch + Fetch emails + + Requires configuration: + * mail.fetchcommand or mail.accounts..fetchcommand + * mail.postfetchcommand or mail.accounts..postfetchcommand (optional) + + --all - Fetch for all accounts + --boxes - Fetch only some boxes (does not work with --all) + +* imag mail send + Send emails from the outgoing folder, also move them to 'sent' boxes + + Requires configuration: + * mail.accounts..outgoingbox + * mail.accounts..sentbox + * mail.sendcommand or mail.accounts..sendcommand + * mail.postsendcommand or mail.accounts..postsendcommand (optional) + + --outbox - Specify the outbox for where the mails that are about to + be send are stored in, if it is not given in the config + (or to override it). + + --sentbox - Specify the sentbox for where the sent mails should be + moved after sending them, if it is not given in the config + (or to override it). + + --no-move-sent - Do not move mail to the "sent" folder after sending it. + + --confirm - Confirm each mail before sending (default). + + --no-confirm - Do not confirm each mail before sending. + + --no-track - Do not track mailfile with imag. Does only work if `imag + mail new` was invoked with `--no-track` (so that the mail + is not tracked already). + +* imag mail mv + Move a mail to another mailbox + + --thread - Move the complete thread of emails belonging to the + specified mail. + + --no-track - Do not track new mailfile with imag. Does not work if + mailfile is already tracked with imag. + +* imag mail find + Search for a mail (by header field (msgid, from, to, cc, subject, date, + date-range), body, ...) + + --msgid + --no-msgid + --from + --no-from + --to + --no-to + --cc + --no-cc + --subject + --no-subject + --date + --no-date + --body + --no-body + --daterange - Toggle where to look at + + --print-entryid - Print imag entry id when finding mail + --no-print-entryid - Do not print imag entry id when finding mail (default). + + --print= - What to print for the found mails. + Valid values: + - msgid + - subject + - from + - cc + - to + - date + - filepath (default) + +* imag mail reply + Reply to an email. + + Requires configuration: mail.accounts..outgoingbox + + Specify the mail to reply to by msgid, filepath or imag entry id. + + --add-to + --add-cc + --add-bcc - Add another recipient. Multiple allowed. + + --no-track - Do not track new mailfile with imag.