path: root/docs/meli.conf.5

.\" meli - meli.conf.5
.\"
.\" Copyright 2017-2019 Manos Pitsidianakis
.\"
.\" This file is part of meli.
.\"
.\" meli is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" meli is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with meli. If not, see <http://www.gnu.org/licenses/>.
.\"
.Dd November 11, 2022
.Dt MELI.CONF 5
.Os
.Sh NAME
.Nm meli.conf
.Nd configuration file for the
.Xr meli 1
terminal e-mail client
.Sh SYNOPSIS
.Pa $XDG_CONFIG_HOME/meli/config.toml
.Sh DESCRIPTION
Configuration for meli is written in TOML which has a few things to consider (quoting the spec):
.Pp
.Bl -bullet -compact
.It
TOML is case sensitive.
.It
A TOML file must be a valid UTF-8 encoded Unicode document.
.It
Whitespace means tab (0x09) or space (0x20).
.It
Newline means LF (0x0A) or CRLF (0x0D 0x0A).
.El
.Pp
Refer to TOML documentation for valid TOML syntax.
.sp
Though not part of TOML syntax,
.Nm
can have nested configuration files by using the following
.Xr m4 1
include macro:
.Dl include(\&"/path/to/file\&")
.Sh SECTIONS
The top level sections of the config are:
.Bl -bullet -compact
.It
accounts
.It
shortcuts
.It
notifications
.It
pager
.It
listing
.It
composing
.It
pgp
.It
terminal
.It
log
.El
.Sh EXAMPLES
example configuration
.sp
.Bd -literal
# Setting up a Maildir account
[accounts.account-name]
root_mailbox = "/path/to/root/folder"
format = "Maildir"
listing.index_style = "Compact"
identity="email@example.com"
subscribed_mailboxes = ["folder", "folder/Sent"] # or [ "*", ] for all mailboxes
display_name = "Name"

# Set mailbox-specific settings
  [accounts.account-name.mailboxes]
  "INBOX" = { alias="Inbox" } #inline table
  "drafts" = { alias="Drafts" } #inline table
  [accounts.account-name.mailboxes."foobar-devel"] # or a regular table
    ignore = true # don't show notifications for this mailbox

# Setting up an mbox account
[accounts.mbox]
root_mailbox = "/var/mail/username"
format = "mbox"
listing.index_style = "Compact"
identity="username@hostname.local"
composing.send_mail = { hostname = "localhost", port = 25, auth = { type = "none" }, security = { type = "none" } }

[pager]
filter = "COLUMNS=72 /usr/local/bin/pygmentize -l email"
html_filter = "w3m -I utf-8 -T text/html"

[notifications]
script = "notify-send"

[composing]
# required for sending e-mail
send_mail = 'msmtp --read-recipients --read-envelope-from'
#send_mail = { hostname = "smtp.example.com", port = 587, auth = { type = "auto", username = "user", password = { type = "command_eval", value = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" } }, security = { type = "STARTTLS" } }
editor_command = 'vim +/^$'

[shortcuts]
[shortcuts.composing]
edit_mail = 'e'

[shortcuts.listing]
new_mail = 'm'
set_seen = 'n'

[terminal]
theme = "light"
.Ed
.Pp
Available options are listed below.
Default values are shown in parentheses.
.Sh ACCOUNTS
.Bl -tag -width 36n
.It Ic root_mailbox Ar String
The backend-specific path of the root_mailbox, usually INBOX.
.It Ic format Ar String Op maildir mbox imap notmuch jmap
The format of the mail backend.
.It Ic subscribed_mailboxes Ar [String,]
An array of mailbox paths to display in the UI.
Paths are relative to the root mailbox (eg "INBOX/Sent", not "Sent").
The glob wildcard
.Em \&*
can be used to match every mailbox name and path.
.It Ic identity Ar String
Your e-mail address that is inserted in the From: headers of outgoing mail.
.It Ic extra_identities Ar [String,]
Extra e-mail address identities.
When replying to an e-mail addressed to one of these identities, the From: header will be adjusted to its value instead of the default identity.
.El
.TS
allbox tab(:);
lb l.
conversations:shows one entry per thread
compact:shows one row per thread
threaded:shows threads as a tree structure
plain:shows one row per mail, regardless of threading
.TE
.Bl -tag -width 36n
.It Ic display_name Ar String
.Pq Em optional
A name which can be combined with your address: "Name <email@example.com>".
.It Ic read_only Ar boolean
Attempt to not make any changes to this account.
.Pq Em false
.It Ic manual_refresh Ar boolean
.Pq Em optional
If true, do not monitor account for changes (you can use shortcut listing.refresh)
.Pq Em false
.It Ic refresh_command Ar String
.Pq Em optional
command to execute when manually refreshing (shortcut listing.refresh)
.Pq Em None
.It Ic search_backend Ar String
.Pq Em optional
Choose which search backend to use.
Available options are 'none' and 'sqlite3'
.Pq Em "sqlite3"
.It Ic vcard_folder Ar String
.Pq Em optional
Folder that contains .vcf files.
They are parsed and imported read-only.
.It Ic mailboxes Ar mailbox
.Pq Em optional
Configuration for each mailbox.
Its format is described below in
.Sx mailboxes Ns
\&.
.El
.Ss notmuch only
notmuch is supported by loading the dynamic library libnotmuch.
If its location is missing from your library paths, you must add it yourself.
Alternatively, you can specify its path by using a setting.
.Pp
notmuch mailboxes are virtual, since they are defined by user-given notmuch queries.
You must explicitly state the mailboxes you want in the
.Ic mailboxes
field and set the
.Ar query
property to each of them.
To create a tree hierarchy with virtual mailboxes, define the
.Ar parent
property to a mailbox as the name of the parent mailbox you have used in your configuration.
.Pp
Account properties:
.Bl -tag -width 36n
.It Ic root_mailbox
points to the directory which contains the
.Pa .notmuch/
subdirectory.
.It Ic library_file_path Ar Path
Use an arbitrary location of libnotmuch by specifying its full filesystem path.
.Pq Em optional
.El
Mailbox properties:
.Bl -tag -width 36n
.It Ic query Ar String
The notmuch query that defines what content this virtual mailbox has.
Refer to
.Xr notmuch-search-terms 7
for notmuch's search syntax.
.It Ic parent Ar String
If you wish to build a mailbox hierarchy, define the name of a parent mailbox you have used in your configuration.
.Pq Em optional
.El
Example:
.Bd -literal
[accounts.notmuch]
format = "notmuch"
#library_file_path = "/opt/homebrew/lib/libnotmuch.5.dylib"
\&...
  [accounts.notmuch.mailboxes]
  "INBOX" = {  query="tag:inbox", subscribe = true }
  "Drafts" = {  query="tag:draft", subscribe = true }
  "Sent" = {  query="from:username@example.com from:username2@example.com", subscribe = true }
  "Archives" = {  query="tag:archived", subscribe = true }
  "Archives/2019" = {  query="tag:archived date:01-2019..12-2019", parent="Archives", subscribe = true }
.Ed
.Ss IMAP only
IMAP specific options are:
.Bl -tag -width 36n
.It Ic server_hostname Ar String
example:
.Qq mail.example.com
.It Ic server_username Ar String
Server username
.It Ic server_password Ar String
Server password
.It Ic server_password_command Ar String
.Pq Em optional
Use instead of
.Ic server_password
.It Ic server_port Ar number
.Pq Em optional
The port to connect to
.\" default value
.Pq Em 143
.It Ic use_starttls Ar boolean
.Pq Em optional
If port is 993 and use_starttls is unspecified, it becomes false by default.
.\" default value
.Pq Em true
.It Ic danger_accept_invalid_certs Ar boolean
.Pq Em optional
Do not validate TLS certificates.
.\" default value
.Pq Em false
.It Ic use_idle Ar boolean
.Pq Em optional
Use IDLE extension.
.\" default value
.Pq Em true
.It Ic use_condstore Ar boolean
.Pq Em optional
Use CONDSTORE extension.
.\" default value
.Pq Em true
.It Ic use_deflate Ar boolean
.Pq Em optional
Use COMPRESS=DEFLATE extension (if built with DEFLATE support).
.\" default value
.Pq Em true
.It Ic use_oauth2 Ar boolean
.Pq Em optional
Use OAUTH2 authentication.
Can only be used with
.Ic server_password_command
which should return a base64-encoded OAUTH2 token ready to be passed to IMAP.
For help on setup with Gmail, see Gmail section below.
.\" default value
.Pq Em false
.It Ic timeout Ar integer
.Pq Em optional
Timeout to use for server connections in seconds.
A timeout of 0 seconds means there's no timeout.
.\" default value
.Pq Em 16
.El
.Ss Gmail
Gmail has non-standard IMAP behaviors that need to be worked around.
.Ss Gmail - sending mail
Option
.Ic store_sent_mail
should be disabled since Gmail auto-saves sent mail by its own.
.Ss Gmail OAUTH2
To use OAUTH2, you must go through a process to register your own private "application" with Google that can use OAUTH2 tokens.
For convenience in the meli repository under the
.Pa contrib/
directory you can find a python3 file named oauth2.py to generate and request the appropriate data to perform OAUTH2 authentication.
Steps:
.Bl -bullet -compact
.It
In Google APIs, create a custom OAuth client ID and note down the Client ID and Client Secret.
You may need to create a consent screen; follow the steps described in the website.
.It
Run the oauth2.py script as follows (after adjusting binary paths and credentials):
.Cm python3 oauth2.py --user=xxx@gmail.com --client_id=1038[...].apps.googleusercontent.com --client_secret=VWFn8LIKAMC-MsjBMhJeOplZ --generate_oauth2_token
and follow the instructions.
Note down the refresh token.
.It
In
.Ic server_password_command
enter a command like this (after adjusting binary paths and credentials):
.Cm TOKEN=$(python3 oauth2.py --user=xxx@gmail.com --quiet --client_id=1038[...].apps.googleusercontent.com --client_secret=VWFn8LIKAMC-MsjBMhJeOplZ --refresh_token=1/Yzm6MRy4q1xi7Dx2DuWXNgT6s37OrP_DW_IoyTum4YA) && python3 oauth2.py --user=xxx@gmail.com --generate_oauth2_string --quiet --access_token=$TOKEN
.It
On startup, meli should evaluate this command which if successful must only return a base64-encoded token ready to be passed to IMAP.
.El
.Ss JMAP only
JMAP specific options
.Bl -tag -width 36n
.It Ic server_url Ar String
example:
.Qq http://mail.example.com
.Qq http://mail.example.com:8080
.Qq https://mail.example.com
.It Ic server_username Ar String
Server username
.It Ic server_password Ar String
Server password
.It Ic danger_accept_invalid_certs Ar boolean
.Pq Em optional
Do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Ss mbox only
mbox specific options
.Bl -tag -width 36n
.It Ic prefer_mbox_type Ar String
.Pq Em optional
Prefer specific mbox format reader for each message.
Default is mboxcl2 format.
If the preferred format fails, the message is retried with mboxrd and then if it fails again there's a recover attempt, which discards the invalid message.
Valid values
.Bl -bullet -compact
.It
.Ar auto
.It
.Ar mboxo
.It
.Ar mboxrd
.It
.Ar mboxcl
.It
.Ar mboxcl2
.El
.\" default value
.Pq Em auto
.El
To set multiple mailboxes, you have to explicitly state the mailboxes you want in the
.Ic mailboxes
field and set the
.Ar path
property to each of them.
Example:
.Bd -literal
[accounts.mbox]
format = "mbox"
mailboxes."Python mailing list" = { path = "~/.mail/python.mbox", subscribe = true, autoload = true }
.Ed
.Ss NNTP
NNTP specific options
.Bl -tag -width 36n
.It Ic server_hostname Ar String
example:
.Qq nntp.example.com
.It Ic server_username Ar String
Server username
.It Ic server_password Ar String
Server password
.It Ic require_auth Ar bool
.Pq Em optional
require authentication in every case
.\" default value
.Pq Em true
.It Ic use_tls Ar boolean
.Pq Em optional
Connect with TLS.
.\" default value
.Pq Em false
.It Ic server_port Ar number
.Pq Em optional
The port to connect to
.\" default value
.Pq Em 119
.It Ic danger_accept_invalid_certs Ar boolean
.Pq Em optional
Do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Pp
You have to explicitly state the groups you want to see in the
.Ic mailboxes
field.
Example:
.Bd -literal
[accounts.sicpm.mailboxes]
  "sic.all" = {}
.Ed
.Pp
To submit articles directly to the NNTP server, you must set the special value
.Em server_submission
in the
.Ic send_mail
field.
Example:
.Bd -literal
composing.send_mail = "server_submission"
.Ed
.Ss MAILBOXES
.Bl -tag -width 36n
.It Ic alias Ar String
.Pq Em optional
Show a different name for this mailbox in the UI
.It Ic autoload Ar boolean
.Pq Em optional
Load this mailbox on startup
.\" default value
.Pq Em true
.It Ic collapsed Ar boolean
.Pq Em optional
Collapse this mailbox subtree in menu.
.\" default value
.Pq Em false
.It Ic subscribe Ar boolean
.Pq Em optional
Watch this mailbox for updates
.\" default value
.Pq Em true
.It Ic ignore Ar boolean
.Pq Em optional
Silently insert updates for this mailbox, if any
.\" default value
.Pq Em false
.It Ic usage Ar boolean
.Pq Em optional
special usage of this mailbox.
Valid values are:
.Bl -bullet -compact
.It
.Ar Normal
.Pq Em default
.It
.Ar Inbox
.It
.Ar Archive
.It
.Ar Drafts
.It
.Ar Flagged
.It
.Ar Junk
.It
.Ar Sent
.It
.Ar Trash
.El
otherwise usage is inferred from the mailbox title.
If for example your Sent folder is not named "Sent", you must explicitly set it.
.It Ic conf_override Ar boolean
.Pq Em optional
Override global settings for this mailbox.
Available sections to override are
.Em pager, notifications, shortcuts, composing
and the account options
.Em identity Ns
\&.
Example:
.Bd -literal
[accounts."imap.example.com".mailboxes]
  "INBOX" = { index_style = "plain" }
  "INBOX/Lists/devlist" = { autoload = false, pager = { filter = "pygmentize -l diff -f 256"} }
.Ed
.It Ic sort_order Ar unsigned integer
.Pq Em optional
Override sort order on the sidebar for this mailbox.
Example:
.Bd -literal
[accounts."imap.example.com".mailboxes]
  "INBOX" = { index_style = "plain" }
  "INBOX/Sent" = { sort_order = 0 }
  "INBOX/Drafts" = { sort_order = 1 }
  "INBOX/Lists" = { sort_order = 2 }
.Ed
.El
.Sh COMPOSING
Composing specific options
.Bl -tag -width 36n
.It Ic send_mail Ar String|SmtpServerConf
Command to pipe new mail to (exit code must be 0 for success) or settings for an SMTP server connection.
See section
.Sx SMTP Connections
for its fields.
.It Ic editor_command Ar String
Command to launch editor.
Can have arguments.
Draft filename is given as the last argument.
If it's missing, the environment variable $EDITOR is looked up.
.It Ic embed Ar boolean
.Pq Em optional
Embed editor within meli.
Editor must be xterm compliant.
.\" default value
.Pq Em false
.It Ic format_flowed Ar boolean
.Pq Em optional
Set format=flowed [RFC3676] in text/plain attachments.
.\" default value
.Pq Em true
.It Ic insert_user_agent Ar boolean
.Pq Em optional
Add meli User-Agent header in new drafts
.\" default value
.Pq Em true
.It Ic default_header_values Ar hash table String[String]
.Pq Em optional
Default header values used when creating a new draft.
.\" default value
.Pq Em []
.It Ic wrap_header_preamble Ar Option<(String, String)>
.Pq Em optional
Wrap header preample when editing a draft in an editor.
This allows you to write non-plain text email without the preamble creating syntax errors.
They are stripped when you return from the editor.
The values should be a two element array of strings, a prefix and suffix.
This can be useful when for example you're writing Markdown; you can set the value to
.Em ["<!--",\ "-->"]
which wraps the headers in an HTML comment.
.\" default value
.Pq Em None
.It Ic store_sent_mail Ar boolean
.Pq Em optional
Store sent mail after successful submission.
This setting is meant to be disabled for non-standard behaviour in gmail, which auto-saves sent mail on its own.
.\" default value
.Pq Em true
.It Ic attribution_format_string Ar String
.Pq Em optional
The attribution line appears above the quoted reply text.
The format specifiers for the replied address are:
.Bl -bullet -compact
.It
.Li %+f
— the sender's name and email address.
.It
.Li %+n
— the sender's name (or email address, if no name is included).
.It
.Li %+a
— the sender's email address.
.El
The format string is passed to
.Xr strftime 3
with the replied envelope's date.
.\" default value
.Pq Em "On %a, %0e %b %Y %H:%M, %+f wrote:%n"
.It Ic attribution_use_posix_locale Ar boolean
.Pq Em optional
Whether the strftime call for the attribution string uses the POSIX locale instead of the user's active locale.
.\" default value
.Pq Em true
.It Ic forward_as_attachment Ar boolean or "ask"
.Pq Em optional
Forward emails as attachment? (Alternative is inline).
.\" default value
.Pq Em ask
.It Ic reply_prefix_list_to_strip Ar [String]
.Pq Em optional
Alternative lists of reply prefixes (etc. ["Re:", "RE:", ...]) to strip.
.\" default value
.Pq Em ["Re:", "RE:", "Fwd:", "Fw:", "回复:", "回覆:", "SV:", "Sv:", "VS:", "Antw:", "Doorst:", "VS:", "VL:", "REF:", "TR:", "TR:", "AW:", "WG:", "ΑΠ:", "Απ:", "απ:", "ΠΡΘ:", "Πρθ:", "πρθ:", "ΣΧΕΤ:", "Σχετ:", "σχετ:", "ΠΡΘ:", "Πρθ:", "πρθ:", "Vá:", "Továbbítás:", "R:", "I:", "RIF:", "FS:", "BLS:", "TRS:", "VS:", "VB:", "RV:", "RES:", "Res", "ENC:", "Odp:", "PD:", "YNT:", "İLT:", "ATB:", "YML:"]
.It Ic reply_prefix Ar String
.Pq Em optional
The prefix to use in reply subjects.
The de facto prefix is "Re:".
.\" default value
.Pq Em `Re:`
.Pp
RFC 2822, "Internet Message Format" has this to say on the matter:
.Bd -literal -offset indent -compact
When used in a reply, the field body MAY start with the string "Re: " (from
the Latin "res", in the matter of) followed by the contents of the "Subject:"
field body of the original message.
.Ed
.El
.Sh SHORTCUTS
Shortcuts can take the following values:
.Bl -bullet -compact
.It
.Em Backspace
.It
.Em Left
.It
.Em Right
.It
.Em Up
.It
.Em Down
.It
.Em Home
.It
.Em End
.It
.Em PageUp
.It
.Em PageDown
.It
.Em Delete
.It
.Em Insert
.It
.Em Enter
.It
.Em Tab
.It
.Em Esc
.It
.Em F1..F12
.It
.Em M-char
.It
.Em C-char
.It
.Em char
.El
.Em char
is a single character string.
.sp
The headings before each list indicate the map key of the shortcut list.
For example for the first list titled
.Em general
the configuration is typed as follows:
.Bd -literal
[shortcuts.general]
next_tab = 'T'
.Ed
.sp
and for
.Em listing Ns
:
.Bd -literal
[shortcuts.listing]
open_entry = "Enter"
exit_entry = 'i'
.Ed
.sp
.Pp
.Em general
.Bl -tag -width 36n
.It Ic toggle_help
Toggle help and shortcuts view.
.\" default value
.Pq Em \&?
.It Ic quit
Quit meli.
.\" default value
.Pq Ql Em q
.It Ic enter_command_mode
Enter
.Em COMMAND
mode.
.\" default value
.Pq Ql Em \&:
.It Ic next_tab
Go to next tab.
.\" default value
.Pq Em T
.It Ic go_to_tab
Go to the
.Em n Ns
th tab
.Pq Em M-n
.It Ic scroll_right
Generic scroll right (catch-all setting)
.\" default value
.Pq Em Right
.It Ic scroll_left
Generic scroll left (catch-all setting)
.\" default value
.Pq Em Left
.It Ic scroll_up
Generic scroll up (catch-all setting)
.\" default value
.Pq Em k
.It Ic scroll_down
Generic scroll down (catch-all setting)
.\" default value
.Pq Em j
.It Ic next_page
Go to next page.
(catch-all setting)
.\" default value
.Pq Em PageDown
.It Ic prev_page
Go to previous page.
(catch-all setting)
.\" default value
.Pq Em PageUp
.It Ic home_page
Go to first page.
(catch-all setting)
.\" default value
.Pq Em Home
.It Ic end_page
Go to last page.
(catch-all setting)
.\" default value
.Pq Em End
.It Ic open_entry
Open list entry.
(catch-all setting)
.\" default value
.Pq Em Enter
.It Ic info_message_next
Show next info message, if any
.\" default value
.Pq Ql Em M->
.It Ic info_message_previous
Show previous info message, if any
.\" default value
.Pq Ql Em M-<
.El
.sp
.Em listing
.Bl -tag -width 36n
.It Ic scroll_up
Scroll up list.
.\" default value
.Pq Em k
.It Ic scroll_down
Scroll down list.
.\" default value
.Pq Em j
.It Ic next_page
Go to next page.
.\" default value
.Pq Em PageDown
.It Ic prev_page
Go to previous page.
.\" default value
.Pq Em PageUp
.It Ic new_mail
Start new mail draft in new tab.
.\" default value
.Pq Em m
.It Ic next_account
Go to next account.
.\" default value
.Pq Em h
.It Ic prev_account
Go to previous account.
.\" default value
.Pq Em l
.It Ic next_mailbox
Go to next mailbox.
.\" default value
.Pq Em J
.It Ic prev_mailbox
Go to previous mailbox.
.\" default value
.Pq Em K
.It Ic open_mailbox
Open selected mailbox
.\" default value
.Pq Em Enter
.It Ic toggle_mailbox_collapse
Toggle mailbox visibility in menu.
.\" default value
.Pq Em Space
.It Ic search
Search within list of e-mails.
.\" default value
.Pq Em /
.It Ic refresh
Manually request a mailbox refresh.
.\" default value
.Pq Em F5
.It Ic set_seen
Set thread as seen.
.\" default value
.Pq Em n
.It Ic union_modifier
Union modifier.
.\" default value
.Pq Em C-u
.It Ic diff_modifier
Difference modifier.
.\" default value
.Pq Em C-d
.It Ic intersection_modifier
Intersection modifier.
.\" default value
.Pq Em i
.It Ic select_entry
Select thread entry.
.\" default value
.Pq Em v
.It Ic increase_sidebar
Increase sidebar width.
.\" default value
.Pq Em C-p
.It Ic decrease_sidebar
Decrease sidebar width.
.\" default value
.Pq Em C-o
.It Ic toggle_menu_visibility
Toggle visibility of side menu in mail list.
.\" default value
.Pq Em `
.It Ic focus_left
Switch focus on the left.
.\" default value
.Pq Em Left
.It Ic focus_right
Switch focus on the right.
.\" default value
.Pq Em Right
.It Ic exit_entry
Exit e-mail entry.
.\" default value
.Pq Em i
.It Ic open_entry
Open e-mail entry.
.\" default value
.Pq Em Enter
.El
.sp
.Em pager
.Bl -tag -width 36n
.It Ic scroll_up
Scroll up pager.
.\" default value
.Pq Em k
.It Ic scroll_down
Scroll down pager.
.\" default value
.Pq Em j
.It Ic page_up
Go to previous pager page
.\" default value
.Pq Em PageUp
.It Ic page_down
Go to next pager pag
.\" default value
.Pq Em PageDown
.El
.sp
.Em contact-list
.Bl -tag -width 36n
.It Ic scroll_up
Scroll up list.
.\" default value
.Pq Em k
.It Ic scroll_down
Scroll down list.
.\" default value
.Pq Em j
.It Ic create_contact
Create new contact.
.\" default value
.Pq Em c
.It Ic edit_contact
Edit contact under cursor.
.\" default value
.Pq Em e
.It Ic mail_contact
Mail contact under cursor.
.\" default value
.Pq Em m
.It Ic next_account
Go to next account.
.\" default value
.Pq Em h
.It Ic prev_account
Go to previous account.
.\" default value
.Pq Em l
.It Ic toggle_menu_visibility
Toggle visibility of side menu in mail list.
.\" default value
.Pq Em `
.El
.sp
.sp
.Em composing
.Bl -tag -width 36n
.It Ic edit_mail
Edit mail.
.\" default value
.Pq Em e
.It Ic send_mail
Deliver draft to mailer
.\" default value
.Pq Em s
.It Ic scroll_up
Change field focus.
.\" default value
.Pq Em k
.It Ic scroll_down
Change field focus.
.\" default value
.Pq Em j
.El
.sp
.Em envelope-view
.Pp
To select an attachment, type its index (you will see the typed result in the command buffer on the bottom right of the status line), then issue the corresponding command.
.Bl -tag -width 36n
.It Ic add_addresses_to_contacts Ns
Select addresses from envelope to add to contacts.
.\" default value
.Pq Em c
.It Ic edit
Open envelope in composer.
.\" default value
.Pq Em e
.It Ic go_to_url
Go to url of given index (with the command
.Ic url_launcher
setting in
.Sx PAGER
section)
.\" default value
.Pq Em g
.It Ic open_attachment
Opens selected attachment with
.Cm xdg-open
.\" default value
.Pq Em a
.It Ic open_mailcap
Opens selected attachment according to its mailcap entry.
See
.Xr meli 1 FILES
for the mailcap file locations.
.\" default value
.Pq Em m
.It Ic reply
Reply to envelope.
.\" default value
.Pq Em R
.It Ic reply_to_author
Reply to author.
.\" default value
.Pq Em C-r
.It Ic reply_to_all
Reply to all/Reply to list/Follow up.
.\" default value
.Pq Em C-g
.It Ic forward
Forward email.
.\" default value
.Pq Em C-f
.It Ic return_to_normal_view
Return to envelope if viewing raw source or attachment.
.\" default value
.Pq Em r
.It Ic toggle_expand_headers
Expand extra headers (References and others)
.\" default value
.Pq Em h
.It Ic toggle_url_mode
Toggles url open mode.
When active, it prepends an index next to each url that you can select by typing the index and open by issuing
.Ic go_to_url
.\" default value
.Pq Em u
.It Ic view_raw_source
View raw envelope source in a pager.
.\" default value
.Pq Em M-r
.El
.sp
.Em thread-view
.Bl -tag -width 36n
.It Ic scroll_up
Scroll up list.
.\" default value
.Pq Em k
.It Ic scroll_down
Scroll down list.
.\" default value
.Pq Em j
.It Ic collapse_subtree
collapse thread branches
.\" default value
.Pq Em h
.It Ic next_page
Go to next page.
.\" default value
.Pq Em PageDown
.It Ic prev_page
Go to previous page.
.\" default value
.Pq Em PageUp
.It Ic reverse_thread_order
reverse thread order
.\" default value
.Pq Em C-r
.It Ic toggle_mailview
toggle mail view visibility
.\" default value
.Pq Em p
.It Ic toggle_threadview
toggle thread view visibility
.\" default value
.Pq Em t
.El
.sp
.Sh NOTIFICATIONS
.Bl -tag -width 36n
.It Ic enable Ar boolean
Enable notifications.
.\" default value
.Pq Em true
.It Ic script Ar String
.Pq Em optional
Script to pass notifications to, with title as 1st arg and body as 2nd
.\" default value
.Pq Em none
.It Ic new_mail_script Ar String
.Pq Em optional
A command to pipe new mail notifications through (preferred over
.Ic script Ns
), with title as 1st arg and body as 2nd.
.\" default value
.Pq Em none
.It Ic xbiff_file_path Ar String
.Pq Em optional
File that gets its size updated when new mail arrives.
.Pq Em none
.\" default value
.It Ic play_sound Ar boolean
.Pq Em optional
Play theme sound in notifications if possible.
.Pq Em false
.\" default value
.It Ic sound_file Ar String
.Pq Em optional
Play sound file in notifications if possible.
.\" default value
.Pq Em none
.El
.Sh PAGER
.Bl -tag -width 36n
.It Ic headers_sticky Ar boolean
.Pq Em optional
Always show headers when scrolling.
.\" default value
.Pq Em true
.It Ic html_filter Ar String
.Pq Em optional
Pipe html attachments through this filter before display
.\" default value
.Pq Em none
.It Ic html_open Ar String
.Pq Em optional
A command to open html files.
.\" default value
.Pq Em none
.It Ic filter Ar String
.Pq Em optional
A command to pipe mail output through for viewing in pager.
.\" default value
.Pq Em none
.It Ic format_flowed Ar bool
.Pq Em optional
Respect format=flowed
.\" default value
.Pq Em true
.It Ic split_long_lines Ar bool
.Pq Em optional
Split long lines that would overflow on the x axis.
.\" default value
.Pq Em true
.It Ic minimum_width Ar num
.Pq Em optional
Minimum text width in columns.
.\" default value
.Pq Em 80
.It Ic auto_choose_multipart_alternative Ar boolean
.Pq Em optional
Choose `text/html` alternative if `text/plain` is empty in `multipart/alternative` attachments.
.\" default value
.Pq Em true
.It Ic show_date_in_my_timezone Ar boolean
.Pq Em optional
Show Date: in local timezone
.\" default value
.Pq Em true
.It Ic url_launcher Ar String
.Pq Em optional
A command to launch URLs with.
The URL will be given as the first argument of the command.
.\" default value
.Pq Em xdg-open
.El
.Sh LISTING
.Bl -tag -width 36n
.It Ic show_menu_scrollbar Ar boolean
.Pq Em optional
 Show auto-hiding scrollbar in accounts sidebar menu.
.\" default value
.Pq Em true
.It Ic datetime_fmt Ar String
.Pq Em optional
Datetime formatting passed verbatim to strftime(3).
.\" default value
.Pq Em \&%Y-\&%m-\&%d \&%T
.It Ic recent_dates Ar Boolean
.Pq Em optional
Show recent dates as `X {minutes,hours,days} ago`, up to 7 days.
.\" default value
.Pq Em true
.It Ic filter Ar Query
.Pq Em optional
Show only envelopes matching this query.
.Po
For query syntax see
.Xr meli 1 QUERY ABNF SYNTAX
.Pc
.\" default value
.Pq Em None
.Pp
Example:
.Bd -literal
filter = "not flags:seen" # show only unseen messages
.Ed
.It Ic index_style Ar String
Sets the way mailboxes are displayed.
.It Ic sidebar_mailbox_tree_has_sibling Ar String
.Pq Em optional
Sets the string to print in the mailbox tree for a level where its root has a sibling.
See example below for a clear explanation and examples.
.It Ic sidebar_mailbox_tree_no_sibling Ar String
.Pq Em optional
Sets the string to print in the mailbox tree for a level where its root has no sibling.
.It Ic sidebar_mailbox_tree_has_sibling_leaf Ar String
.Pq Em optional
Sets the string to print in the mailbox tree for a leaf level where its root has a sibling.
.It Ic sidebar_mailbox_tree_no_sibling_leaf Ar String
.Pq Em optional
Sets the string to print in the mailbox tree for a leaf level where its root has no sibling.
.It Ic sidebar_divider Ar char
.Pq Em optional
Sets the character to print as the divider between the accounts list and the message list.
.It Ic sidebar_ratio Ar Integer
.Pq Em optional
This is the width of the right container to the entire screen width.
.\" default value
.Pq Em 90
.It Ic unseen_flag Ar Option<String>
Flag to show if thread entry contains unseen mail.
.\" default value
.Pq Em "●"
.It Ic thread_snoozed_flag Ar Option<String>
Flag to show if thread has been snoozed.
.\" default value
.Pq Em "💤"
.It Ic selected_flag Ar Option<String>
Flag to show if thread entry has been selected.
.\" default value
.Pq Em "☑️"
.It Ic attachment_flag Ar Option<String>
Flag to show if thread entry contains attachments.
.\" default value
.Pq Em "📎"
.It Ic thread_subject_pack Ar bool
Should threads with differentiating Subjects show a list of those subjects on the entry title?
.\" default value
.Pq Em "true"
.El
.Ss Examples of sidebar mailbox tree customization
The default values
.sp
.Bd -literal
 has_sibling = " "
 no_sibling = " ";
 has_sibling_leaf = " "
 no_sibling_leaf = " "
.Ed
.sp
render a mailbox tree like the following:
.sp
.Bd -literal
0  Inbox 3
1   Archive
2   Drafts
3   Lists
4    example-list-a
5    example-list-b
6   Sent
7   Spam
8   Trash
.Ed
.sp
Other possible trees:
.sp
.Bd -literal
has_sibling = " ┃"
no_sibling = "  "
has_sibling_leaf = " ┣━"
no_sibling_leaf = " ┗━"
.Ed
.sp
.Bd -literal
0  Inbox 3
1   ┣━Archive
2   ┣━Drafts
3   ┣━Lists
4   ┃ ┣━example-list-a
5   ┃ ┗━example-list-b
6   ┣━Sent
7   ┣━Spam
8   ┗━Trash
.Ed
.sp
A completely ASCII one:
.sp
.Bd -literal
has_sibling = " |"
no_sibling = "  "
has_sibling_leaf = " |\\_"
no_sibling_leaf = " \\_"
.Ed
.sp
.Bd -literal
0  Inbox 3
1   |\\_Archive
2   |\\_Drafts
3   |\\_Lists
4   | |\\_example-list-a
5   |  \\_example-list-b
6   |\\_Sent
7   |\\_Spam
8    \\_Trash
.Ed
.sp
.Sh TAGS
.Bl -tag -width 36n
.It Ic colours Ar hash table String[Color]
.Pq Em optional
Set UI colors for tags
.It Ic ignore_tags Ar Array String
.Pq Em optional
Hide tags (not the tagged messages themselves)
.El
.sp
Example:
.sp
.Bd -literal
[tags]
# valid inputs: #HHHHHH, #ABC -> #AABBCC, XTERM_NAME, 0-255 byte
colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
[accounts.dummy]
\&...
  [accounts.dummy.mailboxes]
  # per mailbox override:
  "INBOX" = {  tags.ignore_tags=["inbox", ] }
.Ed
.Sh PGP
.Bl -tag -width 36n
.It Ic auto_verify_signatures Ar boolean
Auto verify signed e-mail according to RFC3156
.\" default value
.Pq Em true
.It Ic auto_sign Ar boolean
.Pq Em optional
Always sign sent messages
.\" default value
.Pq Em false
.It Ic key Ar String
.Pq Em optional
Key to be used when signing/encrypting (not functional yet)
.\" default value
.Pq Em none
.El
.Sh TERMINAL
.Bl -tag -width 36n
.It Ic theme Ar String
.Pq Em optional
Theme name to use.
.\" default value
.Pq Em dark
.It Ic ascii_drawing Ar boolean
.Pq Em optional
If true, box drawing will be done with ascii characters.
.\" default value
.Pq Em false
.It Ic use_color Ar boolean
.Pq Em optional
If false, no ANSI colors are used.
.\" default value
.Pq Em true
.It Ic window_title Ar String
.Pq Em optional
Set window title in xterm compatible terminals An empty string means no window title is set.
.\" default value
.Pq Em "meli"
.It Ic file_picker_command Ar String
.Pq Em optional
Set command that prints file paths in stderr, separated by NULL bytes.
Used with
.Ic add-attachment-file-picker
when composing new mail.
.\" default value
.Pq Em None
.It Ic themes Ar hash table String[String[Attribute]]
Define UI themes.
See
.Xr meli-themes 5
for details.
.Bd -literal
[terminal]
theme = "themeB"

[terminal.themes.themeA]
"mail.view.body" = {fg = "HotPink3", bg = "LightSalmon1"}
\&...
[terminal.themes.themeB]
"mail.view.body" = {fg = "CadetBlue", bg = "White"}
\&...
[terminal.themes.themeC]
\&...
.Ed
.It Ic use_mouse Ar bool
Use mouse events.
This will disable text selection, but you will be able to resize some widgets.
This setting can be toggled with
.Cm toggle mouse Ns
\&.
.\" default value
.Pq Em false
.It Ic mouse_flag Ar String
String to show in status bar if mouse is active.
.\" default value
.Pq Em 🖱️
.It Ic progress_spinner_sequence Ar Either \&< Integer, ProgressSpinner \&>
Choose between 37 built in sequences (integers between 0-36) or define your own list of strings for the progress spinner animation.
Set to an empty array to disable the progress spinner.
.\" default value
.Pq Em 20
.Pp
Builtin sequences are:
.Bd -literal
0   ["-", "\\", "|", "/"]
1   ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"]
2   ["⣀", "⣄", "⣤", "⣦", "⣶", "⣷", "⣿"]
3   ["⣀", "⣄", "⣆", "⣇", "⣧", "⣷", "⣿"]
4   ["○", "◔", "◐", "◕", "⬤"]
5   ["□", "◱", "◧", "▣", "■"]
6   ["□", "◱", "▨", "▩", "■"]
7   ["□", "◱", "▥", "▦", "■"]
8   ["░", "▒", "▓", "█"]
9   ["░", "█"]
10  ["⬜", "⬛"]
11  ["▱", "▰"]
12  ["▭", "◼"]
13  ["▯", "▮"]
14  ["◯", "⬤"]
15  ["⚪", "⚫"]
16  ["▖", "▗", "▘", "▝", "▞", "▚", "▙", "▟", "▜", "▛"]
17  ["|", "/", "-", "\\"]
18  [".", "o", "O", "@", "*"]
19  ["◡◡", "⊙⊙", "◠◠", "⊙⊙"]
20  ["◜ ", " ◝", " ◞", "◟ "]
21  ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"]
22  ["▁", "▃", "▄", "▅", "▆", "▇", "█", "▇", "▆", "▅", "▄", "▃"]
23  [ "▉", "▊", "▋", "▌", "▍", "▎", "▏", "▎", "▍", "▌", "▋", "▊", "▉" ]
24  ["▖", "▘", "▝", "▗"]
25  ["▌", "▀", "▐", "▄"]
26  ["┤", "┘", "┴", "└", "├", "┌", "┬", "┐"]
27  ["◢", "◣", "◤", "◥"]
28  ["⠁", "⠂", "⠄", "⡀", "⢀", "⠠", "⠐", "⠈"]
29  ["⢎⡰", "⢎⡡", "⢎⡑", "⢎⠱", "⠎⡱", "⢊⡱", "⢌⡱", "⢆⡱"]
30  [".", "o", "O", "°", "O", "o", "."]
31  ["㊂", "㊀", "㊁"]
32  ["💛 ", "💙 ", "💜 ", "💚 ", "❤️ "]
33  [ "🕛 ", "🕐 ", "🕑 ", "🕒 ", "🕓 ", "🕔 ", "🕕 ", "🕖 ", "🕗 ", "🕘 ", "🕙 ", "🕚 " ]
34  ["🌍 ", "🌎 ", "🌏 "]
35  [ "[    ]", "[=   ]", "[==  ]", "[=== ]", "[ ===]", "[  ==]", "[   =]", "[    ]", "[   =]", "[  ==]", "[ ===]", "[====]", "[=== ]", "[==  ]", "[=   ]" ]
36  ["🌑 ", "🌒 ", "🌓 ", "🌔 ", "🌕 ", "🌖 ", "🌗 ", "🌘 "]
.Ed
.Pp
Or, define an array of strings each consisting of a frame in the progress sequence indicator for a custom spinner:
.Bl -tag -width 36n
.It Ic interval_ms Ar u64
.Pq Em optional
Frame interval.
.\" default value
.Pq 50
.It Ic frames Ar [String]
The animation frames.
.El
.Pp
Example:
.Bd -literal
progress_spinner_sequence = { interval_ms = 150, frames = [ "-", "=", "≡" ] }
.Ed
.El
.Sh LOG
.Bl -tag -width 36n
.It Ic log_file Ar String
.Pq Em optional
path of the log file
.\" default value
.Pq Pa $XDG_DATA_HOME/meli/meli.log
.It Ic maximum_level Ar String
.Pq Em optional
maximum level of messages to log.
All levels less or equal to the
.Ic maximum_level
will be appended to the log file.
Available levels are, in partial order:
.Bl -bullet -compact
.It
.Em OFF
.It
.Em FATAL
.It
.Em ERROR
.It
.Em WARN
.It
.Em INFO
.It
.Em DEBUG
.It
.Em TRACE
.El
This means that to turn logging off, set
.Ic maximum_level
to
.Em OFF Ns
\&.
.\" default value
.Pq Em INFO
.El
.Sh SMTP Connections
.Bl -tag -width 36n
.It Ic hostname Ar String
server hostname
.It Ic port Ar Integer
server port
.It Ic envelope_from Ar String
.Pq Em optional
address to set as sender in SMTP transactions
.\" default value
.Pq Em none
.It Ic auth Ar SmtpAuth
SMTP server authentication.
See
.Sx SmtpAuth
subsection.
.It Ic security Ar SmtpSecurity
.Pq Em optional
gpg binary name or file location to use
.\" default value
.Po see
.Sx SmtpSecurity
subsection
.Pc
.It Ic extensions Ar SmtpExtensions
.Pq Em optional
set support for SMTP extensions if they are advertised by the server
.\" default value
.Po see
.Sx SmtpExtensions
subsection
.Pc
.El
.Ss SmtpAuth
.Bl -tag -width 36n
.It Ic type Ar "none" | "auto" | "xoauth2"
.El
.Pp
For type "auto":
.Bl -tag -width 36n
.It Ic username Ar String
.It Ic password Ar SmtpPassword
.It Ic require_auth Ar bool
.Pq Em optional
require authentication in every case
.\" default value
.Pq Em true
.El
.sp
For type "xoauth2":
.Bl -tag -width 36n
.It Ic token_command Ar String
Command to evaluate that returns an XOAUTH2 token.
.It Ic require_auth Ar bool
.Pq Em optional
require authentication in every case
.\" default value
.Pq Em true
.El
.sp
Examples:
.Bd -literal
auth = { type = "auto", username = "user", password = { type = "raw", value = "hunter2" } }
.Ed
.Bd -literal
auth = { type = "auto", username = "user", password = "hunter2" }
.Ed
.Bd -literal
auth = { type = "none" }
.Ed
.sp
For Gmail (see
.Sx Gmail OAUTH2
for details on the authentication token command):
.Bd -literal
auth = { type = "xoauth2", token_command = "TOKEN=$(python3 oauth2.py --user=xxx@gmail.com --quiet --client_id=1038[...].apps.googleusercontent.com --client_secret=[..] --refresh_token=[..] && python3 oauth2.py --user=xxx@gmail.com --generate_oauth2_string --quiet --access_token=$TOKEN" }
.Ed
.Ss SmtpPassword
.Bl -tag -width 36n
.It Ic type Ar "raw" | "command_evaluation"
.It Ic value Ar String
Either a raw password string, or command to execute.
.El
.sp
Examples:
.Bd -literal
password = { type = "raw", value = "hunter2" }
.Ed
.Bd -literal
password = { type = "command_eval", value = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" }
.Ed
.Ss SmtpSecurity
Default security type is
.Em auto Ns
\&.
.Bl -tag -width 36n
.It Ic type Ar "none" | "auto" | "starttls" | "tls"
.It Ic danger_accept_invalid_certs Ar bool
Accept invalid SSL/TLS certificates
.\" default value
.Pq Em false
.El
.Ss SmtpExtensions
.Bl -tag -width 36n
.It Ic pipelining Ar bool
rfc2920
.\" default value
.Pq Em true
.It Ic chunking Ar bool
rfc3030
.\" default value
.Pq Em true
.It Ic prdr Ar bool
draft-hall-prdr-00
.\" default value
.Pq Em true
.It Ic dsn_notify Ar String
RFC3461
.\" default value
.Pq Em FAILURE
.El
.Sh SEE ALSO
.Xr meli 1 ,
.Xr meli-themes 5
.Sh CONFORMING TO
TOML Standard v.0.5.0 https://toml.io/en/v0.5.0
.Sh AUTHORS
Copyright 2017-2019
.An Manos Pitsidianakis Aq epilys@nessuent.xyz
Released under the GPL, version 3 or greater.
This software carries no warranty of any kind.
(See COPYING for full copyright and warranty notices.)
.Pp
.Aq https://meli.delivery