meli/meli.conf.5

14 KiB
Raw Blame History

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

NAME
     meli.conf  configuration file for the Meli Mail User Agent

SYNOPSIS
     $XDG_CONFIG_HOME/meli/config

DESCRIPTION
     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*$

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

     example configuration

     # Setting up a Maildir account
     [accounts.account-name]
     root_folder = "/path/to/root/folder"
     format = "Maildir"
     index_style = "Compact"
     identity="email@address.tld"
     subscribed_folders = ["folder", "folder/Sent"] # or [ "*", ] for all folders
     display_name = "Name"

     # Set folder-specific settings
       [accounts.account-name.folders]
       "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
     [accounts.mbox]
     root_folder = "/var/mail/username"
     format = "mbox"
     index_style = "Compact"
     identity="username@hostname.local"

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

     [notifications]
     script = "notify-send"

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

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

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

     [terminal]
     theme = "light"

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

ACCOUNTS
     root_folder String                    the backend-specific path of the
                                           root_folder, usually INBOX.

     format String [maildir mbox imap notmuch]
                                           the format of the mail backend.

     subscribed_folders [String,]          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.

     identity String                       your e-mail address that is
                                           inserted in the From: headers of
                                           outgoing mail

     index_style String                    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 │
     └──────────────┴─────────────────────────────────────────────────┘
     display_name String                   (optional) a name which can be
                                           combined with your address: "Name
                                           <email@address.tld>"

     read_only boolean                     attempt to not make any changes to
                                           this account.  (false)

     cache_type String                     (optional) choose which cache
                                           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.

     folders folder_config                 (optional) configuration for each
                                           folder. Its format is described
                                           below in FOLDERS.

notmuch only
     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:

     [accounts.notmuch]
     format = "notmuch"
     ...
       [accounts.notmuch.folders]
       "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 only
     IMAP specific options are:

     server_hostname String                example: "mail.example.tld"

     server_username String

     server_password String

     server_port number                    (optional) (143)

     use_starttls boolean                  (optional) if port is 993 and
                                           use_starttls is unspecified, it
                                           becomes false by default.  (true)

     danger_accept_invalid_certs boolean   (optional) do not validate TLS
                                           certificates.  (false)

FOLDERS
     rename String                         (optional) show a different name
                                           for this folder in the UI

     autoload boolean                      (optional) load this folder on
                                           startup (not functional yet)

     subscribe boolean                     (optional) watch this folder for
                                           updates (true)

     ignore boolean                        (optional) silently insert updates
                                           for this folder, if any (false)

     usage boolean                         (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.

     conf_override boolean                 (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:

                                           [accounts."imap.domain.tld".folders."INBOX"]
                                             index_style = "plain"
                                             [accounts."imap.domain.tld".folders."INBOX".pager]
                                               filter = ""

COMPOSING
     mailer_cmd String                     command to pipe new mail to, exit
                                           code must be 0 for success.

     editor_cmd 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.

     embed boolean                         (optional) embed editor within meli
                                           (false)

     format_flowed boolean                 (optional) set format=flowed
                                           [RFC3676] in text/plain
                                           attachments.  (true)

SHORTCUTS
     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:

     [shortcuts.general]
     next_tab = 'T'

     and for compact-listing:

     [shortcuts.compact-listing]
     open_thread = "Enter"
     exit_thread = 'i'

     general

     next_tab
                                           Go to next tab.
                                           (T)

     go_to_tab
                                           Go to the
                                           n
                                           th tab
                                           (cannot be redefined)

     listing

     prev_page
                                           Go to previous page.
                                           (PageUp)

     next_page
                                           Go to next page.
                                           (PageDown)

     prev_folder
                                           Go to previous folder.
                                           (K)

     next_folder
                                           Go to next folder.
                                           (J)

     prev_account
                                           Go to previous account.
                                           (l)

     next_account
                                           Go to next account.
                                           (h)

     new_mail
                                           Start new mail draft in new tab
                                           (m)

     search
                                           Search within list of e-mails.
                                           (/)

     toggle_menu_visibility
                                           Toggle visibility of side menu in mail list.
                                           (`)

     compact-listing

     exit_thread
                                           Exit thread view
                                           (i)

     open_thread
                                           Open thread.
                                           (Enter)

     select_entry
                                           Select thread entry.
                                           (v)

     pager

     scroll_up
                                           Scroll up pager.
                                           (k)

     scroll_down
                                           Scroll down pager.
                                           (j)

     page_up
                                           Go to previous pager page
                                           (PageUp)

     page_down
                                           Go to next pager pag
                                           (PageDown)

     contact-list

     create_contact
                                           Create new contact.
                                           (c)

     edit_contact
                                           Edit contact under cursor
                                           (e)

     mail_contact
                                           Mail contact under cursor
                                           (m)

     toggle_menu_visibility
                                           Toggle visibility of side menu in mail list.
                                           (`)


     composing

     send_mail
                                           Deliver draft to mailer
                                           (s)

     edit_mail
                                           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.

     add_addresses_to_contacts
                                           Select addresses from envelope to add to contacts.
                                           (c)

     view_raw_source
                                           View raw envelope source in a pager.
                                           (M-r)

     reply
                                           Reply to envelope.
                                           (R)

     edit
                                           Open envelope in composer.
                                           (e)

     return_to_normal_view
                                           Return to envelope if viewing raw source or attachment.
                                           (r)

     open_attachment
                                           Opens selected attachment with
                                           xdg-open
                                           (a)

     open_mailcap
                                           Opens selected attachment according to its mailcap entry. See
                                           meli.1(FILES)
                                           for the mailcap file locations.
                                           (m)

     go_to_url
                                           Go to url of given index
                                           (g)

     toggle_url_mode
                                           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)

     toggle_expand_headers
                                           Expand extra headers (References and others)
                                           (h)

     thread-view

     reverse_thread_order
                                           Reverse thread order.
                                           (r)

     toggle_mailview
                                           Toggle mail view visibility.
                                           (p)

     toggle_threadview
                                           Toggle thread view visibility.
                                           (t)

     collapse_subtree
                                           Collapse thread branches.
                                           (h)

     prev_page
                                           Go to previous page.
                                           (PageUp)

     next_page
                                           Go to next page.
                                           (PageDown)


NOTIFICATIONS
     enable boolean                        enable freedesktop-spec
                                           notifications. this is usually what
                                           you want (true)

     script String                         (optional) script to pass
                                           notifications to, with title as 1st
                                           arg and body as 2nd (none)

     xbiff_file_path String                (optional) file that gets its size
                                           updated when new mail arrives
                                           (none)

     play_sound boolean                    (optional) play theme sound in
                                           notifications if possible (false)

     sound_file String                     (optional) play sound file in
                                           notifications if possible (none)

PAGER
     pager_context num                     (optional) number of context lines
                                           when going to next page.
                                           (Unimplemented) (0)

     headers_sticky boolean                (optional) always show headers when
                                           scrolling.  (true)

     html_filter String                    (optional) pipe html attachments
                                           through this filter before display
                                           (none)

     filter String                         (optional) a command to pipe mail
                                           output through for viewing in
                                           pager.  (none)

     format_flowed bool                    (optional) respect format=flowed
                                           (true)

     split_long_lines bool                 (optional) Split long lines that
                                           would overflow on the x axis.
                                           (true)

     minimum_width num                     (optional) Minimum text width in
                                           columns.  (80)

TAGS
     colours hash table String[Color]      (optional) set UI colors for tags

     ignore_Tags Array String              (optional) hide tags (not the
                                           tagged messages themselves)

                                           example configuration

                                           [tags]
                                           # valid inputs: #HHHHHH, #ABC -> #AABBCC, XTERM_NAME, 0-255 byte
                                           colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
                                           [accounts.dummy]
                                           ...8<--
                                             [accounts.dummy.folders]
                                             # per folder override:
                                             "INBOX" = {  tags.ignore_tags=["inbox", ] }

PGP
     auto_verify_signatures boolean        auto verify signed e-mail according
                                           to RFC3156 (true)

     auto_sign boolean                     (optional) always sign sent
                                           messages (false)

     key String                            (optional) key to be used when
                                           signing/encrypting (not functional
                                           yet) (none)

     gpg_binary String                     (optional) gpg binary name or file
                                           location to use (gpg2)

TERMINAL
     theme String                          (optional) select between these
                                           themes: light / dark (dark)

     ascii_drawing boolean                 (optional) if true, box drawing
                                           will be done with ascii characters.
                                           (false)

     window_title String                   (optional) set window title in
                                           xterm compatible terminals (empty
                                           string means no window title is
                                           set) (meli)

SEE ALSO
     meli(1)

CONFORMING TO
     TOML Standard v.0.5.0 https://github.com/toml-
     lang/toml/blob/master/versions/en/toml-v0.5.0.md

AUTHORS
     Copyright 2017-2019 Manos Pitsidianakis ⟨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.)

     ⟨https://meli.delivery⟩

Debian                        September 16, 2019                        Debian