Technical documentation: You can view the rustdoc generated documentation here

Quick start tutorial

Follow the installation instructions in the README.

Launch meli with no arguments, and you will be asked if you want to create a sample configuration.

The sample configuration (by default in ~/.config/meli/config) includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away. See meli.conf(5) for the available configuration options.

The main screen when you launch meli is the INBOX of the first account you have configured.

At any time, you can press ? to show a list of all available actions and shortcuts, along with every possible setting and command that your version supports.

Press T to cycle between tabs or Alt + 19 to choose.

Press q to exit.


MELI(1) General Commands Manual MELI(1)

Meli Mail User Agent. meli is the Greek word for honey

meli [--help | -h] [--version | -v] [--create-config [path]] [--test-config [path]] [--config path]


Experimental terminal mail client
Show help message and exit.
Show version and exit.
Create configuration file in path if given, or at $XDG_CONFIG_HOME/meli/config
Test a configuration file for syntax issues or missing options.
Start meli with given configuration file.

When launched for the first time, meli will search for its configuration directory, $XDG_CONFIG_HOME/meli/. If it doesn't exist, you will be asked if you want to create one along with a sample configuration. The sample configuration $XDG_CONFIG_HOME/meli/config includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away. See meli.conf(5) for the available configuration options.

At any time, you may press ? to show a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.

The main visual navigation tool is the left-side sidebar. The menu's visibility may be toggled with ` (shortcuts.listing: toggle_menu_visibility).

The view into each folder has 4 modes: plain, threaded, conversations and compact. Plain views each mail indvidually, threaded shows their thread relationship visually, and conversations includes one entry per thread of emails (compact is one row per thread).

If you're using a light color palette in your terminal, you may set theme = light in the terminal section of your configuration.

         ^^      .-=-=-=-.  ^^
     ^^        (`-=-=-=-=-`)         ^^
             (`-=-=-=-=-=-=-`)  ^^         ^^
       ^^   (`-=-=-=-=-=-=-=-`)   ^^
           ( `-=-=-=-(@)-=-=-` )      ^^
           (`-=-=-=-=-=-=-=-=-`)  ^^
           (`-=-=-=-=-=-=-=-=-`)          ^^
    ^^     (`-=-=-=-=-=-=-=-=-`)  ^^
       ^^   (`-=-=-=-=-=-=-=-`)          ^^
             (`-=-=-=-=-=-=-`)  ^^
      ^^       (`-=-=-=-=-`)
                `-=-=-=-=-`          ^^

Open attachments by typing their index in the attachments list and then a. meli will attempt to open text inside its pager and other content via xdg-open. Press m instead to use the mailcap entry for the MIME type of the attachment, if any. See FILES for the location of the mailcap files and mailcap(5) for their syntax.

Each e-mail storage backend has its default search method. IMAP uses the SEARCH command, notmuch uses libnotmuch and Maildir/mbox have to do a slow linear search. Thus it is advised to use a cache on Maildir/mbox accounts. meli, if built with sqlite3, includes the ability to perform full text search on the following fields: From, To, Cc, Bcc, In-Reply-To, References, Subject and Date. The message body (in plain text human readable form) and the flags can also be queried. To enable sqlite3 indexing for an account set cache_type to sqlite3 in the configuration file and to create the sqlite3 index issue command index ACCOUNT_NAME.

To search in the message body type your keywords without any special formatting. To search in specific fields, prepend your search keyword with "field:" like so:

subject:helloooo or subject:"call for help" or "You remind me today of a small, Mexican chihuahua."

not ((from:unrealistic and (to:complex or not query )) or flags:seen,draft)

alladdresses:mailing@list.tld and cc:me@domain.tld

Boolean operators are or, and and not (alias: !) String keywords with spaces must be quoted. Quotes should always be escaped.

Important Notice about IMAP

To prevent downloading all your messages from your IMAP server, don't set cache_type to sqlite3. meli will relay your queries to the IMAP server. Expect a delay between query and response. Sqlite3 on the contrary at reasonable mailbox sizes should have a non noticable delay.

To send mail, press m while viewing the appropriate account to open a new composing tab. To reply to a mail, press R. You may edit some of the header fields from within the view, by selecting with the arrow keys and pressing enter to enter INSERT mode. At any time you may press e to launch your editor (see meli.conf(5) COMPOSING, setting editor_cmd for how to select which editor to launch). Attachments may be handled with the add-attachment, remove-attachment commands (see below). Finally, pressing s will send your message by piping it into a binary of your choosing (see meli.conf(5) COMPOSING, setting mailer_cmd). To save your draft without sending it, issue command close and select 'save as draft'.

With no Draft or Sent folder, meli tries first saving mail in your INBOX and then at any other folder. On complete failure to save your draft or sent message it will be saved in your tmp directory instead and you will be notified of its location.

To open a draft for editing later, select your draft in the mail listing and press e.

Your editor can be used in meli's embed terminal emulator by setting embed to true in your composing settings. When launched, your editor captures all input until it exits or stops. To stop your editor and return to meli issue Ctrl-z and to resume editing press the edit_mail command again (default e).

meli supports two kinds of contact backends:

  1. an internal format that gets saved under $XDG_DATA_HOME/meli/account_name/addressbook.
  2. vCard files (v3, v4) through the vcard_folder option in the account section. The path defined as vcard_folder can hold multiple vCards per file. They are loaded read only.

See meli.conf(5) ACCOUNTS for the complete account configuration values.

Commands are issued in EXECUTE mode, by default started with Space and exited with Escape key.

the following commands are valid in the mail listing context:

plain | threaded | compact | conversations
set 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
subject | date   asc | desc
sort mail listing
subject | date   asc | desc
sorts only the first level of replies.
where n is a mailbox prefixed with the n number in the side menu for the current account
don't issue notifications for thread under cursor in thread listing
filter mailbox with STRING key. Escape exits filter results
create folder with given path. be careful with backends and separator sensitivity (eg IMAP)
subscribe to folder with given path
unsubscribe to folder with given path
rename folder
delete folder

envelope view commands:

pipe pager contents to binary
post in list of viewed envelope
unsubscribe automatically from list of viewed envelope
open list archive with xdg-open

composing mail commands:

in composer, add PATH as an attachment
remove attachment with given index
toggle between signing and not signing this message. If the gpg invocation fails then the mail won't be sent.

generic commands:

opens envelope view in new tab
closes closeable tabs
set environment variable KEY to VALUE
print environment variable KEY

Non-complete list of shortcuts and their default values.
toggles hiding of sidebar in mail listings
opens up a shortcut window that shows available actions in the current component you are using (eg mail listing, contact list, mail composing)
starts a new mail composer
replies to the viewed mail.
displays numbers next to urls in the body text of an email and ng opens the nth url with xdg-open
opens the nth attachment.
opens the nth attachment according to its mailcap entry.
(un)selects mail entries in mail listings

meli exits with 0 on a successful run. Other exit statuses are:
catchall for general errors

Specifies the editor to use
Override the configuration file

meli uses the following parts of the XDG standard:
defaults to ~/.config/
defaults to ~/.cache/

and appropriates the following locations:

User configuration directory.
User configuration file. See meli.conf(5) for its syntax and values.
Reserved for event hooks.
Reserved for plugin files.
Internal cached data used by meli.
Internal data used by meli.
Operation log.
Temporary files generated by meli.

Mailcap entries are searched for in the following files, in this order:

  1. $XDG_CONFIG_HOME/meli/mailcap
  2. $XDG_CONFIG_HOME/.mailcap
  3. $HOME/.mailcap
  4. /etc/mailcap
  5. /usr/etc/mailcap
  6. /usr/local/etc/mailcap

meli.conf(5), xdg-open(1), mailcap(5)

XDG Standard ⟨⟩, maildir ⟨⟩, IMAPv4rev1 RFC3501.

Copyright 2017-2019 Manos Pitsidianakis ⟨⟩ Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)


July 29, 2019 rendered by mandoc

meli.conf(5) [go back]

MELI.CONF(5) File Formats Manual MELI.CONF(5)

configuration file for the Meli Mail User Agent



Configuration for meli is written in TOML. Few things to consider before writing TOML (quoting the spec):

  • TOML is case sensitive.
  • A TOML file must be a valid UTF-8 encoded Unicode document.
  • Whitespace means tab (0x09) or space (0x20).
  • Newline means LF (0x0A) or CRLF (0x0D 0x0A).

Refer to TOML documentation for valid TOML syntax.

Thought not part of TOML syntax, meli.conf can have nested configuration files by using the following include directive, which though starting with # is not a comment:

#include "/path/to/file"

The accepted regular expression is ^\s*include\s*\"(\\.|[^\"])+\"\s*$

The top level sections of the config are accounts, shortcuts, notifications, pager, composing, pgp, terminal.

example configuration

# Setting up a Maildir account
root_folder = "/path/to/root/folder"
format = "Maildir"
index_style = "Compact"
subscribed_folders = ["folder", "folder/Sent"] # or [ "*", ] for all folders
display_name = "Name"

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

# Setting up an mbox account
root_folder = "/var/mail/username"
format = "mbox"
index_style = "Compact"

filter = "/usr/bin/pygmentize"
html_filter = "w3m -I utf-8 -T text/html"

script = "notify-send"

# required for sending e-mail
mailer_cmd = 'msmtp --read-recipients --read-envelope-from'
editor_cmd = 'vim +/^$'

edit_mail = 'e'

new_mail = 'm'
set_seen = 'n'

theme = "light"

available options are listed below. default values are shown in parentheses.

the backend-specific path of the root_folder, usually INBOX.
String [maildir mbox imap notmuch]
the format of the mail backend.
an array of folder paths to display in the UI. Paths are relative to the root folder (eg "INBOX/Sent", not "Sent"). The glob wildcard * can be used to match every folder name and path.
your e-mail address that is inserted in the From: headers of outgoing mail
set 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) a name which can be combined with your address: "Name <email@address.tld>"
attempt to not make any changes to this account. (false)
(optional) choose which cache backend to use. Available options are 'none' and 'sqlite3' (sqlite3)
(optional) Folder that contains .vcf files. They are parsed and imported read-only.
(optional) configuration for each folder. Its format is described below in FOLDERS.

root_folder points to the directory which contains the .notmuch/ subdirectory. notmuch folders are virtual, since they are defined by user-given notmuch queries. Thus you have to explicitly state the folders you want in the folders field and set the query property to each of them. Example:
format = "notmuch"
  "INBOX" = {  query="tag:inbox", subscribe = true }
  "Drafts" = {  query="tag:draft", subscribe = true }
  "Sent" = {  query="from:username@server.tld from:username2@server.tld", subscribe = true }

IMAP specific options are:
example: “mail.example.tld”
(optional) (143)
(optional) if port is 993 and use_starttls is unspecified, it becomes false by default. (true)
(optional) do not validate TLS certificates. (false)

(optional) show a different name for this folder in the UI
(optional) load this folder on startup (not functional yet)
(optional) watch this folder for updates (true)
(optional) silently insert updates for this folder, if any (false)
(optional) special usage of this folder. valid values are:
  • Normal
  • Inbox
  • Archive
  • Drafts
  • Flagged
  • Junk
  • Sent
  • Trash
otherwise usage is inferred from the folder title.
(optional) override global settings for this folder. available sections to override are pager, notifications, shortcuts, composing and the account options identity and index_style. example:
  index_style = "plain"
    filter = ""

command to pipe new mail to, exit code must be 0 for success.
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.
(optional) embed editor within meli (false)
(optional) set format=flowed [RFC3676] in text/plain attachments. (true)

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” and “char”, where char is a single character string.

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:

next_tab = 'T'

and for compact-listing:

open_thread = "Enter"
exit_thread = 'i'


Go to next tab. (T )
Go to the n th tab (cannot be redefined )
Go to previous page. (PageUp )
Go to next page. (PageDown )
Go to previous folder. (K )
Go to next folder. (J )
Go to previous account. (l )
Go to next account. (h )
Start new mail draft in new tab (m )
Search within list of e-mails. (/ )
Toggle visibility of side menu in mail list. (` )
Exit thread view (i )
Open thread. (Enter )
Select thread entry. (v )
Scroll up pager. (k )
Scroll down pager. (j )
Go to previous pager page (PageUp )
Go to next pager pag (PageDown )
Create new contact. (c )
Edit contact under cursor (e )
Mail contact under cursor (m )
Toggle visibility of side menu in mail list. (` )
Deliver draft to mailer (s )
Edit mail. (e )
envelope-view To "select" an attachment, type its index (you will see the typed result in the command buffer on your bottom right of the status line) and then issue the corresponding command.
Select addresses from envelope to add to contacts. (c )
View raw envelope source in a pager. (M-r )
Reply to envelope. (R )
Open envelope in composer. (e )
Return to envelope if viewing raw source or attachment. (r )
Opens selected attachment with xdg-open (a )
Opens selected attachment according to its mailcap entry. See meli.1(FILES) for the mailcap file locations. (m )
Go to url of given index (g )
Toggles url open mode. When active, it prepends an index next to each url that you can select by typing and open by issuing go_to_url (u )
Expand extra headers (References and others) (h )
Reverse thread order. (r )
Toggle mail view visibility. (p )
Toggle thread view visibility. (t )
Collapse thread branches. (h )
Go to previous page. (PageUp )
Go to next page. (PageDown )

enable freedesktop-spec notifications. this is usually what you want (true)
(optional) script to pass notifications to, with title as 1st arg and body as 2nd (none)
(optional) file that gets its size updated when new mail arrives (none)
(optional) play theme sound in notifications if possible (false)
(optional) play sound file in notifications if possible (none)

(optional) number of context lines when going to next page. (Unimplemented) (0)
(optional) always show headers when scrolling. (true)
(optional) pipe html attachments through this filter before display (none)
(optional) a command to pipe mail output through for viewing in pager. (none)
(optional) respect format=flowed (true)
(optional) Split long lines that would overflow on the x axis. (true)
(optional) Minimum text width in columns. (80)

auto verify signed e-mail according to RFC3156 (true)
(optional) always sign sent messages (false)
(optional) key to be used when signing/encrypting (not functional yet) (none)
(optional) gpg binary name or file location to use (gpg2)

(optional) select between these themes: light / dark (dark)
(optional) if true, box drawing will be done with ascii characters. (false)
(optional) set window title in xterm compatible terminals (empty string means no window title is set) (meli)


TOML Standard v.0.5.0

Copyright 2017-2019 Manos Pitsidianakis ⟨⟩ Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)


September 16, 2019 rendered by mandoc

[go back]