Chapter 6. Optional Features
Prev |  | Next

# Chapter 6. Optional Features

## 1. General Notes

### 1.1. Enabling/Disabling Features

NeoMutt supports several of optional features which can be enabled or disabled at compile-time by giving the configure script certain arguments. These are listed in the “Optional features” section of the configure --help output.

Which features are enabled or disabled can later be determined from the output of `neomutt -v`. If a compile option starts with “+” it is enabled and disabled if prefixed with “-”. For example, if NeoMutt was compiled using GnuTLS for encrypted communication instead of OpenSSL, `neomutt -v` would contain:

    -openssl +gnutls

### 1.2. URL Syntax

NeoMutt optionally supports the IMAP, POP3 and SMTP protocols which require to access servers using URLs. The canonical syntax for specifying URLs in NeoMutt is (an item enclosed in `[]` means it is optional and may be omitted):

    proto[s]://[username[:password]@]server[:port][/path]

proto is the communication protocol: `imap` for IMAP, `pop` for POP3 and `smtp` for SMTP. If “s” for “secure communication” is appended, NeoMutt will attempt to establish an encrypted communication using SSL or TLS.

Since all protocols supported by NeoMutt support/require authentication, login credentials may be specified in the URL. This has the advantage that multiple IMAP, POP3 or SMTP servers may be specified (which isn't possible using, for example, $imap_user). The username may contain the “@” symbol being used by many mail systems as part of the login name. The special characters “/” (`%2F`), “:” (`%3A`) and “%” (`%25`) have to be URL-encoded in usernames using the `%`-notation.

A password can be given, too but is not recommended if the URL is specified in a configuration file on disk.

If no port number is given, NeoMutt will use the system's default for the given protocol (usually consulting `/etc/services`).

The optional path is only relevant for IMAP and ignored elsewhere.

Example 6.1. URLs

    pops://host/
    imaps://user@host/INBOX/Sent
    smtp://user@host:587/

## 2. SSL/TLS Support

If NeoMutt is compiled with IMAP, POP3 and/or SMTP support, it can also be compiled with support for SSL or TLS using either OpenSSL or GnuTLS (by running the configure script with the --ssl=... option for OpenSSL or --gnutls=... for GnuTLS). NeoMutt can then attempt to encrypt communication with remote servers if these protocols are suffixed with “s” for “secure communication”.

### 2.1. STARTTLS

When non-secure URL protocols `imap://`, `pop://`, and `smtp://` are used, the initial connection to the server will be unencrypted. `STARTTLS` can be used to negotiate an encrypted connection after the initial unencrypted connection and exchange.

Two configuration variables control NeoMutt's behavior with `STARTTLS`. $ssl_starttls will initiate `STARTTLS` if the server advertises support for it. $ssl_force_tls will always try to initiate it, whether the server advertises support or not.

NeoMutt highly recommends setting $ssl_force_tls unless you need to connect to an unencrypted server. It's possible for an attacker to spoof interactions during the initial connection and hide support for `STARTTLS`. The only way to prevent these attacks is by forcing `STARTTLS` with the $ssl_force_tls configuration variable.

### 2.2. Tunnel

When connecting through a $tunnel and $tunnel_is_secure is set(the default), NeoMutt will assume the connection to the server through the pipe is already secured. NeoMutt will ignore $ssl_starttls and $ssl_force_tls, behaving as if TLS has already been negotiated.

When $tunnel_is_secure is unset, NeoMutt will respect the values of $ssl_starttls and $ssl_force_tls. It is highly recommended to set $ssl_force_tls in this case, to force `STARTTLS` negotiation. Note that doing so will prevent connection to an IMAP server configured for preauthentication(`PREAUTH`). If you use this configuration, it is recommended to use a secure tunnel.

## 3. POP3 Support

NeoMutt has POP3 support and has the ability to work with mailboxes located on a remote POP3 server and fetch mail for local browsing.

Remote POP3 servers can be accessed using URLs with the `pop` protocol for unencrypted and `pops` for encrypted communication, see Section 1.2, “URL Syntax” for details.

### 3.1. Remote POP3 mailboxes

Polling for new mail is more expensive over POP3 than locally. For this reason the frequency at which NeoMutt will check for mail remotely can be controlled by the $pop_check_interval variable, which defaults to every 60 seconds.

Due to limitations in POP3, this method doesn't allow for some features such as editing messages, changing their flags or even deleting them. However, using Section 8.1, “Header Caching” and Section 8.2, “Body Caching”, NeoMutt simulates the new/old/read flags as well as flagged and replied. NeoMutt applies some logic on top of remote messages but cannot change them so that modifications of flags are lost when messages are downloaded from the POP3 server (either by NeoMutt or other tools).

    # A sample configuration file for setting up a remote POP3 mailbox

    # If an SMTP password has been set, use this to set the same password for POP3.
    set pop_pass=$smtp_pass

    # Set the POP3 server and user
    set pop_host="pops://user@example.com"

    # Use the remote server as the mailbox
    set folder=$pop_host
    set spool_file=+

### 3.2. Fetching mail from a POP3 server

Another way to access your POP3 mail is the `<fetch-mail>` function (default: G). It allows to connect to $pop_host, fetch all your new mail and place it in the local $spool_file. After this point, NeoMutt runs exactly as if the mail had always been local. The `<fetch-mail>` function will ask whether you want to delete the messages on the remote server, leaving only your local copies.

### Note

If you only need to fetch all messages to a local mailbox, you should consider using a specialized program, such as `fetchmail(1)`, `getmail(1)` or similar.

    # A sample configuration file for fetching mail from a POP3 server

    # The spool file contains the local copies of your messages. If it doesn't
    # exist, initialize it as an empty file.
    set spool_file="/home/user/.mailspool"

    # The POP3 server and user from which to fetch messages
    set pop_host="pops://user@example.com"

## 4. IMAP Support

NeoMutt has IMAP support and has the ability to work with folders located on a remote IMAP server.

You can access the remote inbox by selecting the folder by its URL (see Section 1.2, “URL Syntax” for details) using the `imap` or `imaps` protocol. Alternatively, a pine-compatible notation is also supported, i.e. `{[username@]imapserver[:port][/ssl]}path/to/folder`

Note that not all servers use “/” as the hierarchy separator. NeoMutt should correctly notice which separator is being used by the server and convert paths accordingly.

The IMAP protocol has a subscription feature where the server manages a list of of subscribed folders. To add or remove a folder to the list of subscribed folders use the commands:

`subscribe-to` `imap-folder-uri`
`unsubscribe-from` `imap-folder-uri`

imap-folder-uri must be an IMAP URI, from which the server and the folder is derived, e.g.

    subscribe-to imaps://mail.example.org/inbox

Instead of the above commands you can also use the `<subscribe>` and `<unsubscribe>` functions of the browser (default keys `s` and `u`) to subscribe to or unsubscribe from a folder while browsing the folders on the IMAP server. The browser can be instructed to only display the folders you are subscribed to with the `<toggle-subscribed>` functions. See also the $imap_list_subscribed variable.

Because the list of subscribed folders is managed by the IMAP server, NeoMutt can also ask the server for that list. If $imap_check_subscribed is set, NeoMutt will do that and add those folders to its mailboxes list just as if you had used the mailboxes command on each of them, so that these folders get checked periodically for new mail.

Polling for new mail on an IMAP server can cause noticeable delays. So, you'll want to carefully tune the $mail_check and $timeout variables. Reasonable values are:

    set mail_check=90
    set timeout=15

with relatively good results even over slow modem lines.

### Note

Note that if you are using mbox as the mail store on UW servers prior to v12.250, the server has been reported to disconnect a client if another client selects the same folder.

### 4.1. The IMAP Folder Browser

As of version 1.2, NeoMutt supports browsing mailboxes on an IMAP server. This is mostly the same as the local file browser, with the following differences:

- In lieu of file permissions, NeoMutt displays the string “IMAP”, possibly followed by the symbol “+”, indicating that the entry contains both messages and subfolders. On Cyrus-like servers folders will often contain both messages and subfolders. A mailbox name with a trailing delimiter (usually “/” or “.”) indicates subfolders.

- For the case where an entry can contain both messages and subfolders, the selection key (bound to `enter` by default) will choose to descend into the subfolder view. If you wish to view the messages in that folder, you must use `view-file` instead (bound to `space` by default).

- You can create, delete and rename mailboxes with the `<create-mailbox>`, `<delete-mailbox>`, and `<rename-mailbox>` commands (default bindings: `C`, `d` and `r`, respectively). You may also `<subscribe>` and `<unsubscribe>` to mailboxes (normally these are bound to `s` and `u`, respectively).

### 4.2. Authentication

NeoMutt supports four authentication methods with IMAP servers: SASL, GSSAPI, CRAM-MD5, and LOGIN. There is also support for the pseudo-protocol ANONYMOUS, which allows you to log in to a public IMAP server without having an account. To use ANONYMOUS, simply make your username blank or “anonymous”.

SASL is a special super-authenticator, which selects among several protocols (including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure method available on your host and the server. Using some of these methods (including DIGEST-MD5 and possibly GSSAPI), your entire session will be encrypted and invisible to those teeming network snoops. It is the best option if you have it. To use it, you must have the Cyrus SASL library installed on your system and compile NeoMutt with the --with-sasl flag.

NeoMutt will try whichever methods are compiled in and available on the server, in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.

There are a few variables which control authentication:

- $imap_user – controls the username under which you request authentication on the IMAP server, for all authenticators. This is overridden by an explicit username in the mailbox path (i.e. by using a mailbox name of the form `{user@host}`).

- $imap_pass – a password which you may preset, used by all authentication methods where a password is needed.

- $imap_authenticators – a colon-delimited list of IMAP authentication methods to try, in the order you wish to try them. If specified, this overrides NeoMutt's default (attempt everything, in the order listed above).

## 5. SMTP Support

Besides supporting traditional mail delivery through a sendmail-compatible program, NeoMutt supports delivery through SMTP.

If the configuration variable $smtp_url is set, NeoMutt will contact the given SMTP server to deliver messages; if it is unset, NeoMutt will use the program specified by $sendmail.

For details on the URL syntax, please see Section 1.2, “URL Syntax”.

The built-in SMTP support supports encryption (the `smtps` protocol using SSL or TLS) as well as SMTP authentication using SASL. The authentication mechanisms for SASL are specified in $smtp_authenticators defaulting to an empty list which makes NeoMutt try all available methods from most-secure to least-secure.

## 6. OAUTHBEARER and XOAUTH2 Support

Preliminary OAUTH support for IMAP, POP, and SMTP is provided via external scripts.

At least for Gmail, you can use the `oauth2.py` script from Google's gmail-oauth2-tools: https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py

You'll need to get your own oauth client credentials for Gmail here: https://console.developers.google.com/apis/credentials

Then, you'd use `oauth2.py` with `--generate_oauth2_token` to get a refresh token, and configure NeoMutt with:

    set imap_authenticators="oauthbearer"
    set imap_oauth_refresh_command="/path/to/oauth2.py --quiet --user=[email_address]\
        --client_id=[client_id] --client_secret=[client_secret]\
        --refresh_token=[refresh_token]"

For Office365, you can use the `mutt_oauth2.py` script written by Alexander Perlis: https://github.com/neomutt/neomutt/blob/main/contrib/oauth2/mutt_oauth2.py

You'll need to get your own oauth client credentials by following the script instructions: https://github.com/neomutt/neomutt/blob/main/contrib/oauth2/README.md

    set imap_authenticators="xoauth2"
    set imap_oauth_refresh_command="/path/to/mutt_oauth2.py /path/to/token"

Substitute pop or smtp for imap in the above examples to configure for those. Please note that xoauth2 support has not yet been implemented for pop.

## 7. Managing Multiple Accounts

Usage:

`account-hook` `regex` `command`

If you happen to have accounts on multiple IMAP, POP and/or SMTP servers, you may find managing all the authentication settings inconvenient and error-prone. The account-hook command may help. This hook works like folder-hook but is invoked whenever NeoMutt needs to access a remote mailbox (including inside the folder browser), not just when you open the mailbox. This includes (for example) polling for new mail, storing Fcc messages and saving messages to a folder. As a consequence, account-hook should only be used to set connection-related settings such as passwords or tunnel commands but not settings such as sender address or name (because in general it should be considered unpredictable which account-hook was last used).

Some examples:

    account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
    account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
    account-hook imap://host2/ 'set tunnel="ssh host2 /usr/lib/imapd"'
    account-hook smtp://user@host3/ 'set tunnel="ssh host3 /usr/lib/smtpd"'

To manage multiple accounts with, for example, different values of $record or sender addresses, folder-hook has to be be used together with the mailboxes command.

Example 6.2. Managing multiple accounts

    mailboxes imap://user@host1/INBOX
    folder-hook imap://user@host1/ 'set folder=imap://host1/ ; set record=+INBOX/Sent'
    mailboxes imap://user@host2/INBOX
    folder-hook imap://user@host2/ 'set folder=imap://host2/ ; set record=+INBOX/Sent'

In example Example 6.2, “Managing multiple accounts” the folders are defined using mailboxes so NeoMutt polls them for new mail. Each folder-hook triggers when one mailbox below each IMAP account is opened and sets $folder to the account's root folder. Next, it sets $record to the INBOX/Sent folder below the newly set $folder. Please notice that the value the “+” mailbox shortcut refers to depends on the current value of $folder and therefore has to be set separately per account. Setting other values like $from or $signature is analogous to setting $record.

## 8. Local Caching

NeoMutt contains two types of local caching: (1) the so-called “header caching” and (2) the so-called “body caching” which are both described in this section.

Header caching is optional as it depends on external libraries, body caching is always enabled if NeoMutt is compiled with POP and/or IMAP support as these use it (body caching requires no external library).

### 8.1. Header Caching

NeoMutt provides optional support for caching message headers for the following types of folders: IMAP, POP, Maildir and MH. Header caching greatly speeds up opening large folders because for remote folders, headers usually only need to be downloaded once. For Maildir and MH, reading the headers from a single file is much faster than looking at possibly thousands of single files (since Maildir and MH use one file per message.)

Header caching can be enabled by configuring one of the database backends. One of bdb, gdbm, kyotocabinet, lmdb, qdbm, rocksdb, tdb, tokyocabinet.

If enabled, $header_cache can be used to either point to a file or a directory. If set to point to a file, one database file for all folders will be used (which may result in lower performance), but one file per folder if it points to a directory.

Additionally, $header_cache_backend can be set to specify which backend to use. The list of available backends can be specified at configure time with a set of --with-<backend> options. Currently, the following backends are supported: bdb, gdbm, kyotocabinet, lmdb, qdbm, rocksdb, tdb, tokyocabinet.

Take a look at the benchmark script provided in the following repository: contrib-hcache-benchmark. There you can find a way of finding the storage backend for your needs.

### 8.2. Body Caching

Both cache methods can be combined using the same directory for storage (and for IMAP/POP even provide meaningful file names) which simplifies manual maintenance tasks.

In addition to caching message headers only, NeoMutt can also cache whole message bodies. This results in faster display of messages for POP and IMAP folders because messages usually have to be downloaded only once.

For configuration, the variable $message_cache_dir must point to a directory. There, NeoMutt will create a hierarchy of subdirectories named like the account and mailbox path the cache is for.

### 8.3. Cache Directories

For using both, header and body caching, $header_cache and $message_cache_dir can be safely set to the same value.

In a header or body cache directory, NeoMutt creates a directory hierarchy named like: `proto:user@hostname` where `proto` is either “pop” or “imap.” Within there, for each folder, NeoMutt stores messages in single files and header caches in files with the “.hcache” extension. All files can be removed as needed if the consumed disk space becomes an issue as NeoMutt will silently fetch missing items again. Pathnames are always stored in UTF-8 encoding.

For Maildir and MH, the header cache files are named after the MD5 checksum of the path.

### 8.4. Maintenance

NeoMutt does not (yet) support maintenance features for header cache database files so that files have to be removed in case they grow too big. It depends on the database library used for header caching whether disk space freed by removing messages is re-used.

For body caches, NeoMutt can keep the local cache in sync with the remote mailbox if the $message_cache_clean variable is set. Cleaning means to remove messages from the cache which are no longer present in the mailbox which only happens when other mail clients or instances of NeoMutt using a different body cache location delete messages (NeoMutt itself removes deleted messages from the cache when syncing a mailbox). As cleaning can take a noticeable amount of time, it should not be set in general but only occasionally.

## 9. Account Command Feature

### Populate account credentials via an external command

### 9.1. Support

Since: NeoMutt 2022-05-16

Dependencies: None

### 9.2. Introduction

NeoMutt provides dedicated config variables to specify credentials for network servers. These include `imap_user`, `imap_pass`, `smtp_user`, `smtp_pass`, etc. There are a few downsides to this approach. For one thing, their use encourages storing usernames and passwords in plain text inside a NeoMutt config file. People have come up with solutions to this, including using gpg-encrypted files and populating `my_` variables via external scripts through `source "/path/to/script|"`. However, once the variables are set, the secrets can be inspected with the `set` command. Also, because these config variables are not account-specific, they have been the cause of a proliferation of ways to mimic per-account setups using a combination of convoluted hooks and macros to modify them on folder change or on a keypress.

The goal of this feature is to get rid of most `_user` and `_pass` variables. To do so, we provide a way of specifying an external command that NeoMutt will call to populate account credentials for network servers such as IMAP, POP, or SMTP. The external command is called with a number of arguments indicating the known properties of the account such as the account type and hostname; the external command provides NeoMutt with a list of additional properties such as username and password.

### 9.3. Usage

The variable `account_command` configures an external program to be used to gather account credentials.

    set account_command = "/path/to/my/script.sh"

The program specified will be called by NeoMutt with a number of key-value command line arguments.

- `--hostname val`: the network host name of the service

- `--username val`: the username for the account. This might be specified in the URL itself, e.g., `set folder="imaps://me@example.com@example.com"` or with a dedicated existing variable, e.g. `set imap_user=me@example.com`.

- `--type val`: the type of the account, one of `imap`, `pop`, `smtp`, `nntp`, with an optional trailing `s` if SSL/TLS is required.

The program specified will have to respond by printing to stdout a number of `key: value` lines. NeoMutt currently recognizes the following keys.

- login

- username

- password

Because password can contain any characters, including spaces, we expect lines to match the regex `^([[:alpha:]]+): (.*)$` exactly.

### 9.4. Known Bugs

None

### 9.5. Credits

Pietro Cerutti

## 10. Attach Headers Color Feature

### Color attachment headers using regex, just like mail bodies

### 10.1. Support

Since: NeoMutt 2016-09-10

Dependencies: None

### 10.2. Introduction

This feature allows specifying regexes to color attachment headers just like the mail body would. The headers are the parts colored by the `attachment` color. Coloring them is useful to highlight the results of GPGME's signature checks or simply the mimetype or size of the attachment. Only the part matched by the regex is colored.

### 10.3. Usage

The `attach_headers` color should be used just like the `body` color.

    color attach_headers foreground background pattern

### 10.4. neomuttrc

    # Example NeoMutt config file for the attach-headers-color feature.

    # Color if the attachment is autoviewed
    color   attach_headers     brightgreen     default    "Autoview"
    # Color only the brackets around the headers
    color   attach_headers     brightyellow    default    "^\\[--"
    color   attach_headers     brightyellow    default    "--]$"
    # Color the mime type and the size
    color   attach_headers     green           default    "Type: [a-z]+/[a-z0-9\-]+"
    color   attach_headers     green           default    "Size: [0-9\.]+[KM]"
    # Color GPGME signature checks
    color   attach_headers     brightgreen     default    "Good signature from.*"
    color   attach_headers     brightred       default    "Bad signature from.*"
    color   attach_headers     brightred       default    "BAD signature from.*"
    color   attach_headers     brightred       default    "Note: This key has expired!"
    color   attach_headers     brightmagenta   default    "Problem signature from.*"
    color   attach_headers     brightmagenta   default    "WARNING: This key is not certified with a trusted signature!"
    color   attach_headers     brightmagenta   default    "         There is no indication that the signature belongs to the owner."
    color   attach_headers     brightmagenta   default    "can't handle these multiple signatures"
    color   attach_headers     brightmagenta   default    "signature verification suppressed"
    color   attach_headers     brightmagenta   default    "invalid node with packet of type"

    # vim: syntax=neomuttrc

### 10.5. See Also

- Color command

- Regular Expressions

### 10.6. Known Bugs

None

### 10.7. Credits

Guillaume Brogi

## 11. Command-line Crypto (-C) Feature

### Enable message security in modes that by default don't enable it

### 11.1. Support

Since: NeoMutt 2024-01-21

Dependencies: Gpgme

### 11.2. Introduction

This feature allows enabling message security in modes that don't enable it by default. Those include batch mode, sending a postponed message, and resending a message.

This allows using NeoMutt as a driver for git-send-email(1), to send patches in signed and/or encrypted mail.

### 11.3. Usage

To send an email from a file, enabling cryptographic operations as when sending interactively, simply use the `-C` flag.

    $ neomutt -C -H - < /mail/to/be/sent

### 11.4. neomuttrc

    # Example NeoMutt config file for the cli-crypto feature.

    set pgp_default_key = "1111111111111111111111111111111111111111"
    # Sign all mail
    set crypt_autosign = yes
    # Encrypt mail if all recipients have valid public keys
    set crypt_opportunistic_encrypt = yes
    # Self encrypt mail
    set crypt_self_encrypt = yes

    # vim: syntax=neomuttrc

### 11.5. gitconfig

    # Example .gitconfig config file for the cli-crypto feature.

    [sendemail]
    sendmailcmd = neomutt -C -H - && true

### 11.6. Credits

Alejandro Colomar, Richard Russon, Jenya Sovetkin

## 12. Compose Message Preview Feature

### Show a preview of the message in the Compose Dialog

### 12.1. Support

Since: NeoMutt 2024-12-12

Dependencies: None

### 12.2. Introduction

NeoMutt shows you a preview of the message you are about to send in the compose dialog.

### 12.3. Variables

Table 6.1. Message Preview Variables

Name | Type | Default | Description
--- | --- | --- | ---
`compose_preview_above_attachments` | boolean | `no` | Show the message preview above the attachments list.
`compose_preview_min_rows` | number | `5` | Hide the preview if it has fewer than this number of rows
`compose_show_preview` | boolean | `no` | Enable or disable the message preview feature

### 12.4. Functions

The message preview is controller by the following functions.

Table 6.2. Message Preview Functions

Menus | Function | Description | Default
--- | --- | --- | ---
compose | `<preview-page-down>` | show the next page of the message | `<PageDown>`
compose | `<preview-page-up>` | show the previous page of the message | `<PageUp>`

### 12.5. Limitations

This is a new feature and it's still under development. If you find any problems, or you'd like to help improve it, please let us know.

- Pager displays simple text, no colour or attributes

- Smart text wrapping is not supported

### 12.6. Credits

Dennis Schön

## 13. Compose to Sender Feature

### Send new mail to the sender of the current mail

### 13.1. Support

Since: NeoMutt 2016-10-02

Dependencies: None

### 13.2. Introduction

The compose-to-sender feature adds a new command to start composing a new email to the sender of the current message. This is not a reply, but a new, separate, message.

It works on tagged messages too, sending one email to all of the senders of the tagged messages.

### 13.3. Functions

compose-to-sender adds the following function to NeoMutt. By default, it is not bound to a key.

Table 6.3. compose-to-sender Functions

Menus | Function | Description
--- | --- | ---
index,pager | `<compose-to-sender>` | compose a new email to the sender of the current email

### 13.4. neomuttrc

    # Example NeoMutt config file for the compose-to-sender feature.

    # --------------------------------------------------------------------------
    # FUNCTIONS – shown with an example mapping
    # --------------------------------------------------------------------------
    # Compose a new email (not a reply) to the sender
    bind index,pager @ compose-to-sender

    # vim: syntax=neomuttrc

### 13.5. Known Bugs

None

### 13.6. Credits

Brian Medley, Guillaume Brogi

## 14. Compressed Folders Feature

### Read from/write to compressed mailboxes

### 14.1. Support

Since: NeoMutt 2016-05-30

Dependencies: None

### 14.2. Introduction

The Compressed Folder feature allows NeoMutt to read mailbox files that are compressed. But it isn't limited to compressed files. It works well with encrypted files, too. In fact, if you can create a program/script to convert to and from your format, then NeoMutt can read it.

The feature adds three hooks to NeoMutt: `open-hook`, `close-hook` and `append-hook`. They define commands to: uncompress a file; compress a file; append messages to an already compressed file.

There are some examples of both compressed and encrypted files, later. For now, the documentation will just concentrate on compressed files.

### 14.3. Commands

`open-hook` `regex` `"shell-command"`
`close-hook` `regex` `"shell-command"`
`append-hook` `regex` `"shell-command"`

The shell-command must contain two placeholders for filenames: `%f` and `%t`. These represent “from” and “to” filenames. These placeholders should be placed inside single-quotes to prevent unintended shell expansions.

If you need the exact string “%f” or “%t” in your command, simply double up the “%” character, e.g. “%%f” or “%%t”.

Table 6.4. Not all Hooks are Required

Open | Close | Append | Effect | Useful if
--- | --- | --- | --- | ---
Open | — | — | Folder is readonly | The folder is just a backup
Open | Close | — | Folder is read/write, but the entire folder must be written if anything is changed | Your compression format doesn't support appending
Open | Close | Append | Folder is read/write and emails can be efficiently added to the end | Your compression format supports appending
Open | — | Append | Folder is readonly, but can be appended to | You want to store emails, but never change them

### Note

The command:

- should return a non-zero exit status on failure

- should not delete any files

#### 14.3.1. Read from compressed mailbox

    open-hook regex "shell-command"

If NeoMutt is unable to open a file, it then looks for `open-hook` that matches the filename.

If your compression program doesn't have a well-defined extension, then you can use `.` as the regex.

Example 6.3. Example of `open-hook`

    open-hook '\.gz$' "gzip --stdout --decompress '%f' > '%t'"

- NeoMutt finds a file, “example.gz”, that it can't read

- NeoMutt has an `open-hook` whose regex matches the filename: `\.gz$`

- NeoMutt uses the command `gzip -cd` to create a temporary file that it can read

#### 14.3.2. Write to a compressed mailbox

    close-hook regex "shell-command"

When NeoMutt has finished with a compressed mail folder, it will look for a matching `close-hook` to recompress the file. This hook is optional.

### Note

If the folder has not been modified, the `close-hook` will not be called.

Example 6.4. Example of `close-hook`

    close-hook '\.gz$' "gzip --stdout '%t' > '%f'"

- NeoMutt has finished with a folder, “example.gz”, that it opened with `open-hook`

- The folder has been modified

- NeoMutt has a `close-hook` whose regex matches the filename: `\.gz$`

- NeoMutt uses the command `gzip -c` to create a new compressed file

### Note

The `close-hook` can also include extra options, e.g. compression level: `--best`

#### 14.3.3. Append to a compressed mailbox

    append-hook regex "shell-command"

When NeoMutt wants to append an email to a compressed mail folder, it will look for a matching `append-hook`. This hook is optional.

Using the `append-hook` will save time, but NeoMutt won't be able to determine the type of the mail folder inside the compressed file.

NeoMutt will assume the type to be that of the `$mbox_type` variable. NeoMutt also uses this type for temporary files.

NeoMutt will only use the `append-hook` for existing files. The `close-hook` will be used for empty, or missing files.

### Note

If your command writes to stdout, it is vital that you use `>>` in the “append-hook”. If not, data will be lost.

Example 6.5. Example of `append-hook`

    append-hook '\.gz$' "gzip --stdout '%t' >> '%f'"

- NeoMutt wants to append an email to a folder, “example.gz”, that it opened with `open-hook`

- NeoMutt has an `append-hook` whose regex matches the filename: `\.gz$`

- NeoMutt knows the mailbox type from the `$mbox` variable

- NeoMutt uses the command `gzip -c` to append to an existing compressed file

### Note

The `append-hook` can also include extra options, e.g. compression level: `--best`

#### 14.3.4. Empty Files

NeoMutt assumes that an empty file is not compressed. In this situation, unset $save_empty, so that the compressed file will be removed if you delete all of the messages.

#### 14.3.5. Security

Encrypted files are decrypted into temporary files which are stored in the $tmp_dir directory. This could be a security risk.

### 14.4. neomuttrc

    # Example NeoMutt config file for the compress feature.

    # This feature adds three hooks to NeoMutt which allow it to
    # work with compressed, or encrypted, mailboxes.

    # The hooks are of the form:
    #       open-hook   regex "shell-command"
    #       close-hook  regex "shell-command"
    #       append-hook regex "shell-command"
    # The 'append-hook' is optional.

    # Handler for gzip compressed mailboxes
    open-hook   '\.gz$' "gzip --stdout --decompress '%f' >  '%t'"
    close-hook  '\.gz$' "gzip --stdout              '%t' >  '%f'"
    append-hook '\.gz$' "gzip --stdout              '%t' >> '%f'"
    # Handler for bzip2 compressed mailboxes
    open-hook   '\.bz2$' "bzip2 --stdout --decompress '%f' >  '%t'"
    close-hook  '\.bz2$' "bzip2 --stdout              '%t' >  '%f'"
    append-hook '\.bz2$' "bzip2 --stdout              '%t' >> '%f'"
    # Handler for xz compressed mailboxes
    open-hook   '\.xz$' "xz --stdout --decompress '%f' >  '%t'"
    close-hook  '\.xz$' "xz --stdout              '%t' >  '%f'"
    append-hook '\.xz$' "xz --stdout              '%t' >> '%f'"
    # Handler for pgp encrypted mailboxes
    # PGP does not support appending to an encrypted file
    open-hook   '\.pgp$' "pgp -f < '%f' > '%t'"
    close-hook  '\.pgp$' "pgp -fe YourPgpUserIdOrKeyId < '%t' > '%f'"
    # Handler for gpg encrypted mailboxes
    # gpg does not support appending to an encrypted file
    open-hook   '\.gpg$' "gpg --decrypt < '%f' > '%t'"
    close-hook  '\.gpg$' "gpg --encrypt --recipient YourGpgUserIdOrKeyId < '%t' > '%f'"

    # vim: syntax=neomuttrc

### 14.5. See Also

- Regular Expressions

- $tmp_dir

- $mbox_type

- $save_empty

- folder-hook

### 14.6. Credits

Roland Rosenfeld, Alain Penders, Christoph “Myon” Berg, Evgeni Golov, Richard Russon

## 15. Conditional Dates Feature

### Use rules to choose date format

### 15.1. Support

Since: NeoMutt 2016-03-07

Dependencies:

  nested-if feature

### 15.2. Introduction

The “Conditional Dates” feature allows you to construct $index_format expressions based on the age of the email.

NeoMutt's default `$index_format` displays email dates in the form: abbreviated-month day-of-month – “Jan 14”.

The format is configurable but only per-mailbox. This feature allows you to configure the display depending on the age of the email.

Table 6.5. Potential Formatting Scheme

Email Sent | Format | Example
--- | --- | ---
Today | `%H:%M` | 13:23
This Month | `%a %d` | Thu 17
This Year | `%b %d` | Dec 10
Older than 1 Year | `%m/%y` | 06/14

For an explanation of the date formatting strings, see `strftime(3).`

By carefully picking your formats, the dates can remain unambiguous and compact.

NeoMutt's conditional format strings have the form: (whitespace introduced for clarity)

    %< TEST ? TRUE & FALSE >

The examples below use the test “%[” – the date of the message in the local timezone. They will also work with “%(” – the local time that the message arrived.

The date tests are of the form:

    %<[nX? TRUE & FALSE >

- “n” is an optional count (defaults to 1 if missing)

- “X” is the time period

Table 6.6. Date Formatting Codes

Letter | Time Period
--- | ---
y | Years
m | Months
w | Weeks
d | Days
H | Hours
M | Minutes

Table 6.7. Example Date Tests

Test | Meaning
--- | ---
`%[y` | This year
`%[1y` | This year
`%[6m` | In the last 6 months
`%[w` | This week
`%[d` | Today
`%[4H` | In the last 4 hours

#### 15.2.1. Example 1

We start with a one-condition test.

Table 6.8. Example 1

Test | Date Range | Format String | Example
--- | --- | --- | ---
`%[1m` | This month | `%[%b %d]` | Dec 10
| Older | `%[%Y-%m-%d]` | 2015-04-23

The $index_format string would contain:

    %<[1m?%[%b %d]&%[%Y-%m-%d]>

Reparsed a little, for clarity, you can see the test condition and the two format strings.

    %<[1m?        &           >

          %[%b %d] %[%Y-%m-%d]

#### 15.2.2. Example 2

This example contains three test conditions and four date formats.

Table 6.9. Example 2

Test | Date Range | Format String | Example
--- | --- | --- | ---
`%[d` | Today | `%[%H:%M ]` | 12:34
`%[m` | This month | `%[%a %d]` | Thu 12
`%[y` | This year | `%[%b %d]` | Dec 10
| Older | `%[%m/%y ]` | 06/15

The $index_format string would contain:

    %<[y?%<[m?%<[d?%[%H:%M ]&%[%a %d]>&%[%b %d]>&%[%m/%y ]>

Reparsed a little, for clarity, you can see the test conditions and the four format strings.

    %<[y?                                       &%[%m/%y ]>  Older
         %<[m?                        &%[%b %d]>             This year
              %<[d?         &%[%a %d]>                       This month
                   %[%H:%M ]                                 Today

This a another view of the same example, with some whitespace for clarity.

    %<[y? %<[m? %<[d? AAA & BBB > & CCC > & DDD >

AAA = %[%H:%M ] BBB = %[%a %d] CCC = %[%b %d] DDD = %[%m/%y ]

### 15.3. Variables

The “Conditional Dates” feature doesn't have any config of its own. It modifies the behavior of the format strings.

### 15.4. neomuttrc

    # Example NeoMutt config file for the cond-date feature.

    #
    # The default index_format is:
    #       '%4C %Z %{%b %d} %-15.15L (%<l?%4l&%4c>) %s'
    #
    # We replace the date field '%{%b %d}', giving:
    set index_format='%4C %Z %<[y?%<[m?%<[d?%[%H:%M ]&%[%a %d]>&%[%b %d]>&%[%m/%y ]> %-15.15L (%<l?%4l&%4c>) %s'
    # Test  Date Range  Format String  Example
    # --------------------------------------------
    # %[d   Today       %[%H:%M ]      12:34
    # %[m   This month  %[%a %d]       Thu 12
    # %[y   This year   %[%b %d]       Dec 10
    #  —    Older       %[%m/%y ]      06/15

    # vim: syntax=neomuttrc

### 15.5. See Also

- $index_format

- nested-if feature

- `strftime(3)`

### 15.6. Known Bugs

Date parsing doesn't quite do what you expect. “1w” doesn't mean the “in the last 7 days”, but “this week”. This doesn't match the normal NeoMutt behavior: for example `~d>1w` means emails dated in the last 7 days.

### 15.7. Credits

Aaron Schrab, Eric Davis, Richard Russon

## 16. Encrypt-to-Self Feature

### Save a self-encrypted copy of emails

### 16.1. Support

Since: NeoMutt 2016-07-23

Dependencies: None

### 16.2. Introduction

Once you encrypt an email to someone you cannot read it. This is good for security, but bad for record-keeping. If you wanted to keep a copy of an encrypted email you could set $fcc_clear.

A better option is to enable $smime_self_encrypt, then set $smime_default_key to your personal S/MIME key id.

    set smime_self_encrypt = yes
    set smime_default_key  = bb345e23.0

Or, if you use PGP, $pgp_self_encrypt, then set $pgp_default_key to your personal PGP key id.

    set pgp_self_encrypt = yes
    set pgp_default_key  = A4AF18C5582473BD35A1E9CE78BB3D480042198E

If you have different key for signing, then you can set $pgp_sign_as or $smime_sign_as respectively.

### 16.3. Variables

Table 6.10. encrypt-self Variables

Name | Type | Default
--- | --- | ---
`pgp_default_key` | string | (empty)
`pgp_self_encrypt` | boolean | `yes`
`pgp_sign_as` | string | (empty)
`smime_default_key` | string | (empty)
`smime_self_encrypt` | boolean | `yes`
`smime_sign_as` | string | (empty)

### 16.4. neomuttrc

    # Example NeoMutt config file for the encrypt-to-self feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    # Save a copy of outgoing email, encrypted to yourself
    set pgp_self_encrypt = "yes"
    set pgp_default_key = "PGP-KEY"
    # set pgp_sign_as = "PGP-SIGNING-KEY"

    # Save a copy of outgoing email, encrypted to yourself
    set smime_self_encrypt = "yes"
    set smime_default_key = "SMIME-KEY"
    # set smime_sign_as = "SMIME-SIGNING-KEY"

    # vim: syntax=neomuttrc

### 16.5. Known Bugs

None

### 16.6. Credits

Omen Wild, Richard Russon, Guillaume Brogi

## 17. Encryption information block

### Show a block of encryption information about a message

### 17.1. Support

Since: NeoMutt 2024-04-10

Dependencies: Gpgme

### 17.2. Introduction

This feature shows a block of information that provides information about an encrypted message; mainly about its recipients. Here is an example of such a block:

    [-- Begin encryption information --]
    Recipient: RSA key, ID 00C14A7DBBDD521C
    Recipient: RSA key, ID 0000000000000000
    [-- End encryption information --]

### 17.3. Usage

It's enabled by default. The variable to control it is `crypt_encryption_info`.

### 17.4. Credits

Alejandro Colomar, Richard Russon, наб

## 18. Fmemopen Feature

### Replace some temporary files with memory buffers

### 18.1. Support

Since: NeoMutt 2016-03-07

Dependencies:

  `open_memstream()`, `fmemopen()` from glibc

This feature can be enabled by running `configure` with the option `--fmemopen`

### 18.2. Introduction

The “fmemopen” feature speeds up some searches.

This feature changes a few places where NeoMutt creates temporary files. It replaces them with in-memory buffers. This should improve the performance when searching the header or body using the $thorough_search option.

There are no user-configurable parts.

This feature depends on `open_memstream()` and `fmemopen()`. They are provided by glibc. Without them, NeoMutt will simply create temporary files.

### 18.3. See Also

- Compile-Time Features

- `fmemopen(3)`

### 18.4. Known Bugs

debian bug 834408

### 18.5. Credits

Julius Plenz, Richard Russon

## 19. Forgotten Attachment Feature

### Alert user when (s)he forgets to attach a file to an outgoing email.

### 19.1. Support

Since: NeoMutt 2016-09-10

Dependencies: None

### 19.2. Introduction

The “forgotten-attachment” feature provides a new setting for NeoMutt that alerts the user if the message body contains a certain keyword but there are no attachments added. This is meant to ensure that the user does not forget to attach a file after promising to do so in the mail. The attachment keyword will not be scanned in text matched by $quote_regex.

### 19.3. Variables

Table 6.11. forgotten-attachment Variables

Name | Type | Default
--- | --- | ---
`abort_noattach_regex` | regular expression | `\\<(attach|attached|attachments?)\\>`
`abort_noattach` | quadoption | `no`

### 19.4. neomuttrc

    # Example NeoMutt config file for the forgotten-attachment feature.

    # The 'forgotten-attachment' feature provides a new setting for NeoMutt that
    # alerts the user if the message body contains a certain regular expression but there are
    # no attachments added. This is meant to ensure that the user does not forget
    # to attach a file after promising to do so in the mail.

    # Ask if the user wishes to abort sending if $abort_noattach_regex is found in the
    # body, but no attachments have been added
    # It can be set to:
    #    "yes"     : always abort
    #    "ask-yes" : ask whether to abort
    #    "no"      : send the mail
    set abort_noattach = no
    # Search for the following regular expression in the body of the email
    # English: attach, attached, attachment, attachments
    set abort_noattach_regex = "\\<attach(|ed|ments?)\\>"
    # Nederlands:
    # set abort_noattach_regex = "\\<(bijvoegen|bijgevoegd|bijlage|bijlagen)\\>"
    # Deutsch:
    # set abort_noattach_regex = "\\<(anhängen|angehängt|anhang|anhänge|hängt an)\\>"
    # Français:
    # set abort_noattach_regex = "\\<(attaché|attachés|attache|attachons|joint|jointe|joints|jointes|joins|joignons)\\>"

    # vim: syntax=neomuttrc

### 19.5. See Also

- The Attachment Menu

- The Attachment Menu key mappings

### 19.6. Known Bugs

None

### 19.7. Credits

Darshit Shah, Richard Russon, Johannes Weißl, Steven Ragnarök

## 20. Global Hooks

### Define actions to run globally within NeoMutt

### 20.1. Introduction

These hooks are called when global events take place in NeoMutt.

Run a command...

- timeout-hook – periodically

- startup-hook – when NeoMutt starts up, before opening the first mailbox

- shutdown-hook – NeoMutt shuts down, before closing the last mailbox

The commands are NeoMutt commands. If you want to run an external shell command, you need to run them like this:

    startup-hook 'echo `action.sh ARGS`'

The single quotes prevent the backticks from being expanded. The `echo` command prevents an empty command error.

#### 20.1.1. Timeout Hook

##### Run a command periodically

Since: NeoMutt 2016-08-08

This feature implements a new hook that is called periodically when NeoMutt checks for new mail. This hook is called every `$timeout` seconds.

#### 20.1.2. Startup Hook

##### Run a command when NeoMutt starts up, before opening the first mailbox

Since: NeoMutt 2016-11-25

This feature implements a new hook that is called when NeoMutt first starts up, but before opening the first mailbox. This is most likely to be useful to users of notmuch.

#### 20.1.3. Shutdown Hook

##### Run a command when NeoMutt shuts down, before closing the last mailbox

Since: NeoMutt 2016-11-25

This feature implements a hook that is called when NeoMutt shuts down, but before closing the last mailbox. This is most likely to be useful to users of notmuch.

### 20.2. Commands

`timeout-hook` `command`

`startup-hook` `command`

`shutdown-hook` `command`

### 20.3. neomuttrc

    # Example NeoMutt config file for the global hooks feature.

    # --------------------------------------------------------------------------
    # COMMANDS – shown with an example argument
    # --------------------------------------------------------------------------
    # After $timeout seconds of inactivity, run this NeoMutt command
    timeout-hook 'exec sync-mailbox'
    # When NeoMutt first loads, run this NeoMutt command
    startup-hook 'exec sync-mailbox'
    # When NeoMutt quits, run this NeoMutt command
    shutdown-hook 'exec sync-mailbox'

    # vim: syntax=neomuttrc

### 20.4. See Also

- $timeout

### 20.5. Known Bugs

None

### 20.6. Credits

Armin Wolfermann, Richard Russon, Thomas Adam

## 21. Header Cache Compression Feature

### Options for compressing the header cache files

### 21.1. Support

Since: NeoMutt 2020-02-22

Dependencies: header cache

### 21.2. Introduction

The Header Cache Compression Feature can be used for speeding up the loading of large mailboxes. Also the space used on disk can be shrunk by about 50% - depending on the compression method being used.

The implementation sits on top of the header caching functions. So the header cache compression can be used together with all available database backends.

### 21.3. Variables

Table 6.12. Header Cache Compression Variables

Name | Type | Default
--- | --- | ---
`header_cache_compress_method` | string | (empty)
`header_cache_compress_level` | number | `1`

The `header_cache_compress_method` can be (empty) - which means, that no header cache compression should be used. But when set to lz4, zlib or zstd - then the compression is turned on.

The `header_cache_compress_level` defines the compression level, which should be used together with the selected `header_cache_compress_method`. Here is an overview of the possible settings:

Table 6.13. Header Cache Compression Methods and it's Levels

Method Name | Min | Max
--- | --- | ---
`lz4` | 1 | 12
`zlib` | 1 | 9
`zstd` | 1 | 22

### 21.4. neomuttrc

    # Example NeoMutt config file for the header cache compression feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    set header_cache_compress_level = 1
    set header_cache_compress_method = ""

    # vim: syntax=neomuttrc

### 21.5. Known Bugs

None

### 21.6. Credits

Tino Reichardt

## 22. Ifdef Feature

### Conditional config options

### 22.1. Support

Since: NeoMutt 2016-03-07

Dependencies: None

### 22.2. Introduction

The “ifdef” feature introduces three new commands to NeoMutt and allows you to share one config file between versions of NeoMutt that may have different features compiled in.

    ifdef  symbol "config-command [args...]"  # If a symbol is defined
    ifndef symbol "config-command [args...]"  # If a symbol is not defined
    finish                                    # Finish reading the current file

Table 6.14. ifdef Symbols

Example Symbol | Description
--- | ---
`sidebar_format` | Config variable
`status-color`, `imap` | Compiled-in feature
`pgp-menu`, `group-related` | Function
`index-format-hook`, `tag-transforms` | Command
`indicator`, `sidebar_new` | Colour
`my_var` | My variable
`lmdb`, `tokyocabinet` | Store (database)
`HOME`, `COLUMNS` | Environment variable

A list of compile-time symbols can be seen in the output of the command

    neomutt -v

(in the “Compile options” section).

`finish` is particularly useful when combined with `ifndef`. e.g.

    # Sidebar config file
    ifndef sidebar finish

### 22.3. Commands

`ifdef` `symbol` `"config-command [args...]"`
`ifndef` `symbol` `"config-command [args...]"`
`finish`

### 22.4. neomuttrc

    # Example NeoMutt config file for the ifdef feature.

    # This feature introduces three useful commands which allow you to share
    # one config file between versions of NeoMutt that may have different
    # features compiled in.

    #   ifdef  symbol "config-command [args...]"
    #   ifndef symbol "config-command [args...]"
    #   finish
    # The 'ifdef' command tests whether NeoMutt understands the name of
    # a variable, environment variable, function, command or compile-time symbol.

    # If it does, then it executes a config command.

    # The 'ifndef' command tests whether a symbol does NOT exist.

    # The 'finish' command tells NeoMutt to stop reading current config file.

    # If the 'trash' variable exists, set it.
    ifdef trash 'set trash=~/Mail/trash'
    # If the 'PS1' environment variable exists, source config file.
    ifdef PS1 'source .neomutt/interactive.rc'
    # If the 'tag-pattern' function exists, bind a key to it.
    ifdef tag-pattern 'bind index <F6> tag-pattern'
    # If the 'imap-fetch-mail' command exists, read my IMAP config.
    ifdef imap-fetch-mail 'source ~/.neomutt/imap.rc'
    # If the compile-time symbol 'sidebar' does not exist, then
    # stop reading the current config file.
    ifndef sidebar finish

    # vim: syntax=neomuttrc

### 22.5. Known Bugs

None

### 22.6. Credits

Cedric Duval, Matteo F. Vescovi, Richard Russon

## 23. Index Color Feature

### Custom rules for theming the email index

### 23.1. Support

Since: NeoMutt 2016-03-07

Dependencies:

  status-color feature

### 23.2. Introduction

The “index-color” feature allows you to specify colors for individual parts of the email index. e.g. Subject, Author, Flags.

First choose which part of the index you'd like to color. Then, if needed, pick a pattern to match.

Note: The pattern does not have to refer to the object you wish to color. e.g.

    color index_author red default "~sneomutt"

The author appears red when the subject (~s) contains “neomutt”.

### 23.3. Colors

All the colors default to `default`, i.e. unset.

The index objects can be themed using the `color` command and an optional pattern. A missing pattern is equivalent to a match-all `.*` pattern.

    color index-object foreground background [pattern]

Table 6.15. Index Colors

Object | Highlights
--- | ---
`index` | Entire index line
`index_author` | Author name, %A %a %F %L %n
`index_collapsed` | Number of messages in a collapsed thread, %M
`index_date` | Date field
`index_flags` | Message flags, %S %Z
`index_label` | Message label, %y %Y
`index_number` | Message number, %C
`index_size` | Message size, %c %cr %l
`index_subject` | Subject, %s
`index_tag` | Message tags, `%G`
`index_tags` | Transformed message tags, `%g` `%J`

### 23.4. neomuttrc

    # Example NeoMutt config file for the index-color feature.

    # Entire index line
    color index white black '.*'
    # Author name, %A %a %F %L %n
    # Give the author column a dark grey background
    color index_author default color234 '.*'
    # Highlight a particular from (~f)
    color index_author brightyellow color234 '~fRay Charles'
    # Message flags, %S %Z
    # Highlight the flags for flagged (~F) emails
    color index_flags default red '~F'
    # Subject, %s
    # Look for a particular subject (~s)
    color index_subject brightcyan default '~s\(closes #[0-9]+\)'
    # Number of messages in a collapsed thread, %M
    color index_collapsed default brightblue
    # Date field
    color index_date green default
    # Message label, %y %Y
    color index_label default brightgreen
    # Message number, %C
    color index_number red default
    # Message size, %c %cr %l
    color index_size cyan default

    # vim: syntax=neomuttrc

### 23.5. See Also

- Regular Expressions

- Patterns

- $index_format

- Color command

- Status-Color feature

### 23.6. Known Bugs

None

### 23.7. Credits

Christian Aichinger, Christoph “Myon” Berg, Elimar Riesebieter, Eric Davis, Vladimir Marek, Richard Russon

## 24. Initials Expando Feature

### Expando for author's initials

### 24.1. Support

Since: NeoMutt 2016-03-07

Dependencies: None

### 24.2. Introduction

The “initials” feature adds an expando (%I) for an author's initials.

The index panel displays a list of emails. Its layout is controlled by the $index_format variable. Using this expando saves space in the index panel. This can be useful if you are regularly working with a small set of people.

### 24.3. Variables

This feature has no config of its own. It adds an expando which can be used in the $index_format variable.

### 24.4. neomuttrc

    # Example NeoMutt config file for the initials feature.

    # The 'initials' feature has no config of its own.

    # It adds an expando for an author's initials,
    # which can be used in the 'index_format' variable.

    # The default 'index_format' is:
    set index_format='%4C %Z %{%b %d} %-15.15L (%<l?%4l&%4c>) %s'
    # Where %L represents the author/recipient
    # This might look like:
    #       1   + Nov 17 David Bowie   Changesbowie    ( 689)
    #       2   ! Nov 17 Stevie Nicks  Rumours         ( 555)
    #       3   + Nov 16 Jimi Hendrix  Voodoo Child    ( 263)
    #       4   + Nov 16 Debbie Harry  Parallel Lines  ( 540)
    # Using the %I expando:
    set index_format='%4C %Z %{%b %d} %I (%<l?%4l&%4c>) %s'
    # This might look like:
    #       1   + Nov 17 DB Changesbowie    ( 689)
    #       2   ! Nov 17 SN Rumours         ( 555)
    #       3   + Nov 16 JH Voodoo Child    ( 263)
    #       4   + Nov 16 DH Parallel Lines  ( 540)

    # vim: syntax=neomuttrc

### 24.5. See Also

- $index_format

- index-color feature

- folder-hook

### 24.6. Known Bugs

None

### 24.7. Credits

Vsevolod Volkov, Richard Russon

## 25. Kyoto Cabinet Feature

### Kyoto Cabinet backend for the header cache

### 25.1. Support

Since: NeoMutt 2016-10-02

Dependencies:

  Kyoto Cabinet libraries

To check if NeoMutt supports Kyoto Cabinet, look for

- “kyoto” in the NeoMutt version.

- “+hcache” in the compile options

- “hcache backend: kyotocabinet” in the NeoMutt version

### 25.2. Introduction

This feature adds support for using Kyoto Cabinet, the successor to Tokyo Cabinet, as a storage backend for NeoMutt's header cache (hcache). It is enabled at configure time with the --with-kyotocabinet=<path> switch.

### 25.3. See Also

- Local Caching

- Kyoto Cabinet

### 25.4. Known Bugs

None

### 25.5. Credits

Clemens Lang

## 26. Limit Current Thread Feature

### Focus on one Email Thread

### 26.1. Support

Since: NeoMutt 2016-03-28

Dependencies: None

### 26.2. Introduction

This feature adds a new way of using the Limit Command. The `<limit-current-thread>` function restricts the view to just the current thread. Setting the limit (the `l` key) to “all” will restore the full email list.

### 26.3. Functions

Limit-current-thread adds the following function to NeoMutt. By default, it is not bound to a key.

Table 6.16. Limit-Current-Thread Functions

Menus | Function | Description
--- | --- | ---
index | `<limit-current-thread>` | Limit view to current thread

### 26.4. neomuttrc

    # Example NeoMutt config file for the limit-current-thread feature.

    # Limit view to current thread
    bind index <esc>L limit-current-thread

    # vim: syntax=neomuttrc

### 26.5. Known Bugs

None

### 26.6. Credits

David Sterba, Richard Russon

## 27. LMDB Feature

### LMDB backend for the header cache

### 27.1. Support

Since: NeoMutt 2016-07-23

Dependencies: None

### 27.2. Introduction

This feature adds support for using LMDB as a storage backend for NeoMutt's header cache (hcache). It is enabled at configure time with the --with-lmdb=<path> switch.

### Note

It is not recommended to store the lmdb database on a shared drive.

### 27.3. See Also

- Local Caching

### 27.4. Known Bugs

None

### 27.5. Credits

Pietro Cerutti, Jan-Piet Mens, Clemens Lang

## 28. Multiple FCC Feature

### Save multiple copies of outgoing mail

### 28.1. Support

Since: NeoMutt 2016-08-08

Dependencies: None

### 28.2. Introduction

This feature allows the user to save outgoing emails in multiple folders.

Folders should be listed separated by commas, but no spaces.

The “fcc” field of an email can be set in two ways:

- The <edit-fcc> command in the compose menu (default key: “f”)

- Creating a `fcc-hook` in your `.neomuttrc`

### 28.3. See Also

- $record

- fcc-hook

### 28.4. Known Bugs

None

### 28.5. Credits

Omen Wild, Richard Russon

## 29. Nested If Feature

### Allow complex nested conditions in format strings

### 29.1. Support

Since: NeoMutt 2016-03-07

Dependencies: None

### 29.2. Introduction

NeoMutt's format strings can contain embedded if-then-else conditions. They are of the form:

    %?VAR?TRUE&FALSE?

If the variable “VAR” has a value greater than zero, print the “TRUE” string, otherwise print the “FALSE” string.

e.g. `%?S?Size: %S&Empty?`

Which can be read as:

if (%S > 0) { print "Size: %S" } else { print "Empty" }

These conditions are useful, but in NeoMutt they cannot be nested within one another. This feature uses the notation `%<VAR?TRUE&FALSE>` and allows them to be nested.

The `%<...>` notation was used to format the current local time. but that's not really very useful since NeoMutt has no means of refreshing the screen periodically.

A simple nested condition might be: (Some whitespace has been introduced for clarity)

    %<x? %<y? XY & X > & %<y? Y & NONE > >  Conditions
         %<y? XY & X >                      x>0
              XY                            x>0,y>0
                   X                        x>0,y=0

    %<x? %<y? XY & X > & %<y? Y & NONE > >  Conditions
                         %<y? Y & NONE >    x=0
                              Y             x=0,y>0
                                  NONE      x=0,y=0

Equivalent to:

if (x > 0) {
if (y > 0) {
print 'XY'
} else {
print 'X'
}
} else {
if (y > 0) {
print 'Y'
} else {
print 'NONE'
}
}

Examples:

    set index_format='%4C %Z %{%b %d} %-25.25n %s%> %<M?%M Msgs &%<l?%l Lines&%c Bytes>>'

if a thread is folded display the number of messages (%M)
else if we know how many lines in the message display lines in message (%l)
else display the size of the message in bytes (%c)

    set index_format='%4C %Z %{%b %d} %-25.25n %<M?[%M] %s&%s%* %<l?%l&%c>>'

if a thread is folded display the number of messages (%M) and the subject (%s)
else if we know how many lines are in the message display subject (%s) and the lines in message (%l)
else display the subject (%s) and the size of the message in bytes (%c)

### Note

If you wish to use angle brackets `< >` in a nested condition, then it's necessary to escape them, e.g.

    set index_format='%<M?\<%M\>&%s>'

### 29.3. Variables

The “nested-if” feature doesn't have any config of its own. It modifies the behavior of the format strings.

### 29.4. neomuttrc

    # Example NeoMutt config file for the nested-if feature.

    # This feature uses the format: '%<VAR?TRUE&FALSE>' for conditional
    # format strings that can be nested.

    # Example 1
    # if a thread is folded
    #       display the number of messages (%M)
    # else if we know how many lines in the message
    #       display lines in message (%l)
    # else display the size of the message in bytes (%c)
    set index_format='%4C %Z %{%b %d} %-25.25n %s%> %<M?%M Msgs &%<l?%l Lines&%c Bytes>>'

    # Example 2
    # if a thread is folded
    #       display the number of messages (%M)
    #       display the subject (%s)
    # else if we know how many lines in the message
    #       display lines in message (%l)
    # else
    #       display the size of the message in bytes (%c)
    set index_format='%4C %Z %{%b %d} %-25.25n %<M?[%M] %s&%s%* %<l?%l&%c>>'

    # vim: syntax=neomuttrc

### 29.5. See Also

- cond-date feature

- $index_format

- $status_format

### 29.6. Known Bugs

This feature is hard to understand

### 29.7. Credits

David Champion, Richard Russon, Aleksa Sarai

## 30. New Mail Feature

### Execute a command upon the receipt of new mail.

### 30.1. Support

Since: NeoMutt 2016-07-23

Dependencies: None

### 30.2. Introduction

This feature enables the new_mail_command setting, which can be used to execute a custom script (e.g. a notification handler) upon receiving a new mail.

The command string can contain expandos, such as `%n` for the number of new messages. For a complete list, see: $status_format.

### Note

When the notification is sent, the folder of the new mail is no longer known. This is a limitation of NeoMutt. The `%f` expando will show the open folder.

When using Maildir local mailboxes, you must set $check_new config variable for this feature to work.

For example in Linux you can use (most distributions already provide notify-send):

    set new_mail_command="notify-send --icon='/home/santiago/Pictures/neomutt.png' \
      'New Email' '%n new messages, %u unread.' &"

And in OS X you will need to install a command line interface for Notification Center, for example terminal-notifier:

    set new_mail_command="terminal-notifier -title '%v' -subtitle 'New Mail' \
      -message '%n new messages, %u unread.' -activate 'com.apple.Terminal'"

### 30.3. Variables

Table 6.17. New Mail Command Variables

Name | Type | Default
--- | --- | ---
`new_mail_command` | string | (empty)

### 30.4. neomuttrc

    # Example NeoMutt config file for the new-mail feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    # Set the command you want NeoMutt to execute upon the receipt of a new email
    set new_mail_command = ""
    # Linux example:
    # set new_mail_command="notify-send --icon='/home/santiago/Pictures/neomutt.png' \
    #   'New Email in %f' '%n new messages, %u unread.' &"
    # OS X example:
    # set new_mail_command="terminal-notifier -title '%v' -subtitle 'New Mail in %f' \
    #   -message '%n new messages, %u unread.' -activate 'com.apple.Terminal'"
    # --------------------------------------------------------------------------

    # vim: syntax=neomuttrc

### 30.5. See Also

- folder-hook

### 30.6. Known Bugs

None

### 30.7. Credits

Yoshiki Vazquez-Baeza, Santiago Torres-Arias, Richard Russon

## 31. NNTP Feature

### Talk to a Usenet news server

### 31.1. Support

Since: NeoMutt 2016-05-30

Dependencies: None

### 31.2. Introduction

Reading news via NNTP

NeoMutt can read from a news server using NNTP.

The default news server can be obtained from the `$NNTPSERVER` environment variable or from the `/etc/nntpserver` file. Like in other news readers, information about the subscribed newsgroups is saved in the file specified by the $newsrc variable. You can open a newsgroup with the function `<change-newsgroup>`

When browsing the list of newsgroups on the server the function `<subscribe>` can be used to tell NeoMutt the groups of interest to you. This list is stored in the $newsrc file, so NeoMutt remembers it across invocations (see also $save_unsubscribed). With the `<unsubscribe>` function a group can be deleted from that list. You can also specify the list of interesting groups with the mailboxes command in your config file.

When checking for new messages, NeoMutt only polls the subscribed newsgroups.

The variable $news_cache_dir can be used to point to a directory. NeoMutt will create a hierarchy of subdirectories named like the account and newsgroup the cache is for. The hierarchy is also used to store header cache if NeoMutt was compiled with header cache support.

### 31.3. Variables

Table 6.18. NNTP Variables

Name | Type | Default
--- | --- | ---
`ask_followup_to` | boolean | `no`
`ask_x_comment_to` | boolean | `no`
`catchup_newsgroup` | quad | `ask-yes`
`followup_to_poster` | quad | `ask-yes`
`group_index_format` | string | `%4C %M%N %5s %-45.45f %d`
`inews` | string | (empty)
`newsgroups_charset` | string | `utf-8`
`newsrc` | string | `~/.newsrc`
`news_cache_dir` | string | `~/.neomutt`
`news_server` | string | (empty)
`nntp_authenticators` | string | (empty)
`nntp_context` | number | `1000`
`nntp_listgroup` | boolean | `yes`
`nntp_load_description` | boolean | `yes`
`nntp_pass` | string | (empty)
`nntp_poll` | number | `60`
`nntp_user` | string | (empty)
`post_moderated` | quad | `ask-yes`
`save_unsubscribed` | boolean | `no`
`show_new_news` | boolean | `yes`
`show_only_unread` | boolean | `no`
`x_comment_to` | boolean | `no`

### 31.4. Functions

NNTP adds the following functions to NeoMutt. By default, none of them are bound to keys.

Table 6.19. NNTP Functions

Menus | Function | Description
--- | --- | ---
browser,index | `<catchup>` | mark all articles in newsgroup as read
index,pager | `<change-newsgroup>` | open a different newsgroup
compose | `<edit-followup-to>` | edit the Followup-To field
compose | `<edit-newsgroups>` | edit the newsgroups list
compose | `<edit-x-comment-to>` | edit the X-Comment-To field
attach,index,pager | `<followup-message>` | followup to newsgroup
index,pager | `<post-message>` | post message to newsgroup
browser | `<reload-active>` | load list of all newsgroups from NNTP server
browser | `<subscribe>` | subscribe to current mbox (IMAP/NNTP only)
browser | `<subscribe-pattern>` | subscribe to newsgroups matching a pattern
browser | `<uncatchup>` | mark all articles in newsgroup as unread
browser | `<unsubscribe>` | unsubscribe from current mbox (IMAP/NNTP only)
browser | `<unsubscribe-pattern>` | unsubscribe from newsgroups matching a pattern
index,pager | `<change-newsgroup-readonly>` | open a different newsgroup in read only mode
attach,index,pager | `<forward-to-group>` | forward to newsgroup
index | `<get-children>` | get all children of the current message
index | `<get-parent>` | get parent of the current message
index | `<reconstruct-thread>` | reconstruct thread containing current message
index | `<get-message>` | get message with Message-Id

### 31.5. neomuttrc

    # Example NeoMutt config file for the nntp feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    set ask_followup_to = no
    set ask_x_comment_to = no
    set catchup_newsgroup = ask-yes
    set followup_to_poster = ask-yes
    set group_index_format = '%4C %M%N %5s  %-45.45f %d'
    set inews = ''
    set newsgroups_charset = utf-8
    set newsrc = '~/.newsrc'
    set news_cache_dir = '~/.neomutt'
    set news_server = ''
    set nntp_authenticators = ''
    set nntp_context = 1000
    set nntp_listgroup = yes
    set nntp_load_description = yes
    set nntp_pass = ''
    set nntp_poll = 60
    set nntp_user = ''
    set post_moderated = ask-yes
    set save_unsubscribed = no
    set show_new_news = yes
    set show_only_unread = no
    set x_comment_to = no
    # --------------------------------------------------------------------------
    # FUNCTIONS – shown with an example mapping
    # --------------------------------------------------------------------------
    # mark all articles in newsgroup as read
    bind browser,index y catchup
    # open a different newsgroup
    bind index,pager i change-newsgroup
    # edit the Followup-To field
    bind compose o edit-followup-to
    # edit the newsgroups list
    bind compose N edit-newsgroups
    # edit the X-Comment-To field
    bind compose x edit-x-comment-to
    # followup to newsgroup
    bind attach,index,pager F followup-message
    # post message to newsgroup
    bind index,pager P post-message
    # load list of all newsgroups from NNTP server
    bind browser g reload-active
    # subscribe to current mbox (IMAP/NNTP only)
    bind browser s subscribe
    # subscribe to newsgroups matching a pattern
    bind browser S subscribe-pattern
    # mark all articles in newsgroup as unread
    bind browser Y uncatchup
    # unsubscribe from current mbox (IMAP/NNTP only)
    bind browser u unsubscribe
    # unsubscribe from newsgroups matching a pattern
    bind browser U unsubscribe-pattern
    # open a different newsgroup in read only mode
    bind index,pager \ei change-newsgroup-readonly
    # forward to newsgroup
    bind attach,index,pager \eF forward-to-group
    # get all children of the current message
    # bind index ??? get-children
    # get parent of the current message
    bind index \eG get-parent
    # reconstruct thread containing current message
    # bind index ??? reconstruct-thread
    # get message with Message-Id
    bind index \CG get-message
    # --------------------------------------------------------------------------

    # vim: syntax=neomuttrc

### 31.6. Known Bugs

None

### 31.7. Credits

Vsevolod Volkov, Felix von Leitner, Richard Russon

## 32. Custom backend based Tags Feature

### Implements Notmuch tags and Imap keywords

### 32.1. Support

Since: NeoMutt 2017-10-16

Dependencies:

- quasi-delete feature

- index-color feature

### 32.2. Introduction

Some backends allow to index and tag mail without storing the tags within the mail envelope. Two backends are currently implementing this feature. Notmuch handles them natively and IMAP stores them in custom IMAP keywords.

### 32.3. Variables

Table 6.20. Custom tags Variables

Name | Type | Default
--- | --- | ---
`hidden_tags` | string | `unread,draft,flagged,passed,replied,attachment,signed,encrypted`

### 32.4. Functions

Notmuch adds the following functions to NeoMutt. By default, none of them are bound to keys.

Table 6.21. Notmuch/IMAP Functions

Menus | Function | Description
--- | --- | ---
index,pager | `<modify-labels>` | add, remove, or toggle tags: IMAP: edit the tags list Notmuch: [+]<tag> to add, -<tag> to remove, !<tag> to toggle(notmuch) tags. Note: Tab completion of tag names is available
index,pager | `<modify-labels-then-hide>` | add, remove, or toggle tags IMAP: edit the tags list Notmuch: [+]<tag> to add, -<tag> to remove, !<tag> to toggle labels and then hide or unhide the message by changing the "quasi-deleted" to match if it would be shown when requerying. Normal redisplay rules apply here, so the user must call <sync-mailbox> for the changes to be displayed. Note: Tab completion of tag names is available.

### 32.5. Commands

`tag-transforms` `tag` `transformed-string` { `tag` `transformed-string` ...}
`tag-formats` `tag` `format-string` { `tag` `format-string` ...}

### 32.6. Colors

Adds the objects, below, to index-color feature. The objects can take an optional pattern.

Table 6.22. Index Colors

Object | Highlights
--- | ---
`index_tag` | an individual message tag, %G, uses tag name
`index_tags` | the transformed message tags, %g or %J

### 32.7. neomuttrc

    # Example NeoMutt config file for the custom tags feature.

    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    # This variable specifies private notmuch tags which should not be printed
    # on screen (index, pager).
    set hidden_tags = "unread,draft,flagged,passed,replied,attachment,signed,encrypted"
    # --------------------------------------------------------------------------
    # FUNCTIONS – shown with an example mapping
    # --------------------------------------------------------------------------
    # modify (notmuch/imap) tags
    bind index,pager \` modify-labels
    # modify (notmuch/imap) tag non-interactively.
    macro index,pager tt "<modify-labels>!todo\n" "Toggle the 'todo' tag"
    # modify labels and then hide message
    # bind index,pager ??? modify-labels-then-hide
    # --------------------------------------------------------------------------
    # COMMANDS – shown with an example
    # --------------------------------------------------------------------------
    # Replace some tags with icons
    # tag-transforms tag transformed-string { tag transformed-string ...}
    # tag-transforms "inbox"   "i"   \
    #                "unread"  "u"   \
    #                "replied" "↻ "  \
    #                "sent"    "➥ "  \
    #                "todo"    "T"   \
    #                "deleted" "DEL" \
    #                "invites" "CAL"

    # The formats must start with 'G' and the entire sequence is case sensitive.
    # tag-formats tag format-string { tag format-string ...}
    # tag-formats "inbox"   "GI" \
    #             "unread"  "GU" \
    #             "replied" "GR" \
    #             "sent"    "GS" \
    #             "todo"    "Gt" \
    #             "deleted" "GD" \
    #             "invites" "Gi"

    # Now instead of using '%g' or '%J' in your $index_format, which lists all tags
    # in a non-deterministic order, you can something like the following which puts
    # a transformed tag name in a specific spot on the index line:
    # set index_format='%4C %S %[%y.%m.%d] %-18.18n %<GU?%GU& > %<GR?%GR& > %<GI?%GI& > %s'

    # The %G formatting sequence may display all tags including tags hidden by
    # hidden_tags.
    #
    # --------------------------------------------------------------------------
    # COLORS – some unpleasant examples are given
    # --------------------------------------------------------------------------
    # These symbols are added to the index-color feature:
    # an individual message tag, %G, uses tag name
    color index_tag red white "inbox"
    # the transformed message tags, %g
    color index_tags green default
    # --------------------------------------------------------------------------

    # vim: syntax=neomuttrc

### 32.8. Credits

Mehdi Abaakouk, Richard Russon, Bernard 'Guyzmo' Pratz

## 33. Notmuch Feature

### Email search engine

### 33.1. Support

Since: NeoMutt 2016-03-17

Dependencies:

- quasi-delete feature

- index-color feature

- Notmuch libraries

### 33.2. Introduction

Notmuch is an email fulltext indexing and tagging engine.

- For more information, see: https://notmuchmail.org/

- More examples: https://notmuchmail.org/mutttips/

### 33.3. Using Notmuch

#### 33.3.1. Folders URL

notmuch://[<path>][?<item>=<name>[& ...]]

The <path> is an absolute path to the directory where the notmuch database is found as returned by “notmuch config get database.path” command. Note that the <path> should NOT include `.notmuch` directory name.

If the "<path>" is not defined then `$nm_default_url` or `$folder` is used, for example:

    set nm_default_url = "notmuch:///home/foo/maildir"
    virtual-mailboxes "My INBOX" "notmuch://?query=tag:inbox"

#### 33.3.2. Items

query=<string>

See SEARCH SYNTAX in notmuch man page. Don't forget to use operators (“and”/“or”) in your queries.

Note that proper URL should not contain blank space and all “bad” chars should be encoded, for example

`tag:AAA and tag:BBB` – encoding -> `tag:AAA%20and%20tag:BBB`

but NeoMutt config file parser is smart enough to accept space in quoted strings. It means that you can use

`notmuch:///foo?query=tag:AAA and tag:BBB`

in your config files to keep things readable.

For more details about Xapian queries, see: https://xapian.org/docs/queryparser.html

limit=<number>

Restricts number of messages/threads in the result. The default limit is nm_db_limit.

Due to a limitation with `libnotmuch`, unread and flagged message count may be inaccurate with limit statements. `libnotmuch` cannot return a specific tag count within the first X messages of a query.

type=<threads|messages>

Reads all matching messages or whole-threads. The default is 'messages' or nm_query_type.

### 33.4. Variables

Table 6.23. Notmuch Variables

Name | Type | Default | Note
--- | --- | --- | ---
`nm_config_file` | path | `auto` | Configuration file for the notmuch database. Either a path, `auto` for detecting a config. file, or empty for no configuration file. Only useful for notmuch 0.32+.
`nm_config_profile` | string | (empty) | Configuration profile for the notmuch database. Only useful for notmuch 0.32+.
`nm_db_limit` | number | `0` |
`nm_default_url` | string | (empty) | Must use format: `notmuch://<absolute path>`
`nm_exclude_tags` | string | (empty) |
`nm_flagged_tag` | string | `flagged` |
`nm_open_timeout` | number | `5` |
`nm_query_type` | string | `messages` |
`nm_query_window_current_position` | number | `0` | Position of current search window
`nm_query_window_current_search` | string | (empty) | Current search parameters
`nm_query_window_duration` | number | `0` | Duration between start and end dates for windowed notmuch query. This corresponds to a bounded notmuch `date:` query. See `notmuch-search-terms` manual page for more info. Value of `0` disables windowed queries unless `nm_query_window_enable=yes`
`nm_query_window_enable` | boolean | `no` | Enables windowed notmuch queries for `nm_query_window_duration = 0`
`nm_query_window_or_terms` | string | (empty) | Additional notmuch search terms to always include in the window even if they're outside the date range. This turns the window from `date:...` to `date:... or (additional search terms.)` For example, to always include flagged, unread emails, set to `tag:flagged and tag:unread`
`nm_query_window_timebase` | string | `week` | Time base for windowed notmuch queries. Must be one of: `hour`, `day`, `week`, `month`, or `year`
`nm_record` | boolean | `no` |
`nm_record_tags` | string | (empty) |
`nm_unread_tag` | string | `unread` |
`virtual_spool_file` | boolean | `no` | Unnecessary since $spool_file supports mailbox descriptions.

More variables about tags configuration can be found in Custom backend Tags Feature

### 33.5. Functions

Notmuch adds the following functions to NeoMutt. By default, none of them are bound to keys.

Table 6.24. Notmuch Functions

Menus | Function | Description
--- | --- | ---
index,pager | `<change-vfolder>` | switch to another virtual folder, a new folder maybe be specified by vfolder description (see virtual-mailboxes) or URL. the default is next vfolder with unread messages
index,pager | `<entire-thread>` | read entire thread of the current message
index,pager | `<sidebar-toggle-virtual>` | toggle between mailboxes and virtual mailboxes
index,pager | `<vfolder-from-query>` | generate virtual folder from notmuch search query. Note: TAB completion of 'tag:' names is available.
index,pager | `<vfolder-from-query-readonly>` | The same as `<vfolder-from-query>`; however, the mailbox will be read-only.
index | `<vfolder-window-forward>` | generate virtual folder by moving the query's time window forward
index | `<vfolder-window-backward>` | generate virtual folder by moving the query's time window backward
index | `<vfolder-window-reset>` | generate virtual folder by moving the query's time window to the present

More functions about tags can be found in Custom backend Tags Feature

### 33.6. Commands

`virtual-mailboxes` `description` `notmuch-URL` { `description` `notmuch-URL` ...}
`unvirtual-mailboxes` { `*` | `mailbox` ... }

`virtual-mailboxes` is like the mailboxes command, except that it takes a description. The mailbox will be watched for new mail and will appear in the sidebar.

`unvirtual-mailboxes` is identical to the `unmailboxes` command.

More commands about tags can be found in Custom backend Tags Feature

### 33.7. Colors

See Custom backend Tags colors

### 33.8. neomuttrc

    # Example NeoMutt config file for the notmuch feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    # This variable specifies notmuch query limit.
    set nm_db_limit = 0
    # This variable specifies the default Notmuch database in format:
    # notmuch://<absolute path>
    set nm_default_url = ""
    # The messages tagged with these tags are excluded and not loaded
    # from notmuch DB to NeoMutt unless specified explicitly.
    set nm_exclude_tags = ""
    # This option specifies timeout for Notmuch database. Default is 5 seconds.
    set nm_open_timeout = 5
    # This variable specifies notmuch query type, supported types: 'threads' and
    # 'messages'.
    set nm_query_type = messages
    # When writing a message in the NeoMutt record (see $record in the NeoMutt docs),
    # also add it to the notmuch DB. Replies inherit the tags from the original email.
    set nm_record = no
    # Tags modifications to the messages stored in the NeoMutt record.
    # example:
    #   set record = "~/sent-mails"
    #   set nm_record = yes
    #   set nm_record_tags = "-inbox,archive,me"
    set nm_record_tags = ""
    # This variable specifies the notmuch tag used for unread messages.
    set nm_unread_tag = unread
    # When set, NeoMutt will use the first virtual mailbox (see virtual-mailboxes)
    # as a spool_file.
    set virtual_spool_file = no
    # setup time window preferences
    # first setup the duration, and then the time unit of that duration
    # when set to 0 (the default) the search window feature is disabled
    # unless explicitly enabled with nm_query_window_enable.
    set nm_query_window_enable=yes
    set nm_query_window_duration=2
    set nm_query_window_timebase="week" # or "hour", "day", "week", "month", "year"
    # Extend query window to always show mail matching these terms.
    set nm_query_window_or_terms="tag:unread and tag:flagged"
    # --------------------------------------------------------------------------
    # FUNCTIONS – shown with an example mapping
    # --------------------------------------------------------------------------
    # open a different virtual folder
    bind index,pager X change-vfolder
    # read entire thread of the current message
    bind index,pager + entire-thread
    # generate virtual folder from query
    bind index,pager \eX vfolder-from-query
    # generate virtual folder from query with time window
    bind index < vfolder-window-backward
    bind index > vfolder-window-forward
    # toggle between mailboxes and virtual mailboxes
    # bind index,pager ??? sidebar-toggle-virtual
    # --------------------------------------------------------------------------
    # COMMANDS – shown with an example
    # --------------------------------------------------------------------------
    # virtual-mailboxes description notmuch-URL { description notmuch-URL ...}
    # virtual-mailboxes "Climbing" "notmuch://?query=climbing"
    # unvirtual-mailboxes { * | mailbox ...}
    #
    # --------------------------------------------------------------------------

    # vim: syntax=neomuttrc

### 33.9. See Also

- Compile-Time Features

### 33.10. Known Bugs

None

### 33.11. Credits

Karel Zak, Chris Mason, Christoph Rissner, David Riebenbauer, David Sterba, David Wilson, Don Zickus, Eric Davis, Jan Synacek, Jeremiah C. Foster, Josh Poimboeuf, Kirill A. Shutemov, Luke Macken, Mantas Mikulėnas, Patrick Brisbin, Philippe Le Brouster, Raghavendra D Prabhu, Sami Farin, Stefan Assmann, Stefan Kuhn, Tim Stoakes, Vladimir Marek, Víctor Manuel Jáquez Leal, Richard Russon, Bernard 'Guyzmo' Pratz

## 34. Pager Read Delay Feature

### Delay when the pager marks a previewed message as read

### 34.1. Support

Since: NeoMutt 2021-06-16

Dependencies: None

### 34.2. Introduction

The “Pager Read Delay” feature adds a new config variable to allow the pager to operate in a preview mode. A new message is not marked as read merely because the pager opened it, but only after the pager remains on the message for a given length of time.

### 34.3. Functions

The “Pager Read Delay” feature adds no new functions to NeoMutt. Existing pager functions for navigating to a different message now check whether to mark a message as read.

### 34.4. Variables

The “Pager Read Delay” feature adds one new config variable, $pager_read_delay, which is an integer for how many seconds the pager must remain on a given message before marking it as read. The variable defaults to 0 for the original behavior of marking a message as read the moment the pager visits it.

### 34.5. neomuttrc

    # Example NeoMutt config file for the pager-read-delay feature.

    # Stay at least 5 seconds on a message before the pager marks it as read
    set pager_read_delay = 5

    # vim: syntax=neomuttrc

### 34.6. Known Bugs

When $pager_index_lines is non-zero, the “N” status indicator from the “%Z” expando of $index_format does not actively reflect the current new/read status of the message.

### 34.7. Credits

Eric Blake

## 35. Progress Bar Feature

### Show a visual progress bar on slow operations

### 35.1. Support

Since: NeoMutt 2016-03-07

Dependencies: None

### 35.2. Introduction

The “progress” feature shows a visual progress bar on slow tasks, such as indexing a large folder over the net.

### 35.3. Colors

Table 6.25. Progress Colors

Name | Default Color | Description
--- | --- | ---
`progress` | default | Visual progress bar

### 35.4. neomuttrc

    # Example NeoMutt config file for the progress feature.

    # The 'progress' feature provides clear visual feedback for
    # slow tasks, such as indexing a large folder over the net.

    # Set the color of the progress bar
    # White text on a red background
    color progress white red

    # vim: syntax=neomuttrc

### 35.5. See Also

- Color command

### 35.6. Known Bugs

None

### 35.7. Credits

Rocco Rutte, Vincent Lefevre, Stefan Kuhn, Karel Zak, Richard Russon

## 36. Quasi-Delete Feature

### Mark emails that should be hidden, but not deleted

### 36.1. Support

Since: NeoMutt 2016-03-07

Dependencies: None

### 36.2. Introduction

The “quasi-delete” function marks an email that should be hidden from the index, but NOT deleted. The email will disappear from the index when <sync-mailbox> is called.

On its own, this feature isn't very useful. It forms a useful part of the notmuch plugin.

### 36.3. Functions

Table 6.26. Quasi-Delete Functions

Menus | Default Key | Function | Description
--- | --- | --- | ---
index,pager | (none) | `<quasi-delete>` | delete from NeoMutt, don't touch on disk

### 36.4. neomuttrc

    # Example NeoMutt config file for the quasi-delete feature.

    # The 'quasi-delete' function marks an email that should be hidden
    # from the index, but NOT deleted.
    bind index,pager Q quasi-delete

    # vim: syntax=neomuttrc

### 36.5. See Also

- notmuch feature

### 36.6. Known Bugs

None

### 36.7. Credits

Karel Zak, Richard Russon

## 37. Reply With X-Original-To Feature

### Direct reply to email using X-Original-To header

### 37.1. Support

Since: NeoMutt 2016-09-10

Dependencies: None

### 37.2. Introduction

Adds a reply_with_xorig for NeoMutt configuration files. If enabled, allows to reply to an email using the email address in the first X-Original-To: header of a mail as the From: header of the answer.

### 37.3. Variables

Table 6.27. Reply With X-Original-To Variables

Name | Type | Default
--- | --- | ---
`reply_with_xorig` | Boolean | `no`

### 37.4. neomuttrc

    # Example NeoMutt config file for the reply-with-xorig feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    # Use X-Original-To header to reply when reverse is disabled or no alternate
    # is found.
    set reply_with_xorig = "yes"

    # vim: syntax=neomuttrc

### 37.5. Credits

Pierre-Elliott Bécue

## 38. Sensible Browser Feature

### Make the file browser behave

### 38.1. Support

Since: NeoMutt 2016-09-10

Dependencies: None

### 38.2. Introduction

The “sensible browser” is a set of small changes to NeoMutt's mailbox browser which make the browser behave in a more predictable way.

The behavior is divided into two use cases: Fixed Order; Variable Order.

#### 38.2.1. A Fixed Order of Mailboxes

This is for users who like their mailboxes in a fixed order, e.g. alphabetical, or unsorted (in the order of the config file).

    # Fixed order
    set browser_sort = "alpha"
    set browser_sort = "unsorted"

When you first start the browser, e.g. `c?` your current mailbox will be highlighted.

When you navigate to a parent mailbox (“..”) your old mailbox will be highlighted.

“..” will always be listed at the top, however the rest of the list is sorted.

#### 38.2.2. A Variable Order of Mailboxes

This is for users who like their mailboxes sorted by a characteristic that changes, e.g. count of new mail, or the size of mailbox.

    # Variable order
    set browser_sort = "reverse-count"
    set browser_sort = "reverse-size"

When you first start the browser, e.g. `c?` the highlight will be on the first mailbox, e.g. the one with the most new mail.

When you navigate to a parent mailbox (“..”) your old mailbox will be highlighted.

“..” will always be listed at the top, however the rest of the list is sorted.

### 38.3. See Also

- $folder_format

### 38.4. Known Bugs

None

### 38.5. Credits

Pierre-Elliott Bécue, Haakon Riiser, Richard Russon

## 39. Sidebar Feature

### Overview of mailboxes

### 39.1. Support

Since: NeoMutt 2016-09-10, NeoMutt 1.7.0

Dependencies: None

### 39.2. Introduction

The Sidebar shows a list of all your mailboxes. The list can be turned on and off, it can be themed and the list style can be configured.

This part of the manual is a reference guide. If you want a simple introduction with examples see the Sidebar Howto. If you just want to get started, you could use the sample Sidebar neomuttrc.

### 39.3. Variables

Table 6.28. Sidebar Variables

Name | Type | Default
--- | --- | ---
`sidebar_component_depth` | number | `0`
`sidebar_delim_chars` | string | `/.`
`sidebar_divider_char` | string | `|`
`sidebar_folder_indent` | boolean | `no`
`sidebar_format` | string | `%D%* %n`
`sidebar_indent_string` | string | `` (two spaces)
`sidebar_new_mail_only` | boolean | `no`
`sidebar_next_new_wrap` | boolean | `no`
`sidebar_non_empty_mailbox_only` | boolean | `no`
`sidebar_on_right` | boolean | `no`
`sidebar_short_path` | boolean | `no`
`sidebar_sort` | enum | `unsorted`
`sidebar_visible` | boolean | `no`
`sidebar_width` | number | `20`

For more details, and examples, about the `$sidebar_format`, see the Sidebar Intro.

### 39.4. Functions

Sidebar adds the following functions to NeoMutt. By default, none of them are bound to keys.

Table 6.29. Sidebar Functions

Menus | Function | Description
--- | --- | ---
index,pager | `<sidebar-next>` | Move the highlight to next mailbox
index,pager | `<sidebar-next-new>` | Move the highlight to next mailbox with new mail
index,pager | `<sidebar-open>` | Open highlighted mailbox
index,pager | `<sidebar-page-down>` | Scroll the Sidebar down 1 page
index,pager | `<sidebar-page-up>` | Scroll the Sidebar up 1 page
index,pager | `<sidebar-prev>` | Move the highlight to previous mailbox
index,pager | `<sidebar-prev-new>` | Move the highlight to previous mailbox with new mail
index,pager | `<sidebar-toggle-visible>` | Make the Sidebar (in)visible

### 39.5. Commands

`sidebar_pin` `mailbox` [ `mailbox` ...]
`sidebar_unpin` { `*` | `mailbox` ... }

This command specifies mailboxes that will always be displayed in the sidebar, even if $sidebar_new_mail_only is set and the mailbox does not contain new mail.

The “sidebar_unpin” command is used to remove a mailbox from the list of always displayed mailboxes. Use “sidebar_unpin *” to remove all mailboxes.

### 39.6. Colors

Table 6.30. Sidebar Colors

Name | Default Color | Description
--- | --- | ---
`sidebar_background` | default | The entire sidebar panel
`sidebar_divider` | default | The dividing line between the Sidebar and the Index/Pager panels
`sidebar_flagged` | default | Mailboxes containing flagged mail
`sidebar_highlight` | underline | Cursor to select a mailbox
`sidebar_indicator` | neomutt `indicator` | The mailbox open in the Index panel
`sidebar_new` | default | Mailboxes containing new mail
`sidebar_ordinary` | default | Mailboxes that have no new/flagged mails, etc.
`sidebar_spool_file` | default | Mailbox that receives incoming mail
`sidebar_unread` | default | Mailboxes containing unread mail

If the `sidebar_indicator` color isn't set, then the default NeoMutt indicator color will be used (the color used in the index panel).

### 39.7. Sort

Table 6.31. Sidebar Sort

Sort | Description
--- | ---
`alpha` | Alphabetically by path or label
`count` | Total number of messages
`desc` | Descriptive name of the mailbox
`flagged` | Number of flagged messages
`name` | Alphabetically by path or label
`new` | Number of unread messages
`path` | Alphabetically by path (ignores label)
`unread` | Number of unread messages
`unsorted` | Order of the `mailboxes` command

### 39.8. neomuttrc

    # Example NeoMutt config file for the sidebar feature.

    # --------------------------------------------------------------------------
    # VARIABLES – shown with their default values
    # --------------------------------------------------------------------------
    # Should the Sidebar be shown?
    set sidebar_visible = no
    # How wide should the Sidebar be in screen columns?

    # Note: Some characters, e.g. Chinese, take up two columns each.
    set sidebar_width = 20
    # Should the mailbox paths be abbreviated?
    set sidebar_short_path = no
    # Number of top-level mailbox path subdirectories to truncate for display
    set sidebar_component_depth = 0
    # When abbreviating mailbox path names, use any of these characters as path
    # separators. Only the part after the last separators will be shown.
    # For file folders '/' is good. For IMAP folders, often '.' is useful.
    set sidebar_delim_chars = '/.'
    # If the mailbox path is abbreviated, should it be indented?
    set sidebar_folder_indent = no
    # Indent mailbox paths with this string.
    set sidebar_indent_string = '  '
    # Make the Sidebar only display mailboxes that contain new, or flagged,
    # mail.
    set sidebar_new_mail_only = no
    # Any mailboxes that are pinned will always be visible, even if the
    # sidebar_new_mail_only option is enabled.
    set sidebar_non_empty_mailbox_only = no
    # Only show mailboxes that contain some mail
    sidebar_pin '/home/user/mailbox1'
    sidebar_pin '/home/user/mailbox2'
    # When searching for mailboxes containing new mail, should the search wrap
    # around when it reaches the end of the list?
    set sidebar_next_new_wrap = no
    # Show the Sidebar on the right-hand side of the screen
    set sidebar_on_right = no
    # The character to use as the divider between the Sidebar and the other NeoMutt
    # panels.
    set sidebar_divider_char = '|'
    # Enable extended mailbox mode to calculate total, new, and flagged
    # message counts for each mailbox.
    set mail_check_stats
    # Display the Sidebar mailboxes using this format string.
    set sidebar_format = '%B%<F? [%F]>%* %<N?%N/>%S'
    # Sort the mailboxes in the Sidebar using this method:
    #       count    – total number of messages
    #       flagged  – number of flagged messages
    #       unread   – number of unread messages
    #       path     – mailbox path
    #       unsorted – do not sort the mailboxes
    set sidebar_sort = 'unsorted'
    # --------------------------------------------------------------------------
    # FUNCTIONS – shown with an example mapping
    # --------------------------------------------------------------------------
    # Move the highlight to the previous mailbox
    bind index,pager \Cp sidebar-prev
    # Move the highlight to the next mailbox
    bind index,pager \Cn sidebar-next
    # Open the highlighted mailbox
    bind index,pager \Co sidebar-open
    # Move the highlight to the previous page
    # This is useful if you have a LOT of mailboxes.
    bind index,pager <F3> sidebar-page-up
    # Move the highlight to the next page
    # This is useful if you have a LOT of mailboxes.
    bind index,pager <F4> sidebar-page-down
    # Move the highlight to the previous mailbox containing new, or flagged,
    # mail.
    bind index,pager <F5> sidebar-prev-new
    # Move the highlight to the next mailbox containing new, or flagged, mail.
    bind index,pager <F6> sidebar-next-new
    # Toggle the visibility of the Sidebar.
    bind index,pager B sidebar-toggle-visible
    # --------------------------------------------------------------------------
    # COLORS – some unpleasant examples are given
    # --------------------------------------------------------------------------
    # Note: All color operations are of the form:
    #       color OBJECT FOREGROUND BACKGROUND
    # Color of the current, open, mailbox
    # Note: This is a general NeoMutt option which colors all selected items.
    color indicator cyan black
    # Sidebar-specific color of the selected item
    color sidebar_indicator cyan black
    # Color of the highlighted, but not open, mailbox.
    color sidebar_highlight black color8
    # Color of the entire Sidebar panel
    color sidebar_background default black
    # Color of the divider separating the Sidebar from NeoMutt panels
    color sidebar_divider color8 black
    # Color to give mailboxes containing flagged mail
    color sidebar_flagged red black
    # Color to give mailboxes containing new mail
    color sidebar_new green black
    # Color to give mailboxes containing no new/flagged mail, etc.
    color sidebar_ordinary color245 default
    # Color to give the spool_file mailbox
    color sidebar_spool_file color207 default
    # Color to give mailboxes containing no unread mail
    color sidebar_unread color136 default
    # --------------------------------------------------------------------------

    # vim: syntax=neomuttrc

### 39.9. See Also

- Regular Expressions

- Patterns

- Color command

- notmuch feature

### 39.10. Known Bugs

None

### 39.11. Credits

Justin Hibbits, Thomer M. Gil, David Sterba, Evgeni Golov, Fabian Groffen, Jason DeTiberus, Stefan Assmann, Steve Kemp, Terry Chan, Tyler Earnest, Richard Russon

## 40. Skip Quoted Feature

### Managing quoted text in the pager

### 40.1. Support

Since: `$skip_quoted_offset` in NeoMutt 2016-03-28, `$toggle_quoted_show_levels` in NeoMutt 2019-10-25, `<skip-headers>` in NeoMutt 2021-02-05

Dependencies: None

### 40.2. Introduction

When viewing an email, the `<skip-quoted>` function (by default the `S` key) will scroll past any email headers or quoted text. Sometimes, a little context is useful. By setting the `$skip_quoted_offset` variable, you can select how much of the quoted text is left visible.

When using the `<toggle-quoted>` function (by default the `T` key), it can be convenient to hide text that has been quoted multiple times while still leaving quoted text that is relevant to the unquoted reply intact. This can be done by setting the `$toggle_quoted_show_levels` variable.

Also, it can be handy to jump directly to the start of the email body with the `<skip-headers>` function (by default the `H` key).

### 40.3. Functions

Table 6.32. Skip Quoted Functions

Menus | Default Key | Function | Description
--- | --- | --- | ---
pager | H | `<skip-headers>` | jump to first line after headers

### 40.4. Variables

Table 6.33. Skip-Quoted Variables

Name | Type | Default
--- | --- | ---
`pager_skip_quoted_context` | number | 0
`skip_quoted_offset` | synonym | pager_skip_quoted_context
`toggle_quoted_show_levels` | number | 0

### 40.5. neomuttrc

    # Example NeoMutt config file for the skip-quoted feature.

    # The 'S' (skip-quoted) command scrolls the pager past the quoted text (usually
    # indented with '> '. Setting 'pager_skip_quoted_context leaves some lines
    # of quoted text on screen for context.

    # Show three quoted lines before the reply
    set pager_skip_quoted_context = 3

    # The 'T' (toggle-quoted) command hides quoted text, but can
    # be limited to only hiding deeply-nested quotes.

    # Preserve the first level of quoted text
    set toggle_quoted_show_levels = 1

    # vim: syntax=neomuttrc

### 40.6. Known Bugs

None

### 40.7. Credits

David Sterba, Richard Russon

## 41. Status Color Feature

### Custom rules for theming the status bar

### 41.1. Support

Since: NeoMutt 2016-03-07

Dependencies: None

### 41.2. Introduction

The “status-color” feature allows you to theme different parts of the status bar (also when it's used by the index).

Unlike normal color commands, `color status` can now take up to 2 extra parameters (regex, num).

### 41.3. Commands

`color` `status` `foreground` `background` [ `regex` [ `num` ]]

With zero parameters, NeoMutt will set the default color for the entire status bar.

With one parameter, NeoMutt will only color the parts matching the regex.

With two parameters, NeoMutt will only color the num'th sub-match of the regex.

### 41.4. Colors

Table 6.34. Status Colors

Name | Default Color | Description
--- | --- | ---
status | `reverse` | Status bar

### 41.5. neomuttrc

    # Example NeoMutt config file for the status-color feature.

    # The 'status-color' feature allows you to theme different parts of
    # the status bar (also when it's used by the index).

    # For the examples below, set some defaults
    set status_format='-%r-NeoMutt: %f [Msgs:%<M?%M/>%m%<n? New:%n>%<o? Old:%o>%<d? Del:%d>\
    %<F? Flag:%F>%<t? Tag:%t>%<p? Post:%p>%<b? Inc:%b>%<l? %l>]---(%s/%S)-%>-(%P)---'
    set index_format='%4C %Z %{%b %d} %-15.15L (%<l?%4l&%4c>) %s'
    set use_threads=yes
    set sort=last-date-received
    set sort_aux=date
    # 'status color' can take up to 2 extra parameters
    # color status foreground background [ regex [ num ]]
    # 0 extra parameters
    # Set the default color for the entire status line
    color status blue white
    # 1 extra parameter
    # Set the color for a matching pattern
    # color status foreground background regex
    # Highlight New, Deleted, or Flagged emails
    color status brightred white '(New|Del|Flag):[0-9]+'
    # Highlight mailbox ordering if it's different from the default
    # First, highlight anything (*/*)
    color status brightred default '\([^)]+/[^)]+\)'
    # Then override the color for one specific case
    color status default default '\(threads/last-date-received\)'
    # 2 extra parameters
    # Set the color for the nth submatch of a pattern
    # color status foreground background regex num
    # Highlight the contents of the []s but not the [] themselves
    color status red default '\[([^]]+)\]' 1
    # The '1' refers to the first regex submatch, which is the inner
    # part in ()s
    # Highlight the mailbox
    color status brightwhite default 'NeoMutt: ([^ ]+)' 1
    # Search for 'NeoMutt: ' but only highlight what comes after it

    # vim: syntax=neomuttrc

### 41.6. See Also

- Compile-Time Features

- Regular Expressions

- Patterns

- index-color feature

- Color command

### 41.7. Known Bugs

None

### 41.8. Credits

David Sterba, Thomas Glanzmann, Kirill A. Shutemov, Richard Russon

## 42. TLS-SNI Feature

### Negotiate with a server for a TLS/SSL certificate

### 42.1. Support

Since: NeoMutt 2016-03-07

Dependencies:

  OpenSSL

### 42.2. Introduction

The “TLS-SNI” feature adds support for TLS virtual hosting. If your mail server doesn't support this everything will still work normally.

TLS supports sending the expected server hostname during the handshake, via the SNI extension. This can be used to select a server certificate to issue to the client, permitting virtual-hosting without requiring multiple IP addresses.

This has been tested against Exim 4.80, which optionally logs SNI and can perform vhosting.

To verify TLS SNI support by a server, you can use:

    openssl s_client -host <imap server> -port <port> -tls1 -servername <imap server>

### 42.3. Known Bugs

None

### 42.4. Credits

Jeremy Katz, Phil Pennock, Richard Russon

## 43. Trash Folder Feature

### Automatically move deleted emails to a trash bin

### 43.1. Support

Since: NeoMutt 2016-09-10, NeoMutt 1.7.0

Dependencies:

  If IMAP is enabled, the trash folder will use it wisely

### 43.2. Introduction

In NeoMutt, when you “delete” an email it is first marked deleted. The email isn't really gone until <sync-mailbox> is called. This happens when the user leaves the folder, or the function is called manually.

After `<sync-mailbox>` has been called the email is gone forever.

The $trash variable defines a folder in which to keep old emails. As before, first you mark emails for deletion. When <sync-mailbox> is called the emails are moved to the trash folder.

The `$trash` path can be either a full directory, or be relative to the $folder variable, like the `mailboxes` command.

### Note

Emails deleted from the trash folder are gone forever.

### 43.3. Variables

Table 6.35. Trash Variables

Name | Type | Default
--- | --- | ---
trash | string | (none)

### 43.4. Functions

Table 6.36. Trash Functions

Menus | Default Key | Function | Description
--- | --- | --- | ---
index,pager | (none) | `<purge-message>` | really delete the current entry, bypassing the trash folder

### 43.5. neomuttrc

    # Example NeoMutt config file for the 'trash' feature.

    # This feature defines a new 'trash' folder.

    # When mail is deleted it will be moved to this folder.

    # Folder in which to put deleted emails
    set trash='+Trash'
    set trash='/home/flatcap/Mail/Trash'
    # The default delete key 'd' will move an email to the 'trash' folder
    # Bind 'D' to REALLY delete an email
    bind index D purge-message
    # Note: Deleting emails from the 'trash' folder will REALLY delete them.

    # vim: syntax=neomuttrc

### 43.6. See Also

- folder-hook

### 43.7. Known Bugs

None

### 43.8. Credits

Cedric Duval, Benjamin Kuperman, Paul Miller, Richard Russon

## 44. Use Threads Feature

### Improve the experience with viewing threads in the index

### 44.1. Support

Since: NeoMutt 2021-08-01

Dependencies: None

### 44.2. Introduction

The “Use Threads” feature adds a new config variable to allow more precise control of how threads are displayed in the index. Whether threads are in use is now orthogonal from how messages are sorted.

### 44.3. Functions

The “Use Threads” feature adds no new functions to NeoMutt. The existing functions `<sort-mailbox>` and `<sort-reverse>` are updated to toggle the state of `$use_threads` once it has been set, while preserving backwards-compatible behavior on `$sort` if this feature is not used.

### 44.4. Variables

The “Use Threads” feature adds one new config variable, $use_threads, which is an enumeration of possible thread views. The variable defaults to unset for the original behavior of overloading $sort=threads to enable sorting. It can be set to `flat` (or `no`) for an unthreaded view based on `$sort`, to `threads` (or `yes`) for a threaded view where roots appear above children, or to `reverse` for a threaded view where children appear above roots.

When sorting by threads, the value of $sort determines which thread floats to the top. If `$sort` does not contain `reverse-`, the latest thread goes to the bottom for `use_threads=threads` and to the top for `use_threads=reverse`; the direction of float is swapped if `$sort` also uses `reverse-`. If `$sort` includes `last-`, the overall thread is sorted by its descendant at any depth which would sort last in a flat view; otherwise, the overall thread is sorted solely by the thread root. The `last-` prefix is ignored when `use_threads=flat`.

Within a single thread, the value of $sort_aux determines how siblings are sorted. The same prefixes apply as for `$sort`, although it is less common to use the `last-` prefix.

The “Use Threads” feature also modifies the existing config variable $status_format, adding the `%T` expando which shows the current threading method.

### 44.5. Use Threads

Table 6.37. Use Threads

Name | Type | Default
--- | --- | ---
`use_threads` | enum | `unset`

### 44.6. neomuttrc

    # Example NeoMutt config file for the use-threads feature.

    # ------------------------------------------------------------
    # Default configuration: flat view sorted by date
    # selecting threads with <sort-mailbox> changes $sort
    #set use_threads=unset sort=date sort_aux=date
    # Modern configuration: explicit flat view sorted by date
    # selecting threads with <sort-mailbox> changes $use_threads
    set use_threads=no sort=date sort_aux=date
    #   Anne     12:01  cover letter for thread 1
    #   Anne     12:02  part 1 of thread 1
    #   Anne     12:03  part 2 of thread 1
    #   Anne     12:04  part 3 of thread 1
    #   Barbara  12:05  thread 2
    #   Claire   12:06  thread 3
    #   Diane    12:07  re: part 2 of thread 1
    #   Erica    12:08  re: thread 2

    # ------------------------------------------------------------
    # Legacy configuration: sorting threads by date started
    #set sort=threads sort_aux=date
    # Modern configuration for the same
    # Latest root message sorts last
    set use_threads=yes sort=date sort_aux=date
    #   Anne     12:01  cover letter for thread 1
    #   Anne     12:02  |->part 1 of thread 1
    #   Anne     12:03  |->part 2 of thread 1
    #   Diane    12:07  | `->re: part 2 of thread 1
    #   Anne     12:04  `->part 3 of thread 1
    #   Barbara  12:05  thread 2
    #   Erica    12:08  `->re: thread 2
    #   Claire   12:06  thread 3

    # ------------------------------------------------------------
    # Legacy configuration: display threads upside-down
    #set sort=reverse-threads sort_aux=date
    # Modern configuration for the same
    # Latest root message sorts first
    set use_threads=reverse sort=date sort_aux=date
    #   Claire   12:06  thread 3
    #   Erica    12:08  ,->re: thread 2
    #   Barbara  12:05  thread 2
    #   Anne     12:04  ,->part 3 of thread 1
    #   Diane    12:07  | ,->re: part 2 of thread 1
    #   Anne     12:03  |->part 2 of thread 1
    #   Anne     12:02  |->part 1 of thread 1
    #   Anne     12:01  cover letter for thread 1

    # ------------------------------------------------------------
    # Legacy configuration: recently active thread/subthread first
    #set sort=threads sort_aux=reverse-last-date
    # Modern configuration for the same
    # Note that subthreads are also rearranged
    set use_threads=threads sort=reverse-last-date sort_aux=reverse-last-date
    #   Barbara  12:05  thread 2
    #   Erica    12:08  `->re: thread 2
    #   Anne     12:01  cover letter for thread 1
    #   Anne     12:03  |->part 2 of thread 1
    #   Diane    12:07  | `->re: part 2 of thread 1
    #   Anne     12:04  |->part 3 of thread 1
    #   Anne     12:02  `->part 1 of thread 1
    #   Claire   12:06  thread 3

    # ------------------------------------------------------------
    # Modern configuration: threads keep date order, recently active thread last
    # (not possible with legacy configuration)
    set use_threads=threads sort=last-date sort_aux=date
    #   Claire   12:06  thread 3
    #   Anne     12:01  cover letter for thread 1
    #   Anne     12:02  |->part 1 of thread 1
    #   Anne     12:03  |->part 2 of thread 1
    #   Diane    12:07  | `->re: part 2 of thread 1
    #   Anne     12:04  `->part 3 of thread 1
    #   Barbara  12:05  thread 2
    #   Erica    12:08  `->re: thread 2

    # vim: syntax=neomuttrc

### 44.7. Known Bugs

Even though `use_threads` accepts the values `yes` and `no`, it does not behave like a boolean or quad-option variable. A bare `set use_threads` performs a query rather than setting it to `yes`, and the variable is not usable with `toggle`.

### 44.8. Credits

Eric Blake

## 45. Autocrypt

NeoMutt can be compiled with Autocrypt support by running `configure` with the `--autocrypt` flag. Autocrypt provides easy to use, passive protection against data collection. Keys are distributed via an `Autocrypt:` header added to emails. It does not protect against active adversaries, and so should not be considered a substitute for normal encryption via your keyring, using key signing and the web of trust to verify identities. With an understanding of these limitations, Autocrypt still provides an easy way to minimize cleartext emails sent between common correspondents, without having to explicitly exchange keys. More information can be found at https://autocrypt.org/.

### 45.1. Requirements

Autocrypt requires support for ECC cryptography, and NeoMutt by default will generate ECC keys. Therefore GnuPG 2.1 or greater is required. Additionally, NeoMutt's Autocrypt implementation uses GPGME and requires at least version 1.8.0.

Account and peer information is stored in a sqlite3 database, and so NeoMutt must be configured with the `--with-sqlite` flag when autocrypt is enabled.

It is highly recommended that NeoMutt be configured with `--idn2` (enabled by default) so that Autocrypt can properly deal with international domain names.

While NeoMutt uses GPGME for Autocrypt, normal keyring operations can still be performed via classic mode (i.e. with $crypt_use_gpgme unset). However, to avoid unnecessary prompts, it is recommended gpg not be configured in `loopback pinentry` mode, and that $pgp_use_gpg_agent remain set (the default).

### 45.2. First Run

To enable Autocrypt, set $autocrypt, and if desired change the value of $autocrypt_dir in your muttrc. The first time NeoMutt is run after that, you will be prompted to create $autocrypt_dir. NeoMutt will then automatically create an sqlite3 database and GPG keyring in that directory. Note since these files should be considered private, NeoMutt will create this directory with mode `700`. If you create the directory manually, you should do the same.

NeoMutt recommends keeping the $autocrypt_dir directory set differently from your GnuPG keyring directory (e.g. `~/.gnupg`). Keys are automatically imported into the keyring from `Autocrypt:` headers. Compared to standard “web of trust” keys, Autocrypt keys are somewhat ephemeral, and the autocrypt database is used to track when keys change or fall out of use. Having these keys mixed in with your normal keyring will make it more difficult to use features such as $crypt_opportunistic_encrypt and Autocrypt at the same time.

The $autocrypt_dir variable is not designed to be changed while NeoMutt is running. The database is created (if necessary) and connected to during startup. Changing the variable can result in a situation where NeoMutt is looking in one place for the database and a different place for the GPG keyring, resulting in strange behavior.

Once the directory, keyring, and database are created, NeoMutt will ask whether you would like to create an account. In order to use Autocrypt, each sending address needs an account. As a convenience you can create an account during the first run. If you would like to add additional accounts later, this can be done via the `<autocrypt-acct-menu>` function in the index, by default bound to `A`.

Account creation will first ask you for an email address. Next, it will ask whether you want to create a new key or select an existing key. (Note key selection takes place from the $autocrypt_dir keyring, which will normally be empty during first run). Finally, it will ask whether this address should prefer encryption or not. Autocrypt 1.1 allows automatically enabling encryption if both sender and receiver have set “prefer encryption”. Otherwise, you will need to manually enable autocrypt encryption in the compose menu. For more details, see the compose menu section below.

After optionally creating an account, NeoMutt will prompt you to scan mailboxes for Autocrypt headers. This step occurs because header cached messages are not re-scanned for Autocrypt headers. Scanning during this step will temporarily disable the header cache while opening each mailbox. If you wish to do this manually later, you can simulate the same thing by unsetting $header_cache and opening a mailbox.

A final technical note: the first run process takes place between reading the muttrc and opening the initial mailbox. Some muttrc files will push macros to be run after opening the mailbox. To prevent this from interfering with the first run prompts, NeoMutt disables all macros during the first run.

### 45.3. Compose Menu

When enabled, Autocrypt will add a line to the compose menu with two fields: `Autocrypt:` and `Recommendation:`.

The `Autocrypt:` field shows whether the message will be encrypted by Autocrypt when sent. It has two values: `Encrypt` and `Off`. `Encrypt` can be enabled using the `<autocrypt-menu>` function, by default bound to `o`.

The `Recommendation:` field shows the output of the Autocrypt recommendation engine. This can have one of five values:

- `Off` means the engine is disabled. This can happen if the From address doesn't have an autocrypt account, or if the account has been manually disabled.

- `No` means one or more recipients are missing an autocrypt key, or the key found is unusable (i.e. expired, revoked, disabled, invalid, or not usable for encryption.)

- `Discouraged` means a key was found for every recipient, but the engine is not confident the message will be decryptable by the recipient. This can happen if the key hasn't been used recently (compared to their last seen email).

  It can also happen if the key wasn't seen first-hand from the sender. Autocrypt has a feature where recipient keys can be included in group-encrypted emails. This allows you to reply to a conversation where you don't have a key first-hand from one of the other recipients. However, those keys are not trusted as much as from first-hand emails, so the engine warns you with a `Discouraged` status.

- `Available` means a key was found for every recipient, and the engine believes all keys are recent and seen from the recipient first hand. However, either you or one of the recipients chose not to specify “prefer encryption”.

- `Yes` is the same as `Available`, with the addition that you and all recipients have specified “prefer encryption”. This value will automatically enable encryption, unless you have manually switched it off or enabled regular encryption or signing via the `<pgp-menu>`.

As mentioned above the `<autocrypt-menu>` function, by default bound to `o`, can be used to change the `Encrypt:` field value. `(e)ncrypt` will toggle encryption on. `(c)lear` will toggle encryption off. If either of these are chosen, the field will remain in that state despite what the `Recommendation:` field shows. Lastly, `(a)utomatic` will set the value based on the recommendation engine's output.

Autocrypt encryption defers to normal encryption or signing. Anything that enables normal encryption or signing will cause autocrypt encryption to turn off. The only exception is when replying to an autocrypt-encrypted email (i.e. an email decrypted from the $autocrypt_dir keyring). Then, if $autocrypt_reply is set, autocrypt mode will be forced on, overriding the settings $crypt_auto_sign, $crypt_auto_encrypt, $crypt_reply_encrypt, $crypt_reply_sign, $crypt_reply_sign_encrypted, and $crypt_opportunistic_encrypt.

When postponing a message, autocrypt will respect $postpone_encrypt, but will use the autocrypt account key to encrypt the message. Be sure to set $postpone_encrypt to ensure postponed messages marked for autocrypt encryption are encrypted.

### 45.4. Account Management

The Autocrypt Account Menu is available from the index via `<autocrypt-acct-menu>`, by default bound to `A`. See Autocrypt Account Menu for the list of functions and their default keybindings.

In this menu, you can create new accounts, delete accounts, toggle an account active/inactive, and toggle the “prefer encryption” flag for an account.

Deleting an account only removes the account from the database. The GPG key is kept, to ensure you still have the ability to read past encrypted emails.

The Autocrypt 1.1 “Setup Message” feature is not available yet, but will be added in the future.

### 45.5. Alternative Key and Keyring Strategies

NeoMutt by default partitions Autocrypt from normal keyring encryption/signing. It does this by using a separate GPG keyring (in $autocrypt_dir) and creating a new ECC key in that keyring for accounts. There are good reasons for doing this by default. It keeps random keys found inside email headers out of your normal keyring. ECC keys are compact and better suited for email headers. Autocrypt key selection is completely different from “web of trust” key selection, based on last-seen rules as opposed to trust and validity. It also allows NeoMutt to distinguish Autocrypt encrypted emails from regular encrypted emails, and set the mode appropriately when replying to each type of email.

Still, some users may want to use an existing key from their normal keyring for Autocrypt too. There are two ways this can be accomplished. The recommended way is to set $autocrypt_dir to your normal keyring directory (e.g. `~/.gnupg`). During account creation, choosing “(s)elect existing GPG key” will then list and allow selecting your existing key for the new account.

An alternative is to copy your key over to the Autocrypt keyring, but there is a severe downside. NeoMutt first tries to decrypt messages using the Autocrypt keyring, and if that fails tries the normal keyring second. This means all encrypted emails to that key will be decrypted, and have signatures verified from, the Autocrypt keyring. Keys signatures and web of trust from your normal keyring will no longer show up in signatures when decrypting.

For that reason, if you want to use an existing key from your normal keyring, it is recommended to just set $autocrypt_dir to `~/.gnupg`. This allows “web of trust” to show an appropriate signature message for verified messages. Autocrypt header keys will be imported into your keyring, but if you don't want them mixed you should strongly consider using a separate autocrypt key and keyring instead.

Both methods have a couple additional caveats:

- Replying to an Autocrypt decrypted message by default forces Autocrypt mode on. By sharing the same key, all replies will then start in Autocrypt mode, even if a message wasn't sent by one of your Autocrypt peers. $autocrypt_reply can be unset to allow manual control of the mode when replying.

- When NeoMutt creates an account from a GPG key, it exports the public key, base64 encodes it, and stores that value in the sqlite3 database. The value is then used in the Autocrypt header added to outgoing emails. The ECC keys NeoMutt creates don't change, but if you use external keys that expire, when you resign to extend the expiration you will need to recreate the Autocrypt account using the account menu. Otherwise the Autocrypt header will contain the old expired exported keydata.

Prev |  | Next
Chapter 5. NeoMutt's MIME Support | Home | Chapter 7. Security Considerations