Chapter 2. Getting Started

The index is the screen that you usually see first when you start NeoMutt. It gives an overview over your emails in the currently opened mailbox. By default, this is your system mailbox. The information you see in the index is a list of emails, each with its number on the left, its flags (new email, important email, email that has been forwarded or replied to, tagged email, ...), the date when email was sent, its sender, the email size, and the subject. Additionally, the index also shows thread hierarchies: when you reply to an email, and the other person replies back, you can see the other person's email in a "sub-tree" below. This is especially useful for personal email between a group of people or when you've subscribed to mailing lists.

The pager is responsible for showing the email content. On the top of the pager you have an overview over the most important email headers like the sender, the recipient, the subject, and much more information. How much information you actually see depends on your configuration, which we'll describe below.

Below the headers, you see the email body which usually contains the message. If the email contains any attachments, you will see more information about them below the email body, or, if the attachments are text files, you can view them directly in the pager.

To give the user a good overview, it is possible to configure NeoMutt to show different things in the pager with different colors. Virtually everything that can be described with a regular expression can be colored, e.g. URLs, email addresses or smileys.

The file browser is the interface to the local or remote file system. When selecting a mailbox to open, the browser allows custom sorting of items, limiting the items shown by a regular expression and a freely adjustable format of what to display in which way. It also allows for easy navigation through the file system when selecting file(s) to attach to a message, select multiple files to attach and many more.

Some mail systems can nest mail folders inside other mail folders. The normal open entry commands in NeoMutt will open the mail folder and you can't see the sub-folders. If you instead use the <descend-directory> function it will go into the directory and not open it as a mail directory.

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 suitable for beginners. If you already know NeoMutt you could skip ahead to the main Sidebar guide. If you just want to get started, you could use the sample Sidebar neomuttrc.

Let's turn on the Sidebar:

set sidebar_visible
set sidebar_format = "%B%<F? [%F]>%* %<N?%N/>%S"
set mail_check_stats

You will see something like this. A list of mailboxes on the left. A list of emails, from the selected mailbox, on the right.

Fruit [1]     3/8|  1    + Jan 24  Rhys Lee         (192)  Yew
Animals [1]   2/6|  2    + Feb 11  Grace Hall       (167)  Ilama
Cars            4|  3      Feb 23  Aimee Scott      (450)  Nectarine
Seas          1/7|  4    ! Feb 28  Summer Jackson   (264)  Lemon
                 |  5      Mar 07  Callum Harrison  (464)  Raspberry
                 |  6 N  + Mar 24  Samuel Harris    (353)  Tangerine          
                 |  7 N  + Sep 05  Sofia Graham     (335)  Cherry
                 |  8 N    Sep 16  Ewan Brown       (105)  Ugli
                 |
                 |

This user has four mailboxes: “Fruit”, “Cars”, “Animals” and “Seas”.

The current, open, mailbox is “Fruit”. We can also see information about the other mailboxes. For example: The “Animals” mailbox contains, 1 flagged email, 2 new emails out of a total of 6 emails.

Fruit [1]     3/8|  1      Jan 03  Tia Gibson       (362)  Caiman
Animals [1]   2/6|  2    + Jan 22  Rhys Lee         ( 48)  Dolphin
Cars            4|  3    ! Aug 16  Ewan Brown       (333)  Hummingbird
Seas          1/7|  4      Sep 25  Grace Hall       ( 27)  Capybara
                 |  5 N  + Nov 12  Evelyn Rogers    (453)  Tapir              
                 |  6 N  + Nov 16  Callum Harrison  (498)  Hedgehog
                 |
                 |
                 |
                 |

bind index,pager \CP sidebar-prev       # Ctrl-P – Previous Mailbox
bind index,pager \CN sidebar-next       # Ctrl-N – Next Mailbox
bind index,pager \CO sidebar-open       # Ctrl-O – Open Highlighted Mailbox

Fruit [1]     3/8|  1      Jan 03  Tia Gibson       (362)  Caiman
Animals [1]   2/6|  2    + Jan 22  Rhys Lee         ( 48)  Dolphin
Cars            4|  3    ! Aug 16  Ewan Brown       (333)  Hummingbird
Seas          1/7|  4      Sep 25  Grace Hall       ( 27)  Capybara
                 |  5 N  + Nov 12  Evelyn Rogers    (453)  Tapir              
                 |  6 N  + Nov 16  Callum Harrison  (498)  Hedgehog
                 |
                 |
                 |
                 |

Fruit [1]     3/8|  1    ! Mar 07  Finley Jones     (139)  Molucca Sea
Animals [1]   2/6|  2    + Mar 24  Summer Jackson   ( 25)  Arafura Sea
Cars            4|  3    + Feb 28  Imogen Baker     (193)  Pechora Sea
Seas          1/7|  4 N  + Feb 23  Isla Hussain     (348)  Balearic Sea       
                 |
                 |
                 |
                 |
                 |
                 |

set sidebar_visible                         # Make the Sidebar visible by default
bind index,pager B sidebar-toggle-visible   # Use 'B' to switch the Sidebar on and off

set sidebar_width = 25                  # Plenty of space
set sidebar_divider_char = '│'          # Pretty line-drawing character

set mail_check_stats

mailbox [F]            N/S 

mailbox              F:N:S 

mailbox (N)              S 

mailbox                F/S 

set folder="~/mail"
mailboxes =fruit/apple          =fruit/banana          =fruit/cherry
mailboxes =water/sea/sicily     =water/sea/archipelago =water/sea/sibuyan
mailboxes =water/ocean/atlantic =water/ocean/pacific   =water/ocean/arctic

set sidebar_short_path                  # Shorten mailbox names (truncate all subdirs)
set sidebar_component_depth=1           # Shorten mailbox names (truncate 1 subdirs)
set sidebar_delim_chars="/"             # Delete everything up to the last or Nth / character

|fruit/apple                            |apple
|fruit/banana                           |banana
|fruit/cherry                           |cherry
|water/sea/sicily                       |sicily
|water/sea/archipelago                  |archipelago
|water/sea/sibuyan                      |sibuyan
|water/ocean/atlantic                   |atlantic
|water/ocean/pacific                    |pacific
|water/ocean/arctic                     |arctic

|fruit/apple                            |apple
|fruit/banana                           |banana
|fruit/cherry                           |cherry
|water/sea/sicily                       |sea/sicily
|water/sea/archipelago                  |sea/archipelago
|water/sea/sibuyan                      |sea/sibuyan
|water/ocean/atlantic                   |ocean/atlantic
|water/ocean/pacific                    |ocean/pacific
|water/ocean/arctic                     |ocean/arctic

set folder="~/mail"
mailboxes =fruit
mailboxes =fruit/apple =fruit/banana =fruit/cherry
mailboxes =water
mailboxes =water/sea
mailboxes =water/sea/sicily =water/sea/archipelago =water/sea/sibuyan
mailboxes =water/ocean
mailboxes =water/ocean/atlantic =water/ocean/pacific =water/ocean/arctic

set sidebar_short_path                  # Shorten mailbox names
set sidebar_delim_chars="/"             # Delete everything up to the last / character
set sidebar_folder_indent               # Indent folders whose names we've shortened
set sidebar_indent_string="  "          # Indent with two spaces

|fruit                                  |fruit
|fruit/apple                            |  apple
|fruit/banana                           |  banana
|fruit/cherry                           |  cherry
|water                                  |water
|water/sea                              |  sea
|water/sea/sicily                       |    sicily
|water/sea/archipelago                  |    archipelago
|water/sea/sibuyan                      |    sibuyan
|water/ocean                            |  ocean
|water/ocean/atlantic                   |    atlantic
|water/ocean/pacific                    |    pacific
|water/ocean/arctic                     |    arctic

set sidebar_new_mail_only         # Only mailboxes with new/flagged email
sidebar_pin +fruit +fruit/apple   # Always display these two mailboxes

color sidebar_background default black       # Black background
color sidebar_indicator  default color17     # Dark blue background
color sidebar_highlight  white   color238    # Grey background
color sidebar_spool_file yellow  default     # Yellow
color sidebar_unread     cyan    default     # Light blue
color sidebar_new        green   default     # Green
color sidebar_ordinary   default default     # Default colors
color sidebar_flagged    red     default     # Red
color sidebar_divider    color8  default     # Dark grey

The help screen is meant to offer a quick help to the user. It lists the current configuration of key bindings and their associated commands including a short description, and currently unbound functions that still need to be associated with a key binding (or alternatively, they can be called via the NeoMutt command prompt).

The compose menu features a split screen containing the information which really matters before actually sending a message by mail: who gets the message as what (recipients and who gets what kind of copy). Additionally, users may set security options like deciding whether to sign, encrypt or sign and encrypt a message with/for what keys. Also, it's used to attach messages, to re-edit any attachment including the message itself.

The alias menu is used to help users finding the recipients of messages. For users who need to contact many people, there's no need to remember addresses or names completely because it allows for searching, too. The alias mechanism and thus the alias menu also features grouping several addresses by a shorter nickname, the actual alias, so that users don't have to select each single recipient manually. The alias menu is also used to display the result of external address queries.

As will be later discussed in detail, NeoMutt features a good and stable MIME implementation, that is, it supports sending and receiving messages of arbitrary MIME types. The attachment menu displays a message's structure in detail: what content parts are attached to which parent part (which gives a true tree structure), which part is of what type and what size. Single parts may saved, deleted or modified to offer great and easy access to message's internals.

NeoMutt has a built-in line editor for inputting text, e.g. email addresses or filenames. The keys used to manipulate text input are very similar to those of Emacs. See Table 2.6, “Most common line editor keys” for a full reference of available functions, their default key bindings, and short descriptions.

^G is the generic “abort” key in NeoMutt. In addition to the line editor, it can also be used to abort prompts. Generally, typing ^G at a confirmation prompt or line editor should abort the entire action.

You can remap the editor functions using the bind command. For example, to make the <Delete> key delete the character in front of the cursor rather than under, you could use:

bind editor <delete> backspace

NeoMutt maintains a history for the built-in editor. The number of items is controlled by the $history variable and can be made persistent using an external file specified using $history_file and $save_history. You may cycle through them at an editor prompt by using the <history-up> and/or <history-down> commands. NeoMutt will remember the currently entered text as you cycle through history, and will wrap around to the initial entry line.

NeoMutt maintains several distinct history lists, one for each of the following categories:

NeoMutt automatically filters out consecutively repeated items from the history. If $history_remove_dups is set, all repeated items are removed from the history. It also mimics the behavior of some shells by ignoring items starting with a space. The latter feature can be useful in macros to not clobber the history's valuable entries with unwanted entries.

Common keys used to navigate through and manage messages in the index are shown in Table 2.7, “Most common message index keys”. How messages are presented in the index menu can be customized using the $index_format variable.

In addition to who sent the message and the subject, a short summary of the disposition of each message is printed beside the message number. Zero or more of the “flags” in Table 2.8, “Message status flags” may appear, some of which can be turned on or off using these functions: <set-flag> and <clear-flag> bound by default to “w” and “W” respectively.

Furthermore, the flags in Table 2.9, “Message recipient flags” reflect who the message is addressed to. They can be customized with the $to_chars variable.

By default, NeoMutt uses its built-in pager to display the contents of messages (an external pager such as less(1) can be configured, see $pager variable). The pager is very similar to the Unix program less(1) though not nearly as featureful.

In addition to key bindings in Table 2.10, “Most common pager keys”, many of the functions from the index menu are also available in the pager, such as <delete-message> or <copy-message> (this is one advantage over using an external pager to view messages).

Also, the internal pager supports a couple other advanced features. For one, you can set $pager_read_delay to operate in a preview mode, where new messages are not marked read unless you remain on the message for a certain length of time. Additionally, it will accept and translate the “standard” nroff sequences for bold and underline. These sequences are a series of either the letter, backspace (“^H”), the letter again for bold or the letter, backspace, “_” for denoting underline. NeoMutt will attempt to display these in bold and underline respectively if your terminal supports them. If not, you can use the bold and underline color objects to specify a color or mono attribute for them.

Additionally, the internal pager supports the ANSI escape sequences for character attributes. NeoMutt translates them into the correct color and character settings. The sequences NeoMutt supports are:

\e[ Ps; Ps; ...  Ps;m

where Ps can be one of the codes shown in Table 2.11, “ANSI escape sequences”.

NeoMutt uses these attributes for handling text/enriched messages, and they can also be used by an external autoview script for highlighting purposes.

So-called “threads” provide a hierarchy of messages where replies are linked to their parent message(s). This organizational form is extremely useful in mailing lists where different parts of the discussion diverge. NeoMutt displays threads as a tree structure.

In NeoMutt, when a mailbox is sorted by threads, there are a few additional functions available in the index and pager modes as shown in Table 2.13, “Most common thread mode keys”.

In the index, the subject of threaded children messages will be prepended with thread tree characters. By default, the subject itself will not be duplicated unless $hide_thread_subject is unset. Special characters will be added to the thread tree as detailed in Table 2.14, “Special Thread Characters”.

Collapsing a thread displays only the first message in the thread and hides the others. This is useful when threads contain so many messages that you can only see a handful of threads on the screen. See %M in $index_format. For example, you could use %<M?(#%03M)&(%4l)> in $index_format to optionally display the number of hidden messages if the thread is collapsed. The %<char?if-part&else-part> syntax is explained in detail in format string conditionals.

Technically, every reply should contain a list of its parent messages in the thread tree, but not all do. In these cases, NeoMutt groups them by subject which can be controlled using the $strict_threads variable.

In addition, the index and pager menus have these interesting functions:

The bindings shown in Table 2.15, “Most common mail sending keys” are available in the index and pager to start a new message.

Bouncing a message sends the message as-is to the recipient you specify. Forwarding a message allows you to add comments or modify the message you are forwarding. These items are discussed in greater detail in the next section “Forwarding and Bouncing Mail”.

NeoMutt will then enter the compose menu and prompt you for the recipients to place on the “To:” header field when you hit m to start a new message. Next, it will ask you for the “Subject:” field for the message, providing a default if you are replying to or forwarding a message. You again have the chance to adjust recipients, subject, and security settings right before actually sending the message. See also $ask_cc, $ask_bcc, $auto_edit, $bounce, $fast_reply, and $include for changing how and if NeoMutt asks these questions.

When replying, NeoMutt fills these fields with proper values depending on the reply type. The types of replying supported are:

After getting recipients for new messages, forwards or replies, NeoMutt will then automatically start your $editor on the message body. If the $edit_headers variable is set, the headers will be at the top of the message in your editor; the message body should start on a new line after the existing blank line at the end of headers. Any messages you are replying to will be added in sort order to the message, with appropriate $attribution_intro, $indent_string and $attribution_trailer. When forwarding a message, if the $mime_forward variable is unset, a copy of the forwarded message will be included. If you have specified a $signature, it will be appended to the message.

Once you have finished editing the body of your mail message, you are returned to the compose menu providing the functions shown in Table 2.16, “Most common compose menu keys” to modify, send or postpone the message.

The compose menu is also used to edit the attachments for a message which can be either files or other messages. The <attach-message> function to will prompt you for a folder to attach messages from. You can now tag messages in that folder and they will be attached to the message you are sending.

After exiting the compose menu via <send-message>, the message will be sent. This happens via $smtp_url. Otherwise $sendmail will be invoked. Prior to version 2019-11-29, NeoMutt enabled $write_bcc by default, assuming the MTA would automatically remove a Bcc: header as part of delivery. Starting with 2019-11-29, the option is unset by default, but no longer affects the fcc copy of the message.

When editing the header because of $edit_headers being set, there are a several pseudo headers available which will not be included in sent messages but trigger special NeoMutt behavior.

If you have told NeoMutt to PGP or S/MIME encrypt a message, it will guide you through a key selection process when you try to send the message. NeoMutt will not ask you any questions about keys which have a certified user ID matching one of the message recipients' mail addresses. However, there may be situations in which there are several keys, weakly certified user ID fields, or where no matching keys can be found.

In these cases, you are dropped into a menu with a list of keys from which you can select one. When you quit this menu, or NeoMutt can't find any matching keys, you are prompted for a user ID. You can, as usually, abort this prompt using ^G. When you do so, NeoMutt will return to the compose screen.

Once you have successfully finished the key selection, the message will be encrypted using the selected public keys when sent out.

To ensure you can view encrypted messages you have sent, you may wish to set $pgp_self_encrypt and $pgp_default_key for PGP, or $smime_self_encrypt and $smime_default_key for S/MIME.

Most fields of the entries in the key selection menu (see also $pgp_entry_format) have obvious meanings. But some explanations on the capabilities, flags, and validity fields are in order.

The flags sequence (“%f”) will expand to one of the flags in Table 2.17, “PGP key menu flags”.

The capabilities field (“%c”) expands to a two-character sequence representing a key's capabilities. The first character gives the key's encryption capabilities: A minus sign (“-”) means that the key cannot be used for encryption. A dot (“.”) means that it's marked as a signature key in one of the user IDs, but may also be used for encryption. The letter “e” indicates that this key can be used for encryption.

The second character indicates the key's signing capabilities. Once again, a “-” implies “not for signing”, “.” implies that the key is marked as an encryption key in one of the user-ids, and “s” denotes a key which can be used for signing.

Finally, the validity field (“%t”) indicates how well-certified a user-id is. Its values depend on the backend used. Note that S/MIME (which uses X509 certificates) has no concept of validity, so this field simply shows x. The possible values listed in Table 2.18, “PGP key menu validity”.

The two most important settings are $pgp_default_key and $pgp_sign_as. To perform encryption, you must set the first variable. If you have a separate signing key, or only have a signing key, then set the second. Most people will only need to set $pgp_default_key.

Starting with version 2.1.0, GnuPG automatically uses an agent to prompt for your passphrase. If you are using a version older than that, you'll need to ensure an agent is running (alternatively, you can unset $pgp_use_gpg_agent and NeoMutt will prompt you for your passphrase). The agent in turn uses a pinentry program to display the prompt. There are many different kinds of pinentry programs that can be used: qt, gtk2, gnome3, fltk, and curses. However, NeoMutt does not work properly with the tty pinentry program. Please ensure you have one of the GUI or curses pinentry programs installed and configured to be the default for your system.

As with OpenPGP, the two most important settings are $smime_default_key and $smime_sign_as. To perform encryption and decryption, you must set the first variable. If you have a separate signing key, or only have a signing key, then set the second. Most people will only need to set $smime_default_key.

When using GPGME as S/MIME backend, keys and certificates are managed by GnuPG. You can add your key (or certificates) to GnuPG with the command “gpgsm --import mykey.p12”. Note that in order to use the key for signing or encrypting, the root certificate of that key must be trusted, which might involve editing ~/.gnupg/trustlist.txt. Consult your documentation of GnuPG for details, in particular gpgsm.

In “classic mode”, keys and certificates are managed by the smime_keys program that comes with NeoMutt. By default they are stored under ~/.smime/. (This is set by the smime.rc file with $smime_certificates and $smime_keys.) To initialize this directory, use the command “smime_keys init” from a shell prompt. The program can be then be used to import and list certificates. You may also want to periodically run “smime_keys refresh” to update status flags for your certificates.