--- name: "meli.conf" section: "5" platform: "linux" package: "meli" version: "0.8.11+dfsg-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/meli.conf" --- # meli.conf(5) configuration file for the meli(1) terminal e-mail client ## NAME **meli.conf** – configuration file for the [meli(1)](/meli/1.md) 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)](/m4/1.md) 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" # 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 = '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\_mailbox** *String* The backend-specific path of the root\_mailbox, usually**INBOX** . - **default\_mailbox** *String* (*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. - **format** *String* \[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. - **identity** *String* Your e-mail address that is inserted in theFrom : headers of outgoing mail. - **extra\_identities** *\[String,\]* Extra e-mail address identities. When replying to an e-mail addressed to one of these identities, theFrom : header will be adjusted to its value instead of the default identity. - **display\_name** *String* (*optional*) A name which can be combined with your address:"Name \" . - **read\_only** *boolean* Attempt to not make any changes to this account. (*false*) - **manual\_refresh** *boolean* (*optional*) If true, do not monitor account for changes( you can use shortcut listing.refresh) . (*false*) - **refresh\_command** *String* (*optional*) command to execute when manually refreshing( shortcut listing.refresh) (*None*) - **search\_backend** *String* (*optional*) Choose which search backend to use. Available options are "none" and"sqlite3" . ("sqlite3") - **vcard\_folder** *String* (*optional*) Folder that contains **.vcf** files. They are parsed and imported read-only. - **mutt\_alias\_file** *String* (*optional*) Path of [mutt(1)](/mutt/1.md) compatible alias file in the option They are parsed and imported read-only. - **notmuch\_address\_book\_query** *String* (*optional*) Query passed to "notmuch address" to import contacts into meli. Contacts are parsed and imported read-only. - **mailboxes** *mailbox* (*optional*) Configuration for each mailbox. Its format is described below inmailboxes . ### 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\_path** *Path* Use an arbitrary location of **libnotmuch** by specifying its full filesystem path. (*optional*) Mailbox properties: - **query** *String* The **notmuch** query that defines what content this virtual mailbox has. Refer to [notmuch-search-terms(7)](/notmuch-search-terms/7.md) for**notmuch** 's search syntax. - **parent** *String* If you wish to build a mailbox hierarchy, define the name of a parent mailbox you have used in your configuration. (*optional*) Example: ``` [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 } ``` ### IMAP only *IMAP* specific options are: - **server\_hostname** *String* example: "mail.example.com" - **server\_username** *String* Server username - **server\_password** *String* Server password - **server\_password\_command** *String* (*optional*) Use instead of **server\_password** - **server\_port** *number* (*optional*) The port to connect to (*143*) - **use\_starttls** *boolean* (*optional*) If port is 993 and "use\_starttls" is unspecified, it becomes false by default. (*true*) - **use\_tls** *boolean* (*optional*) Connect with *TLS*( or upgrade from plain connection to *TLS* if *STARTTLS* is set.) (*true*) - **danger\_accept\_invalid\_certs** *boolean* (*optional*) Do not validate *TLS* certificates. (*false*) - **offline\_cache** *boolean* (*optional*) Keep mail headers in an **sqlite3** database. (*true*) - **use\_idle** *boolean* (*optional*) Use *IDLE* extension. (*true*) - **use\_condstore** *boolean* (*optional*) Use *CONDSTORE* extension. (*true*) - **use\_deflate** *boolean* (*optional*) Use *COMPRESS=DEFLATE* extension (if built with *DEFLATE* support) (*true*) - **use\_oauth2** *boolean* (*optional*) Use *OAUTH2* authentication. Can only be used with **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. (*false*) - **use\_auth\_anonymous** *boolean* (*optional*) Use *AUTH=ANONYMOUS* extension for authentication. (*false*) - **use\_id** *boolean* (*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\_pool** *boolean* (*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*) - **timeout** *integer* (*optional*) Timeout to use for server connections in seconds. A timeout of 0 seconds 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* *API* s, 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.py script 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\_token** and follow the instructions. Note down the refresh token. - In **server\_password\_command** enter a command like this(after adjusting binary paths and credentials) : **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** - 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 = "TOKEN=$(py...th2_string --quiet --access_token=$TOKEN" server_port="993" listing.index_style = "Conversations" identity = "username@gmail.com" display_name = "Name Name" subscribed_mailboxes = ["*" ] composing.store_sent_mail = false composing.send_mail = { hostname = "smtp.gmail.com", port = 587, auth = { type = "xoauth2", token_command = "...", require_auth = true }, security = { type = "STARTTLS" } } ``` ### JMAP only *JMAP* specific options - **server\_url** *String* example: "http://mail.example.com" "http://mail.example.com:8080" "https://mail.example.com" - **server\_username** *String* Server username - **server\_password** *String* Server password - **server\_password\_command** *String* (*optional*) Use instead of **server\_password** - **use\_token** *boolean* Authenticate using the API Bearer token method. If enabled, the token value must be provided as the configured password. (*false*) - **danger\_accept\_invalid\_certs** *boolean* (*optional*) Do not validate *TLS* certificates. (*false*) - **timeout** *integer* (*optional*) Timeout to use for server connections in seconds. A timeout of 0 seconds means there is no timeout. (*16*) ### mbox only *mbox* specific options: - **prefer\_mbox\_type** *String* (*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* (*auto*) To set multiple mailboxes, you have to explicitly state the mailboxes you want in the **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\_hostname** *String* example: "nntp.example.com" - **server\_username** *String* Server username - **server\_password** *String* Server password - **require\_auth** *boolean* (*optional*) require authentication in every case (*true*) - **use\_tls** *boolean* (*optional*) Connect with*TLS* . (*false*) - **server\_port** *number* (*optional*) The port to connect to (*119*) - **danger\_accept\_invalid\_certs** *boolean* (*optional*) Do not validate *TLS* certificates. (*false*) - **store\_flags\_locally** *boolean* (*optional*) Store seen status locally in an **sqlite3** database. (*true*) - **timeout** *integer* (*optional*) Timeout to use for server connections in seconds. A timeout of 0 seconds 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 **send\_mail** field. Example: ``` composing.send_mail = "server_submission" ``` ### MAILBOXES - **alias** *String* (*optional*) Show a different name for this mailbox in the*UI* . - **autoload** *boolean* (*optional*) Load this mailbox on startup (*true*) - **collapsed** *boolean* (*optional*) Collapse this mailbox subtree in menu. (*false*) - **subscribe** *boolean* (*optional*) Watch this mailbox for updates. (*true*) - **ignore** *boolean* (*optional*) Silently insert updates for this mailbox, if any. (*false*) - **usage** *boolean* (*optional*) special usage of this mailbox. Valid values are: - *Normal* (*default*) - *Inbox* - *Archive* - *Drafts* - *Flagged* - *Junk* - *Sent* - *Trash* otherwise usage is inferred from the mailbox title. If for example your Sent folder is not named"Sent" , you must explicitly set it. - **conf\_override** *boolean* (*optional*) Override global settings for this mailbox. Available sections to override are *pager,* *notifications,* *shortcuts,* *composing* and the account options*identity* . Example: ``` [accounts."imap.example.com".mailboxes] "INBOX" = { index_style = "plain" } "INBOX/Lists/devlist" = { autoload = false, pager = { filter = "pygmentize -l diff -f 256"} } ``` - **sort\_order** *unsigned* *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 } ``` - **encoding** *String* (*optional*) Override the default *UTF-8* charset for the mailbox name. Useful only for *UTF-7* mailboxes. (*utf7*, *utf-7*, *utf8*, *utf-8*) ## COMPOSING ### Composing specific configuration settings Default values are shown in parentheses. - **send\_mail** *String\|SmtpServerConf* Command to pipe new mail to( exit code must be 0 for success) or settings for an *SMTP* server connection. See section SMTP Connections for its fields. - **editor\_command** *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. - **embedded\_pty** *boolean* (*optional*) Embedded editor within**meli** . Editor must be **xterm** compliant. (*false*) - **format\_flowed** *boolean* (*optional*) Set format=flowed \[RFC3676\] in text/plain attachments. (*true*) - **insert\_user\_agent** *boolean* (*optional*) Add **meli** User-Agent header in new drafts. (*true*) - **default\_header\_values** *hash* *table* *String\[String\]* (*optional*) Default header values used when creating a new draft. (*{}*) - **wrap\_header\_preamble** *Option\<(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 *\["\