| MELI.CONF(5) | File Formats Manual | MELI.CONF(5) |
NAME¶
meli.conf —
configuration file for the meli(1)
terminal e-mail client
SYNOPSIS¶
$XDG_CONFIG_HOME/meli/config.toml
DESCRIPTION¶
Configuration for meli is written in TOML which has a few things to consider (quoting the specification):
- TOML is case sensitive.
- A TOML file must be a valid UTF-8 encoded Unicode document.
- White-space means
tab
(
0x09) or space (0x20). - Newline means
LF
(
0x0A) or CRLF (0x0D 0x0A).
Refer to TOML documentation for valid TOML syntax.
Though not part of TOML syntax,
meli.conf can have nested configuration files by
using the following m4(1) include macro:
include("/path/to/file")SECTIONS¶
The top level sections of the configuration are:
- accounts
- shortcuts
- notifications
- pager
- listing
- composing
- pgp
- terminal
- log
EXAMPLES¶
An example configuration:
# 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"
send_mail = 'msmtp --read-recipients --read-envelope-from'
#send_mail = { hostname = "smtp.example.com", port = 587, auth = { type = "auto", username = "user", password = { command = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" } }, security = { type = "STARTTLS" } }
# 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"
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 -o display_link_number=1"
[notifications]
script = "notify-send"
[composing]
editor_command = 'vim +/^$'
[shortcuts]
[shortcuts.composing]
edit = 'e'
[shortcuts.listing]
new_mail = 'm'
set_seen = 'n'
[terminal]
theme = "light"
Available options are listed below.
ACCOUNTS¶
Account configuration settings¶
Default values are shown in parentheses.
root_mailboxString- The backend-specific path of the root_mailbox, usually INBOX.
send_mailString|SmtpServerConf- Command to pipe new mail to (exit code must be
0for success) or settings for an SMTP server connection. See section SMTP Connections for its fields. default_mailboxString- (optional) The mailbox that is the default to open or view for this account. Must be a valid mailbox path. If not specified, the default will be the root mailbox.
formatString [maildir mbox imap notmuch jmap]- The format of the mail backend.
subscribed_mailboxes[String,]- An array of mailbox paths to display in the UI. Paths are relative to the root mailbox (e.g. INBOX/Sent, not Sent). The glob wildcard * can be used to match every mailbox name and path.
identityString- Your e-mail address that is inserted in the
From: headers of outgoing mail. extra_identities[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.
display_nameString- (optional) A name which can be combined with your
address: "
Name <email@example.com>". read_onlyboolean- Attempt to not make any changes to this account. (false)
manual_refreshboolean- (optional) If true, do not monitor account for changes
(you can use shortcut
listing.refresh). (false) refresh_commandString- (optional) command to execute when manually refreshing
(shortcut
listing.refresh) (None) search_backendString- (optional) Choose which search backend to use. Available
options are "
none" and "sqlite3". ("sqlite3") contactsMap[String, ContactBackendConf]- (optional) A map of named contact backends for this
account. The key string value is an arbitrary name you set for your own
reference. The value type of
ContactBackendConfis a map with two keys: Wheretypeis one of:NotmuchAddress- and
valueis a string query passed to "notmuch address" to import contacts into meli. Contacts are parsed and imported read-only. This can be used with any backend, not just notmuch, since it only relies on the existence of the notmuch(1) binary.Example:
This will run the commandcontacts = { "notmuch" = { type = "NotmuchAddress", value = "date:1Y.. AND from:you@example.com" } }and parse its json output.notmuch address --format=json --output=recipients date:1Y.. AND from:you@example.com
MuttAlias- and
valueis a string of a path of mutt(1) compatible alias file in the option They are parsed and imported read-only. Example:contacts = { "mutt" = { type = "MuttAlias", value = "~/.mutt/aliases" } } VCard- and
valueis a string of a folder path that contains .vcf files. They are parsed and imported read-only. Example:contacts = { "vcards" = { type = "VCard", value = "~/.contacts/" } } CardDAV- and
valueis a map including the CardDAV server configuration.urlString- Server url.
usernameSecret- Authentication username.
passwordSecret- Authentication password.
auth"Basic" | "BearerToken" | "None"- Type of HTTP authentication.
contacts = { "my_carddav" = { type = "CardDAV", value = { url = "https://carddav.example.com", username = "user@example.com", password = "hunter2", auth = "Basic" } } }
mailboxesmailbox- (optional) Configuration for each mailbox. Its format is described below in mailboxes.
- conf_override
- (optional) Override global settings for this account.
The settings are nested, optional versions of global settings. Available
sections to override are pager, listing, notifications,
shortcuts, composing, identity, tags, themes, pgp and the account
options identity, send_mail. Example:
[accounts."imap.example.com"] pager = { filter = "pygmentize -l diff -f 256"} }
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.
notmuch mailboxes are virtual, since they are defined by
user-given notmuch queries. You must explicitly state the mailboxes you want
in the mailboxes field and set the
query property to each of them. To create a tree
hierarchy with virtual mailboxes, define the parent
property to a mailbox as the name of the parent mailbox you have used in
your configuration.
Account properties:
root_mailbox- points to the directory which contains the .notmuch/ subdirectory.
library_file_pathPath- Use an arbitrary location of libnotmuch by specifying its full filesystem path. (optional)
queryString- The notmuch query that defines what content this virtual mailbox has. Refer to notmuch-search-terms(7) for notmuch's search syntax.
parentString- If you wish to build a mailbox hierarchy, define the name of a parent mailbox you have used in your configuration. (optional)
save_toSaveTo- If you wish to be able to save e-mails to your filesystem by copying to a
mailbox or when sending a copy of sent e-mails to your Sent folder, you
can specify a path that will be used to store a Maildir file copy and
optionally tags to add. The path must point to a valid Maildir directory,
and not to one of its
cur,new,tmpsubdirectories. TheSaveTotype is a map with the following keys:pathPath Directory path. The path must point to a valid Maildir directory.
Example:
[accounts.notmuch]
format = "notmuch"
#library_file_path = "/opt/homebrew/lib/libnotmuch.5.dylib"
...
[accounts.notmuch.mailboxes]
"INBOX" = { query="tag:inbox", subscribe = true, usage = "Inbox", save_to = { path = "/path/to/INBOX", add_tags = ["inbox"] } }
"Drafts" = { query="tag:draft", usage = "Drafts", save_to = { path = "/path/to/Drafts", add_tags = ["draft"] }, subscribe = true }
"Sent" = { query="from:username@example.com from:username2@example.com", usage = "Sent", save_to = { path = "/path/to/Sent", add_tags = ["sent"] }, subscribe = true }
"Archives" = { query="tag:archived", subscribe = true }
"Archives/2019" = { query="tag:archived date:01-2019..12-2019", parent="Archives", subscribe = true }
IMAP only¶
IMAP specific options are:
server_hostnameSecret- example: "mail.example.com"
server_usernameSecret- Server username
server_passwordSecret- Server password
server_port16-bit number- (optional) The port to connect to (143)
use_starttlsboolean- (optional) If port is
993and "use_starttls" is unspecified, it becomes false by default. (true) use_tlsboolean- (optional) Connect with TLS (or upgrade from plain connection to TLS if STARTTLS is set.) (true)
danger_accept_invalid_certsboolean- (optional) Do not validate TLS certificates. (false)
offline_cacheboolean- (optional) Keep mail headers in an sqlite3 database. (true)
use_idleboolean- (optional) Use IDLE extension. (true)
use_condstoreboolean- (optional) Use CONDSTORE extension. (true)
use_deflateboolean- (optional) Use COMPRESS=DEFLATE extension (if built with DEFLATE support) (true)
use_oauth2boolean- (optional) Use OAUTH2 authentication.
Can be used with
server_passwordthat returns a base64-encoded OAUTH2 token ready to be passed to IMAP. For help on setup with Gmail, see Gmail section below. (false) use_auth_anonymousboolean- (optional) Use AUTH=ANONYMOUS extension for authentication. (false)
use_idboolean- (optional) Use ID extension to retrieve server metadata, viewable at the account status page. Enabling this does not send any information to the server. (false)
use_connection_poolboolean- (optional) Use a connection pool of more than one server connections, to prevent time-outs when performing multiple operations. IMAP connections are stateful and can only operate on one mailbox at a time, thus using a connection requires locking. Having a pool of alternative connections created on demand in case they can be made available faster than the main connection can be unlocked might alleviate lock contention. (true)
timeoutinteger- (optional) Timeout to use for server connections in
seconds. A timeout of
0seconds means there is no timeout. (16)
Gmail¶
Gmail has non-standard IMAP behaviors that need to be worked around.
Gmail - sending mail¶
Option store_sent_mail should be disabled
since Gmail auto-saves sent mail by its own.
Gmail OAUTH2¶
To use OAUTH2, you must go through a process to
register your own private "application" with
Google that can use OAUTH2 tokens, and
set the option use_oauth2 as
‘true’ in the account configuration
section. For convenience in the meli repository under the
contrib/ directory you can find a
python3
file named oauth2.py to generate and request the
appropriate data to perform OAUTH2 authentication.
Steps:
- 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.
- Run the
oauth2.pyscript as follows (after adjusting binary paths and credentials):python3 oauth2.py --user=xxx@gmail.com --client_id=1038[...].apps.googleusercontent.com --client_secret=VWFn8LIKAMC-MsjBMhJeOplZ --generate_oauth2_tokenand follow the instructions. Note down the refresh token. - In
server_passwordenter a command like this (after adjusting binary paths and credentials):python3 oauth2.py --user=xxx@gmail.com --quiet --client_id=1038[...].apps.googleusercontent.com --client_secret=VWFn8LIKAMC-MsjBMhJeOplZ --refresh_token=1/Yzm6MRy4q1xi7Dx2DuWXNgT6s37OrP_DW_IoyTum4YA - On startup, meli should evaluate this
command which if successful must only return a
base64-encoded
token ready to be passed to
IMAP.
Your account section should look like this:
[accounts."gmail"] root_mailbox = '[Gmail]' format = "imap" server_hostname='imap.gmail.com' server_username="username@gmail.com" use_oauth2 = true server_password = { command = "python3 oauth2.py ..." } server_port="993" listing.index_style = "Conversations" identity = "username@gmail.com" display_name = "Name Name" subscribed_mailboxes = ["*" ] send_mail = { hostname = "smtp.gmail.com", port = 587, auth = { type = "xoauth2", token = { command = "..." }, require_auth = true }, security = { type = "STARTTLS" } } composing.store_sent_mail = false
JMAP only¶
JMAP specific options
server_urlSecret- example: "http://mail.example.com" "http://mail.example.com:8080" "https://mail.example.com"
server_usernameSecret- Server username
server_passwordSecret- Server password
use_tokenboolean- Authenticate using the API Bearer token method. If enabled, the token value must be provided as the configured password. (false)
danger_accept_invalid_certsboolean- (optional) Do not validate TLS certificates. (false)
timeoutinteger- (optional) Timeout to use for server connections in
seconds. A timeout of
0seconds means there is no timeout. (16)
mbox only¶
mbox specific options:
prefer_mbox_typeString- (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 is a recover attempt, which discards the invalid message.Valid values
- auto
- mboxo
- mboxrd
- mboxcl
- mboxcl2
mailboxes field and set the
path property to each of them. Example:
[accounts.mbox]
format = "mbox"
mailboxes."Python mailing list" = { path = "~/.mail/python.mbox", subscribe = true, autoload = true }
NNTP¶
NNTP specific options
server_hostnameSecret- example: "nntp.example.com"
server_usernameSecret- Server username
server_passwordSecret- Server password
require_authboolean- (optional) require authentication in every case (true)
use_tlsboolean- (optional) Connect with TLS. (false)
server_portnumber- (optional) The port to connect to (119)
danger_accept_invalid_certsboolean- (optional) Do not validate TLS certificates. (false)
store_flags_locallyboolean- (optional) Store seen status locally in an sqlite3 database. (true)
timeoutinteger- (optional) Timeout to use for server connections in
seconds. A timeout of
0seconds means there is no timeout. (16)
You have to explicitly state the groups you want to see in the
mailboxes field. Example:
[accounts.sicpm.mailboxes]
"sic.all" = {}
To submit articles directly to the
NNTP server, you must set the special value
server_submission
in the account send_mail field. Example:
send_mail = "server_submission"
MAILBOXES¶
aliasString- (optional) Show a different name for this mailbox in the UI.
autoloadboolean- (optional) Load this mailbox on startup (true)
collapsedboolean- (optional) Collapse this mailbox subtree in menu. (false)
subscribeboolean- (optional) Watch this mailbox for updates. (true)
ignoreboolean- (optional) Silently insert updates for this mailbox, if any. (false)
usageboolean- (optional) special usage of this mailbox. Valid values
are:
- Normal (default)
- Inbox
- Archive
- Drafts
- Flagged
- Junk
- Sent
- Trash
Sent", you must explicitly set it. sort_orderunsigned integer- (optional) Override sort order on the sidebar for this
mailbox. Example:
[accounts."imap.example.com".mailboxes] "INBOX" = { index_style = "plain" } "INBOX/Sent" = { sort_order = 0 } "INBOX/Drafts" = { sort_order = 1 } "INBOX/Lists" = { sort_order = 2 } encodingString- (optional) Override the default UTF-8 charset for the mailbox name. Useful only for UTF-7 mailboxes. (utf7, utf-7, utf8, utf-8)
- conf_override
- (optional) Override global settings for this mailbox.
The settings are nested, optional versions of global settings. Available
sections to override are pager, listing, notifications,
shortcuts, composing, identity, tags, themes, pgp and the account
options identity, send_mail. Example:
[accounts."imap.example.com".mailboxes] "INBOX" = { index_style = "plain" } "INBOX/Lists/devlist" = { autoload = false, pager = { filter = "pygmentize -l diff -f 256"} }
COMPOSING¶
Composing specific configuration settings¶
Default values are shown in parentheses.
editor_commandString- Command to launch editor. Can have arguments. Draft filename is given as
the last argument. If it's missing, the environment variable
EDITORis looked up. embedded_ptyboolean- (optional) Embedded editor within meli. Editor must be xterm compliant. (false)
format_flowedboolean- (optional) Set
format=flowed[RFC3676] intext/plainattachments. (true) insert_user_agentboolean- (optional) Add meli
User-Agentheader in new drafts. (true) default_header_valueshash table String[String]- (optional) Default header values used when creating a new draft. ({})
wrap_header_preambleOption<(String, String)>- (optional) Wrap header pre-ample 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 ["<!--", "-->"] which wraps the headers in an HTML comment. (None)
store_sent_mailboolean- (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. (true)
attribution_format_stringString- (optional) The attribution line appears above the quoted
reply text. The format specifiers for the replied address are:
%+f— the sender's name and email address.%+n— the sender's name (or email address, if no name is included).%+a— the sender's email address.
attribution_use_posix_localeboolean- (optional) Whether the strftime(3) call for the attribution string uses the POSIX locale instead of the user's active locale. (true)
forward_as_attachmentboolean or ask- (optional) Forward emails as attachment? (Alternative is inline). (ask)
reply_prefix_list_to_strip[String]- (optional) Alternative lists of reply prefixes (etc. ["Re:", "RE:", ...]) to strip.
reply_prefixString- (optional) The prefix to use in reply subjects. The
default prefix is ‘
Re:’. (‘Re:’)RFC 2822, "Internet Message Format" has this to say on the matter:
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.
custom_compose_hooks[{ name = String, command = String }]- (optional) Custom compose-hooks that run shell scripts.
compose-hooks run before submitting an e-mail. They perform draft
validation and/or transformations. If a custom hook exits with an error
status or prints output to stdout and stderr, it will show up in the UI as
a notification.
Example:
[composing] editor_cmd = '~/.local/bin/vim +/^$' embedded_pty = true custom_compose_hooks = [ { name ="spellcheck", command="aspell --mode email --dont-suggest --ignore-case list" }] disabled_compose_hooks[String]- (optional) Disabled compose-hooks. compose-hooks run
before submitting an e-mail. They perform draft validation and/or
transformations. If a hook encounters an error or warning, it will show up
as a notification. The currently available hooks are:
past-date-warn— Warn ifDateheader value is far in the past or future.important-header-warn— Warn if important headers (From,Date,To,Cc,Bcc) are missing or invalid.missing-attachment-warn— Warn ifSubjector draft body mention attachments but they are missing.empty-draft-warn— Warn if draft has no subject and no body.
signature_filePath | Secret- (optional) Path to plain text file with signature that
will pre-populate an email draft, or a command that must print a signature
to standard output with a timeout of 300 milliseconds.
File example:
[composing] signature_file = "/home/user/.signature"
Command example:
[composing] signature_file = { command = "fortune" }Signatures must be explicitly enabled to be used, otherwise this setting will be ignored. (None)
use_signaturebool- Pre-populate email drafts with signature, if any. meli
will lookup the signature value in this order:
- The
signature_filesetting. - ${XDG_CONFIG_DIR}/meli/<account>/signature
- ${XDG_CONFIG_DIR}/meli/signature
- ${XDG_CONFIG_DIR}/signature
- ${HOME}/.signature
- No signature otherwise.
- The
signature_delimiterString- (optional) Signature delimiter, that is, text that will
be prefixed to your signature to separate it from the email body.
(‘
\n\n-- \n’) allow_reply_to_selfboolean- (optional) When replying to an e-mail authored by our main identity or one of our extra identities, reply to those addresses instead of reusing the receivers of the original e-mail we are replying to. The default is false, because the intuitive behavior when replying to ourselves is to follow-up on an e-mail we sent. (false)
SHORTCUTS¶
Values corresponding to keyboard keys, keycodes¶
Shortcuts can take the following values:
- Backspace
- Left
- Right
- Up
- Down
- Home
- End
- PageUp
- PageDown
- Delete
- Insert
- Enter
- Tab
- Esc
- F1..F12
- M-char
- C-char
- char
Where char is a single character string, maximum 4 bytes long, like the corresponding type in Rust.
In the next subsection, you will find lists for each shortcut category. The headings before each list indicate the map key of the shortcut list. For example for the first list titled general the configuration is typed as follows:
[shortcuts.general] next_tab = 'T'
and for listing:
[shortcuts.listing] open_entry = "Enter" exit_entry = 'i'
In addition, each shortcuts section supports a TOML array of commands to associate a key to an array of COMMAND mode commands.
[shortcuts.listing]
commands = [ { command = [ "tag remove trash", "flag unset trash" ], shortcut = "D" },
{ command = [ "tag add trash", "flag set trash" ], shortcut = "d" } ]
Shortcut configuration settings¶
Default values are shown in parentheses.
general
toggle_help- Toggle help and shortcuts view. (?)
enter_command_mode- Enter COMMAND mode. (:)
open_terminal- Opens
$SHELLin current directory. (C-t) quit- Quit meli. (q)
go_to_tab- Go to the nth tab (M-n)
next_tab- Go to the next tab. (T)
scroll_right- Generic scroll right (catch-all setting) (l)
scroll_left- Generic scroll left (catch-all setting) (h)
scroll_up- Generic scroll up (catch-all setting) (k)
scroll_down- Generic scroll down (catch-all setting) (j)
next_page- Go to next page. (catch-all setting) (PageDown)
prev_page- Go to previous page. (catch-all setting) (PageUp)
home_page- Go to first page. (catch-all setting) (Home)
end_page- Go to last page. (catch-all setting) (End)
open_entry- Open list entry. (catch-all setting) (Enter)
info_message_next- Show next info message, if any. (>)
info_message_previous- Show previous info message, if any. (<)
focus_in_text_field- Focus on a text field. (Enter)
search- Search within pager. (/)
next_search_result- Scroll to next search result. (n)
previous_search_result- Scroll to previous search result. (N)
listing
scroll_up- Scroll up list. (k)
scroll_down- Scroll down list. (j)
next_page- Go to next page. (PageDown)
prev_page- Go to previous page. (PageUp)
new_mail- Start new mail draft in new tab. (m)
next_account- Go to next account. (H)
prev_account- Go to previous account. (L)
next_mailbox- Go to next mailbox. (J)
prev_mailbox- Go to previous mailbox. (K)
open_mailbox- Open selected mailbox (Enter)
toggle_mailbox_collapse- Toggle mailbox visibility in menu. (Space)
search- Search within list of e-mails. (/)
refresh- Manually request a mailbox refresh. (F5)
set_seen- Set thread as seen. (n)
send_to_trash- Send entry to trash folder. (D)
union_modifier- Union modifier. (C-u)
diff_modifier- Difference modifier. (C-d)
intersection_modifier- Intersection modifier. (i)
select_entry- Select (or toggle) thread entry. (V)
select_motion- Perform select motion with a movement. (v)
- Increase sidebar width. (C-f)
- Decrease sidebar width. (C-d)
next_entry- When reading a mail item, change focus on next entry according to the current sorting. (C-n)
previous_entry- When reading a mail item, change focus on previous entry according to the current sorting. (C-p)
- Toggle visibility of side menu in mail list. (`)
focus_left- Switch focus on the left. (Left)
focus_right- Switch focus on the right. (Right)
exit_entry- Exit e-mail entry. (i)
open_entry- Open e-mail entry. (Enter)
page_down- Go to next page. (PageDown)
page_up- Go to previous page. (PageUp)
scroll_down- Scroll down pager. (j)
scroll_up- Scroll up pager. (k)
select_filter- Select content filter.
(f)
See also
named_filterssetting.
contact-list Scrolling and navigation shortcuts from listing also apply.
create_contact- Create new contact. (c)
edit_contact- Edit contact under cursor. (e)
export_contact- Export contact under cursor to .vcf. (E)
import_contact- Import contact from .vcf file. (I)
delete_contact- Delete contact under cursor. (d)
mail_contact- Mail contact under cursor. (m)
edit- Edit mail. (e)
send_mail- Deliver draft to mailer (s)
scroll_up- Change field focus. (k)
scroll_down- Change field focus. (j)
reset_date- Reset date to current time. (F1)
reset_body- Reset body to default template. (F2)
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.
add_addresses_to_contacts- Select addresses from envelope to add to contacts. (c)
edit- Open envelope in composer. (e)
go_to_url- Go to url of given index (with the command
url_launchersetting in PAGER section) (g) open_attachment- Opens selected attachment with xdg-open(1) or, in MacOS, open(1) (a)
open_mailcap- Opens selected attachment according to its mailcap entry. See meli(1) FILES for the mailcap file locations. (m)
open_html- Opens html attachment in the default browser. (v)
reply- Reply to envelope. (R)
- Reply to author. (C-r)
reply_to_all- Reply to all/Reply to list/Follow up. (C-g)
forward- Forward email. (C-f)
return_to_normal_view- Return to envelope if viewing raw source or attachment. (r)
toggle_expand_headers- Expand extra headers (References and others) (h)
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
go_to_url(u) view_raw_source- View raw envelope source in a pager. (M-r)
change_charset- Force attachment charset for decoding. (d)
scroll_up- Scroll up list. (k)
scroll_down- Scroll down list. (j)
collapse_subtree- collapse thread branches. (h)
next_page- Go to next page. (PageDown)
prev_page- Go to previous page. (PageUp)
reverse_thread_order- reverse thread order. (C-r)
toggle_mailview- toggle mail view visibility. (p)
toggle_threadview- toggle thread view visibility. (t)
toggle_layout- Toggle between horizontal and vertical layout. (Space)
NOTIFICATIONS¶
System notifications¶
meli(1) can display notifications for
asynchronous, out-of-band events that happen. These events can be any event
of interest that is not a direct result of the user's interaction with the
user interface, like for example receiving a new e-mail, or an
SMTP server accepting an e-mail for delivery, or a backend
watch mechanism error. The used notification mechanism depending on the
platform is
dbus if it
is available on your system and if meli(1) has been
compiled with support for it (check output of
compiled-with CLI subcommand), or
NSUserNotification
on MacOS. Otherwise the fallback mechanism is calling a script to display a
notification. If script is defined in your
configuration, this mechanism will be preferred even if OS system
notifications are available.
You can browse through previously shown notifications with
shortcuts.general.info_message_next and
shortcuts.general.info_message_previous
shortcuts.
Notification configuration settings¶
Default values are shown in parentheses.
enableNotificationEnable- (optional) How to handle notifications.
(system_and_ui) Valid values:
system_and_ui- Always show as both system and inside the UI.
none- Do not show notifications.
system_only- Show them only as system notifications.
ui_only- Show them only as UI notifications.
scriptString- (optional) Script to pass notifications to, with kind as
1st argument, title as 2nd and body as 3rd. (none) Kind
values:
- "info"
- "error" or "error: " plus kind
- "new mail"
- "sent mail"
- "saved"
new_mail_scriptString- (optional) A command to pipe new mail notifications
through (preferred over
script, and has the exact same usage). (none) xbiff_file_pathString- (optional) File that gets its size updated when new mail arrives. (none)
play_soundboolean- (optional) Play theme sound in notifications if possible. (false)
sound_fileString- (optional) Play sound file in notifications if possible. (none)
PAGER¶
Pager (viewing text) configuration settings¶
Default values are shown in parentheses.
sticky_headersboolean- (optional) Always show headers when scrolling. (false)
html_filterString- (optional) Pipe html attachments through this filter before display (none)
html_openString- (optional) A command to open html files. (none)
filterString- (optional) A command to pipe mail output through for viewing in pager.
named_filtersString[String]- (optional) Named filter commands to use at will.
(empty)
Show menu with an empty
filtercommand. Example:[pager] named_filters = { diff = "pygmentize -l diff -f 256", par = "par 72" } format_flowedboolean- (optional) Respect format=flowed (true)
split_long_linesboolean- (optional) Split long lines that would overflow on the x axis. (true)
minimum_widthnum- (optional) Minimum text width in columns. (80)
auto_choose_multipart_alternativeboolean- (optional) Choose
text/htmlalternative iftext/plainis empty inmultipart/alternativeattachments. (true) show_date_in_my_timezoneboolean- (optional) Show
Date: in local timezone (true) url_launcherString- (optional) A command to launch URLs with. The URL will be given as the first argument of the command. (xdg-open)
show_extra_headers[String]- (optional) Extra headers to display, if present, in the
default header preamble of the pager. (empty)
This setting is useful especially when used per-folder or per-account. For example, if you use rss2email (See r2e(1)) the e-mail you will receive will have the X-RSS-Feed header by default. You can show them only in the folder where you keep your feed items:
[accounts."personal".mailboxes] INBOX = {} "INBOX/Sent" = { sort_order=0 } "INBOX/Feeds" = { pager.show_extra_headers = ["X-RSS-Feed"] }
LISTING¶
Listing (lists of e-mail entries in a mailbox) configuration settings¶
Default values are shown in parentheses.
- (optional)
Show auto-hiding scrollbar in accounts sidebar menu. (true) datetime_fmtString- (optional) Datetime formatting passed verbatim to strftime(3). (%Y-%m-%d %T)
recent_datesBoolean- (optional) Show recent dates as
‘
X {minutes,hours,days} ago’, up to 7 days. (true) filterQuery- (optional) Show only envelopes matching this query. (For
query syntax see meli(1) QUERY ABNF SYNTAX)
(None)
Example:
filter = "not flags:seen" # show only unseen messages
index_styleString- Sets the way mailboxes are displayed.
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 - (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.
- (optional) Sets the string to print in the mailbox tree for a level where its root has no sibling.
- (optional) Sets the string to print in the mailbox tree for a leaf level where its root has a sibling.
- (optional) Sets the string to print in the mailbox tree for a leaf level where its root has no sibling.
- (optional) Sets the character to print as the divider between the accounts list and the message list.
- (optional) This is the width of the right container to the entire screen width. (90)
unseen_flagOption<String>- Flag to show if thread entry contains unseen mail. (●)
thread_snoozed_flagOption<String>- Flag to show if thread has been snoozed.
("
💤\u{FE0E}") [Rendered as:r##"💤︎"##] selected_flagOption<String>- Flag to show if thread entry has been selected.
("
☑️ \u{2007}") [Rendered as:r##"☑️ "##] attachment_flagOption<String>- Flag to show if thread entry contains attachments.
("
📎\u{FE0E}") [Rendered as:r##"📎︎"##] highlight_self_flagOption<String>- Flag to show if any thread entry contains your address as a receiver. Useful to make mailing list threads that CC you stand out. (✸)
highlight_selfboolean- Show
highlight_self_flagor not. (false) thread_subject_packboolean- Should threads with differentiating Subjects show a list of those subjects on the entry title? (true)
threaded_repeat_identical_from_valuesboolean- In threaded listing style, repeat identical From column values within a thread. Not repeating adds empty space in the From column which might result in less visual clutter. (false)
- Show relative indices in menu mailboxes to quickly help with jumping to them. (true)
relative_list_indicesboolean- Show relative indices in listings to quickly help with jumping to them. (true)
- Start app with sidebar hidden. (false)
mail_view_dividerchar- Character to show in the divider space between mail view and listing. (' ')
thread_layoutauto | vertical | horizontal- Force specific layout in thread view. The layout can also be toggled at
runtime with the
listing.toggle_layoutshortcut. (auto) sort(SortField, SortOrder)- Sort order. Sort field can take the values "date" and "subject", and sort order the values "asc" and "desc". ([date, desc)]
Examples of sidebar mailbox tree customization¶
The default values
has_sibling = " " no_sibling = " "; has_sibling_leaf = " " no_sibling_leaf = " "
render a mailbox tree like the following:
0 Inbox 3 1 Archive 2 Drafts 3 Lists 4 example-list-a 5 example-list-b 6 Sent 7 Spam 8 Trash
Other possible trees:
has_sibling = " ┃" no_sibling = " " has_sibling_leaf = " ┣━" no_sibling_leaf = " ┗━"
0 Inbox 3 1 ┣━Archive 2 ┣━Drafts 3 ┣━Lists 4 ┃ ┣━example-list-a 5 ┃ ┗━example-list-b 6 ┣━Sent 7 ┣━Spam 8 ┗━Trash
A completely ASCII one:
has_sibling = " |" no_sibling = " " has_sibling_leaf = " |\_" no_sibling_leaf = " \_"
0 Inbox 3 1 |\_Archive 2 |\_Drafts 3 |\_Lists 4 | |\_example-list-a 5 | \_example-list-b 6 |\_Sent 7 |\_Spam 8 \_Trash
TAGS¶
Tags (e-mail metadata in backends that support them) configuration settings¶
Default values are shown in parentheses.
colourshash table String[Color]- (optional) Set UI colors for tags
- (optional) Hide tags (not the tagged messages themselves)
renamehash table String[String]- (optional) Rename the tag when shown in the UI (not used as an alias any other way).
Example:
[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", ] }
"Project" = { tags.rename = { "bug" = "🐜" } }
PGP¶
Default values are shown in parentheses.
auto_verify_signaturesboolean- Auto verify signed e-mail according to RFC3156 (true)
auto_decryptboolean- (optional) Always decrypt encrypted e-mail (true)
auto_signboolean- (optional) Always sign sent messages (false)
auto_encryptboolean- (optional) Always encrypt sent messages (false)
sign_keyString- (optional) ID of key to be used for signatures (none)
decrypt_keyString- (optional) ID of key to be used for decryption (none)
encrypt_keyString- (optional) ID of key to be used for encryption (none)
auto_remote_lookupboolean- (optional) Allow remote lookups (false)
remote_lookup_mechanismsLocateKey- (optional) Remote lookup mechanisms. Use comma to
separate values.
(local,wkd)
Possible mechanisms:
backendPGPBackendChoice- (optional)
PGP backend to use. (sequoia)Possible values:
- libgpgme backend (requires that meli(1) has been
compiled with support for libgpgme, check output of
compiled-withCLI subcommand):backend = "gpgme"
- CLI backend Example:
For example scripts and their invocation and input/output formats, in the meli repository under the contrib/pgp-cli-backends/gpg directory you can find python scripts that work with the gpg(1) binary.
backend = { verify_command = "gpg_verify.py", sign_command = "gpg_sign.py", encrypt_command = "gpg_encrypt.py", decrypt_command = "gpg_decrypt.py", get_key_command = "gpg_get_key.py", keylist_command = "gpg_keylist.py" } - sequoia backend (requires that meli(1) has been
compiled with support for sequoia, check output of
compiled-withCLI subcommand):backend = "sequoia"
- libgpgme backend (requires that meli(1) has been
compiled with support for libgpgme, check output of
TERMINAL¶
Note about emojis and other multi-width characters in string values¶
Some useful unicode combining marks (invisible characters that modify the presentation of visible characters before them) are:
\u{FE0E}Emoji variation sequence select 15: renders an emoji as text style (monochrome)\u{FE0F}Emoji variation sequence select 16: renders an emoji in color\u{2007}Figure space, a space character with the width of a digit in a monospace typeface
Terminal configuration settings¶
Default values are shown in parentheses.
themeString- (optional) "light", "dark", "auto" or a named theme to use. (auto)
tab_widthu8- How many cells a tab character occupies. (4)
ascii_drawingboolean- (optional) If true, box drawing will be done with ASCII characters. (false)
use_colorboolean- (optional) If false, no ANSI colors are used. (true)
force_text_presentationboolean- (optional) If true, text presentations of color symbols and emoji will be enforced as much as possible. Might not work on all non-text symbols and is experimental. (false)
window_titleString- (optional) Set window title in xterm compatible terminals An empty string means no window title is set. (meli)
file_picker_commandString- (optional) Set command that prints file paths in stdout,
separated by NUL bytes. Used with
add-attachment-file-pickerwhen composing new mail. (None) themeshash table String[String[Attribute]]- Define UI themes. See meli-themes(5)
for details.
[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] ... use_mouseboolean- Use mouse events. This will disable text selection, but you will be able
to resize some widgets. This setting can be toggled with
toggle mouse. (false) mouse_flagString- String to show in status bar if mouse is active. (🖱️)
progress_spinner_sequenceEither < 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.
(20)
Built-in sequences are:
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 ["🌑 ", "🌒 ", "🌓 ", "🌔 ", "🌕 ", "🌖 ", "🌗 ", "🌘 "]
Or, define an array of strings each consisting of a frame in the progress sequence indicator for a custom spinner:
interval_msu64- (optional) Frame interval. (50)
frames[String]- The animation frames.
Example:
progress_spinner_sequence = { interval_ms = 150, frames = [ "-", "=", "≡" ] } quit_confirmationboolean- Whether the
shortcuts.general.quitshortcut needs a confirmation to quit. (true) store_component_statesboolean- Store some TUI state such as current tab in $XDG_STATE_HOME/meli/ (which is usually $HOME/.local/state/meli/) directories. (true)
LOG¶
Logging configuration settings¶
Default values are shown in parentheses.
log_fileString- (optional) path of the log file ($XDG_DATA_HOME/meli/meli.log)
maximum_levelString- (optional) maximum level of messages to log. All levels
less or equal to the
maximum_levelwill be appended to the log file. Available levels are, in partial order: This means that to turn logging off, setmaximum_levelto OFF. (INFO)
SMTP Connections¶
SMTP configuration settings¶
Default values are shown in parentheses.
hostnameString- server hostname
portInteger- server port
envelope_fromString- (optional) address to set as sender in SMTP transactions (none)
authSmtpAuth- SMTP server authentication. See SmtpAuth subsection.
securitySmtpSecurity- (optional) gpg binary name or file location to use. (see SmtpSecurity subsection)
extensionsSmtpExtensions- (optional) set support for SMTP extensions if they are advertised by the server. (see SmtpExtensions subsection)
SmtpAuth¶
typenone | auto | xoauth2 | oauthbearer
For type "auto":
usernameStringpasswordSmtpPasswordrequire_authboolean- (optional) require authentication in every case. (true)
For type "xoauth2":
tokenSecret- A string literal or a command to evaluate that returns an XOAUTH2 token.
require_authboolean- (optional) require authentication in every case. (true)
For type "oauthbearer":
tokenSecret- A string literal or a command to evaluate that returns an OAUTHBEARER token (not base64 encoded).
require_authboolean- (optional) require authentication in every case. (true)
Examples:
auth = { type = "auto", username = "user", password = { type = "raw", value = "hunter2" } }
auth = { type = "auto", username = "user", password = "hunter2" }
auth = { type = "none" }
For Gmail (see Gmail OAUTH2 for details on the authentication token command):
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" } }
SmtpPassword¶
Takes either a raw password string, or command to execute (type is Secret).
Deprecated syntax:
Examples:
password = "hunter2"
# deprecated syntax
password = { type = "raw", value = "hunter2" }
password = { command = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" }
# deprecated syntax
password = { type = "command_eval", value = "gpg2 --no-tty -q -d ~/.passwords/user.gpg" }
SmtpSecurity¶
Default security type is auto.
typenone | auto | starttls | tlsdanger_accept_invalid_certsboolean- Accept invalid SSL / TLS certificates (false)
SmtpExtensions¶
pipeliningboolean- RFC2920 (true)
chunkingboolean- RFC3030 (true)
prdrboolean- draft-hall-prdr-00 (true)
dsn_notifyString- RFC3461 (FAILURE)
Types and syntax¶
- Secret
- Either a string, or:
commandStringstore_in_memoryboolean- (optional) If possible, store value in memory instead of re-evaluating the command. (false)
SEE ALSO¶
STANDARDS¶
- TOML
Standard
v.0.5.0https://toml.io/en/v0.5.0
AUTHORS¶
Copyright 2017–2024 Manos Pitsidianakis <manos@pitsidianak.is>
Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)
Links¶
| May 20, 2024 | Nixpkgs |