Chapter 6. Optional Features
Prev |  | Next

# Chapter 6. Optional Features

## 1. General Notes

### 1.1. Enabling/Disabling Features

Mutt 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 `mutt -v`. If a compile option starts with “+” it is enabled and disabled if prefixed with “-”. For example, if Mutt was compiled using GnuTLS for encrypted communication instead of OpenSSL, `mutt -v` would contain:

    -USE_SSL_OPENSSL +USE_SSL_GNUTLS

### 1.2. URL Syntax

Mutt optionally supports the IMAP, POP3 and SMTP protocols which require to access servers using URLs. The canonical syntax for specifying URLs in Mutt 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, Mutt will attempt to establish an encrypted communication using SSL or TLS.

Since all protocols supported by Mutt 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, Mutt 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 Mutt 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 --enable-ssl=... option for OpenSSL or --enable-gnutls=... for GnuTLS). Mutt 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 Mutt'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.

Mutt 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), Mutt will assume the connection to the server through the pipe is already secured. Mutt will ignore $ssl_starttls and $ssl_force_tls, behaving as if TLS has already been negotiated.

When $tunnel_is_secure is unset, Mutt 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

If Mutt is compiled with POP3 support (by running the configure script with the --enable-pop flag), it 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.

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

POP is read-only which doesn't allow for some features like editing messages or changing flags. However, using Section 8.1, “Header Caching” and Section 8.2, “Body Caching” Mutt simulates the new/old/read flags as well as flagged and replied. Mutt 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 POP server (either by Mutt or other tools).

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 $spoolfile. After this point, Mutt runs exactly as if the mail had always been local.

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

## 4. IMAP Support

If Mutt was compiled with IMAP support (by running the configure script with the --enable-imap flag), it 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. Mutt should correctly notice which separator is being used by the server and convert paths accordingly.

When browsing folders on an IMAP server, you can toggle whether to look at only the folders you are subscribed to, or all folders with the toggle-subscribed command. See also the $imap_list_subscribed variable.

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, Mutt 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, Mutt 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

Mutt supports four authentication methods with IMAP servers: SASL, GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add NTLM authentication for you poor exchange users out there, but it has yet to be integrated into the main tree). 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 Mutt with the --with-sasl flag.

Mutt 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 Mutt's default (attempt everything, in the order listed above).

## 5. SMTP Support

Besides supporting traditional mail delivery through a sendmail-compatible program, Mutt supports delivery through SMTP if it was configured and built with `--enable-smtp`.

If the configuration variable $smtp_url is set, Mutt will contact the given SMTP server to deliver messages; if it is unset, Mutt 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 Mutt try all available methods from most-secure to least-secure.

## 6. OAUTHBEARER 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 mutt 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]"

Substitute pop or smtp for imap in the above example to configure for those.

An alternative script is contrib/mutt_oauth2.py script. For more details see contrib/mutt_oauth2.py.README.

### 6.1. XOAUTH2 Support

Support for the deprecated XOAUTH2 protocol is also available. To enable this, add “xoauth2” to the $imap_authenticators, $pop_authenticators, or $smtp_authenticators config variables. XOAUTH2 uses the same refresh command configuration variables as OAUTHBEARER: $imap_oauth_refresh_command, $pop_oauth_refresh_command, and $smtp_oauth_refresh_command. Those will need to be set to a script to generate the appropriate XOAUTH2 token.

## 7. Managing Multiple Accounts

Usage:

`account-hook` `regexp` `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 Mutt 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/libexec/imapd"'
    account-hook smtp://user@host3/ 'set tunnel="ssh host3 /usr/libexec/smtpd"'

To manage multiple accounts with, for example, different values of $record or sender addresses, folder-hook has to 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 Mutt 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

Mutt 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 Mutt is compiled with POP and/or IMAP support as these use it (body caching requires no external library).

### 8.1. Header Caching

Mutt 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 via the configure script and the --enable-hcache option. It's not turned on by default because external database libraries are required: one of tokyocabinet, kyotocabinet, lmdb, qdbm, gdbm or bdb must be present.

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. When pointing to a directory, be sure to create the directory in advance, or Mutt will interpret it as a file to be created.

### 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, Mutt 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_cachedir must point to a directory. There, Mutt 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_cachedir can be safely set to the same value.

In a header or body cache directory, Mutt creates a directory hierarchy named like: `proto:user@hostname` where `proto` is either “pop” or “imap.” Within there, for each folder, Mutt 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 Mutt 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

Mutt 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, Mutt 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 Mutt using a different body cache location delete messages (Mutt 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. Exact Address Generation

Mutt supports the “Name <user@host>” address syntax for reading and writing messages, the older “user@host (Name)” syntax is only supported when reading messages. The --enable-exact-address switch can be given to configure to build it with write-support for the latter syntax. `EXACT_ADDRESS` in the output of `mutt -v` indicates whether it's supported.

Note: If the full address contains non-ascii characters, or sequences that require RFC 2047 encoding, Mutt reverts to writing out the normalized “Name <user@host>” form, in order to generate legal output.

## 10. Sending Anonymous Messages via Mixmaster

You may also have compiled Mutt to co-operate with Mixmaster, an anonymous remailer. Mixmaster permits you to send your messages anonymously using a chain of remailers. Mixmaster support in Mutt is for mixmaster version 2.04 or later.

To use it, you'll have to obey certain restrictions. Most important, you cannot use the `Cc` and `Bcc` headers. To tell Mutt to use mixmaster, you have to select a remailer chain, using the mix function on the compose menu.

The chain selection screen is divided into two parts. In the (larger) upper part, you get a list of remailers you may use. In the lower part, you see the currently selected chain of remailers.

You can navigate in the chain using the `<chain-prev>` and `<chain-next>` functions, which are by default bound to the left and right arrows and to the `h` and `l` keys (think vi keyboard bindings). To insert a remailer at the current chain position, use the `<insert>` function. To append a remailer behind the current chain position, use `<select-entry>` or `<append>`. You can also delete entries from the chain, using the corresponding function. Finally, to abandon your changes, leave the menu, or `<accept>` them pressing (by default) the `Return` key.

Note that different remailers do have different capabilities, indicated in the %c entry of the remailer menu lines (see $mix_entry_format). Most important is the “middleman” capability, indicated by a capital “M”: This means that the remailer in question cannot be used as the final element of a chain, but will only forward messages to other mixmaster remailers. For details on the other capabilities, please have a look at the mixmaster documentation.

## 11. Sidebar

### Overview of mailboxes

### 11.1. 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.

### 11.2. Variables

Table 6.1. Sidebar Variables

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

### 11.3. Functions

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

Table 6.2. 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

### 11.4. Commands

`sidebar_whitelist` `mailbox` [ `mailbox` ...]
`unsidebar_whitelist` { `*` | `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 “unsidebar_whitelist” command is used to remove a mailbox from the list of whitelisted mailboxes. Use “unsidebar_whitelist *” to remove all mailboxes.

### 11.5. Colors

Table 6.3. Sidebar Colors

Name | Default Color | Description
--- | --- | ---
`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` | mutt `indicator` | The mailbox open in the Index panel
`sidebar_new` | default | Mailboxes containing new mail
`sidebar_spoolfile` | default | Mailbox that receives incoming mail

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

### 11.6. Sort

Table 6.4. Sidebar Sort

Sort | Description
--- | ---
`alpha` | Alphabetically by path or label
`count` | Total number of messages
`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` | Do not resort the paths

### 11.7. See Also

- Regular Expressions

- Patterns

- Color command

## 12. Compressed Folders Feature

### Read from/write to compressed mailboxes

### 12.1. Introduction

The Compressed Folder patch allows Mutt 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 Mutt can read it.

The patch adds three hooks to Mutt: `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.

### 12.2. Commands

`open-hook` `pattern` `shell-command`
`close-hook` `pattern` `shell-command`
`append-hook` `pattern` `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.5. 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

#### 12.2.1. Read from compressed mailbox

    open-hook regexp shell-command

If Mutt 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 regexp.

Example 6.3. Example of open-hook

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

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

- Mutt has an `open-hook` whose regexp matches the filename: `\.gz$`

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

#### 12.2.2. Write to a compressed mailbox

    close-hook regexp shell-command

When Mutt 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 -c '%t' > '%f'"

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

- The folder has been modified

- Mutt has a `close-hook` whose regexp matches the filename: `\.gz$`

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

#### 12.2.3. Append to a compressed mailbox

    append-hook regexp shell-command

When Mutt 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 Mutt won't be able to determine the type of the mail folder inside the compressed file.

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

Mutt 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 -c '%t' >> '%f'"

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

- Mutt has an `append-hook` whose regexp matches the filename: `\.gz$`

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

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

#### 12.2.4. Empty Files

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

#### 12.2.5. Security

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

## 13. Autocrypt

Mutt can be compiled with Autocrypt support by running `configure` with the `--enable-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/.

### 13.1. Requirements

Autocrypt requires support for ECC cryptography, and Mutt by default will generate ECC keys. Therefore GnuPG 2.1 or greater is required. Additionally, Mutt'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 Mutt must be configured with the `--with-sqlite3` flag when autocrypt is enabled.

It is highly recommended Mutt be configured `--with-idn` or `--with-idn2` so that Autocrypt can properly deal with international domain names.

While Mutt 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).

### 13.2. First Run

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

Mutt 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 Mutt is running. The database is created (if necessary) and connected to during startup. Changing the variable can result in a situation where Mutt 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, Mutt 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, Mutt 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, Mutt disables all macros during the first run.

### 13.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_autosign, $crypt_autoencrypt, $crypt_replyencrypt, $crypt_replysign, $crypt_replysignencrypted, 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.

### 13.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.

### 13.5. Alternative Key and Keyring Strategies

Mutt 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 Mutt 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. Mutt 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 Mutt 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 Mutt 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. Mutt's MIME Support | Home | Chapter 7. Security Considerations