Getting Started

This section is intended as a brief overview of how to use NeoMutt. There are many other features which are described elsewhere in the manual. There is even more information available in the NeoMutt FAQ and various web pages. See the NeoMutt homepage for more details.

The keybindings described in this section are the defaults as distributed. Your local system administrator may have altered the defaults for your site. You can always type ? in any menu to display the current bindings.

The first thing you need to do is invoke NeoMutt, simply by typing neomutt at the command line. There are various command-line options, see either the NeoMutt man page or the reference.

1. Core Concepts

NeoMutt is a text-based application which interacts with users through different menus which are mostly line-/entry-based or page-based. A line-based menu is the so-called index menu (listing all messages of the currently opened folder) or the alias menu (allowing you to select recipients from a list). Examples for page-based menus are the pager(showing one message at a time) or the help menu listing all available key bindings.

The user interface consists of a context sensitive help line at the top, the menu's contents followed by a context sensitive status line and finally the command line. The command line is used to display informational and error messages as well as for prompts and for entering interactive commands.

NeoMutt is configured through variables which, if the user wants to permanently use a non-default value, are written to configuration files. NeoMutt supports a rich config file syntax to make even complex configuration files readable and commentable.

Because NeoMutt allows for customizing almost all key bindings, there are so-called functions which can be executed manually (using the command line) or in macros. Macros allow the user to bind a sequence of commands to a single key or a short key sequence instead of repeating a sequence of actions over and over.

Many commands (such as saving or copying a message to another folder) can be applied to a single message or a set of messages (so-called tagged messages). To help selecting messages, NeoMutt provides a rich set of message patterns (such as recipients, sender, body contents, date sent/received, etc.) which can be combined into complex expressions using the boolean and and or operations as well as negating. These patterns can also be used to (for example) search for messages or to limit the index to show only matching messages.

NeoMutt supports a hook concept which allows the user to execute arbitrary configuration commands and functions in certain situations such as entering a folder, starting a new message or replying to an existing one. These hooks can be used to highly customize NeoMutt's behavior including managing multiple identities, customizing the display for a folder or even implementing auto-archiving based on a per-folder basis and much more.

Besides an interactive mode, NeoMutt can also be used as a command-line tool to send messages. See Table 45.1, “Command line options” for a complete list of command-line options.

2. Screens and Menus

2.1. Index

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.

2.2. Pager

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.

2.3. File Browser

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.

2.4. Sidebar

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.

To check if NeoMutt supports Sidebar, look for the string +sidebar in the neomutt version.

neomutt -v

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.

2.4.1. Navigation

The Sidebar adds some new functions to NeoMutt.

The user pressed the c key to <change-folder> to the Animals mailbox. The Sidebar automatically updated the indicator to match.

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

Let's map some functions:

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

Pressing Ctrl-N(Next mailbox) twice will move the Sidebar highlight to down to the Seas 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


Functions <sidebar-next> and <sidebar-prev> move the Sidebar highlight . They do not change the open mailbox.

Press Ctrl-O( <sidebar-open> ) to open the highlighted mailbox.

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       

2.4.2. Features

The Sidebar shows a list of mailboxes in a panel.

Everything about the Sidebar can be configured.

State of the Sidebar

  • Visibility

  • Width

Which mailboxes are displayed

  • Display all

  • Limit to mailboxes with new mail

  • Pin mailboxes to display always

The order in which mailboxes are displayed

  • Unsorted (order of mailboxes commands)

  • Sorted alphabetically

  • Sorted by number of new mails


  • Sidebar indicators and divider

  • Mailboxes depending on their type

  • Mailboxes depending on their contents

Key bindings

  • Hide/Unhide the Sidebar

  • Select previous/next mailbox

  • Select previous/next mailbox with new mail

  • Page up/down through a list of mailboxes

2.4.3. Display

Everything about the Sidebar can be configured. Sidebar Basics

The most important variable is $sidebar_visible. You can set this in your neomuttrc, or bind a key to the function <sidebar-toggle-visible>.

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

Next, decide how wide you want the Sidebar to be. 25 characters might be enough for the mailbox name and some numbers. Remember, you can hide/show the Sidebar at the press of button.

Finally, you might want to change the divider character. By default, Sidebar draws an ASCII line between it and the Index panel. If your terminal supports it, you can use a Unicode line-drawing character.

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

$sidebar_format allows you to customize the Sidebar display. For an introduction, read format strings including the section about conditionals.

The default value is: %D%* %n

A more detailed value is: %B%<F? [%F]>%* %<N?%N/>%S

Which breaks down as:

  • %B – Mailbox name

  • %<F? [%F]> – If flagged emails [%F], otherwise nothing

  • %* – Pad with spaces

  • %<N?%N/> – If new emails %N/, otherwise nothing

  • %S – Total number of emails

Table 2.1. sidebar_format

Format Notes Description
%B   Name of the mailbox
%d * ‡ Number of deleted messages
%D   Descriptive name of the mailbox
%F * † Number of flagged messages in the mailbox
%L * ‡ Number of messages after limiting
%n * If there's new mail, display N, otherwise (space).
%N * † Number of unread messages in the mailbox (seen or unseen)
%o * † Number of old messages in the mailbox (unread, but seen)
%r * † Number of read messages in the mailbox
%S * † Size of mailbox (total number of messages)
%t * ‡ Number of tagged messages in the mailbox
%Z * † Number of new messages in the mailbox (unread, unseen)
%!   !: one flagged message; !!: two flagged messages; n!: n flagged messages (for n > 2). Otherwise prints nothing.
%>X   Right justify the rest of the string and pad with X
%|X   Pad to the end of the line with X
%*X   Soft-fill with character X as pad

* = Can be optionally printed if nonzero

† = To use these expandos, you must first:

set mail_check_stats

‡ = Only applicable to the current folder

Here are some examples. They show the number of (F)lagged, (N)ew and (S)ize.

Table 2.2. sidebar_format examples

Format Example
%B%<F? [%F]>%* %<N?%N/>%S
mailbox [F]            N/S
%B%* %F:%N:%S
mailbox              F:N:S
%B %<N?(%N)>%* %S
mailbox (N)              S
%B%* %<F?%F/>%N
mailbox                F/S Abbreviating Mailbox Names

$sidebar_delim_chars tells Sidebar how to split up mailbox paths. For local directories use /; for IMAP folders use . Example 1

This example works well if your mailboxes have unique names after the last separator.

Add some mailboxes of different depths.

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

Shorten the names:

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

The screenshot below shows what the Sidebar would look like before and after shortening using sidebar_short_path.

|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

The screenshot below shows what the Sidebar would look like before and after shortening using sidebar_component_depth=1.

|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 Example 2

This example works well if you have lots of mailboxes which are arranged in a tree.

Add some mailboxes of different depths.

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

Shorten the names:

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

The screenshot below shows what the Sidebar would look like before and after shortening.

|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

Sometimes, it will be necessary to add mailboxes, that you don't use, to fill in part of the tree. This will trade vertical space for horizontal space (but it looks good). Limiting the Number of Mailboxes

If you have a lot of mailboxes, sometimes it can be useful to hide the ones you aren't using. $sidebar_new_mail_only tells Sidebar to only show mailboxes that contain new, or flagged, email.

Sometimes it is useful to only show mailboxes that have mails in them, while hiding the rest. $sidebar_non_empty_mailbox_only tells the Sidebar to only show mailboxes with a non-zero number of mails.

If you want some mailboxes to be always visible, then use the sidebar_pin command. It takes a list of mailboxes as parameters.

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

2.4.4. Colors

Here is a sample color scheme:

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

There is a priority order when coloring Sidebar mailboxes. e.g. If a mailbox has new mail it will have the sidebar_new color, even if it also contains flagged mails.

Table 2.3. Sidebar Color Priority

Priority Color Description
Highest sidebar_indicator Mailbox is open
  sidebar_highlight Mailbox is highlighted
  sidebar_new Mailbox contains new mail
  sidebar_unread Mailbox contains unread mail
  sidebar_flagged Mailbox contains flagged mail
  sidebar_spool_file Mailbox is the spool_file (receives incoming mail)
Lowest sidebar_ordinary Mailbox does not match above

2.5. Help

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

2.6. Compose Menu

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.

2.7. Alias Menu

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.

2.8. Attachment Menu

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.

3. Moving Around in Menus

The most important navigation keys common to line- or entry-based menus are shown in Table 2.4, “Most common navigation keys in entry-based menus” and in Table 2.5, “Most common navigation keys in page-based menus” for page-based menus.

Table 2.4. Most common navigation keys in entry-based menus

Key Function Description
j or <Down> <next-entry> move to the next entry
k or <Up> <previous-entry> move to the previous entry
z or <PageDn> <page-down> go to the next page
Z or <PageUp> <page-up> go to the previous page
= or <Home> <first-entry> jump to the first entry
* or <End> <last-entry> jump to the last entry
q <quit> exit the current menu
? <help> list all keybindings for the current menu

Table 2.5. Most common navigation keys in page-based menus

Key Function Description
J or <Return> <next-line> scroll down one line
<Backspace> <previous-line> scroll up one line
K, <Space> or <PageDn> <next-page> move to the next page
- or <PageUp> <previous-page> move the previous page
<Home> <top> move to the top
<End> <bottom> move to the bottom

4. Editing Input Fields

4.1. Introduction

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.

Table 2.6. Most common line editor keys

Key Function Description
^A or <Home> <bol> move to the start of the line
^B or <Left> <backward-char> move back one char
Esc B <backward-word> move back one word
^D or <Delete> <delete-char> delete the char under the cursor
^E or <End> <eol> move to the end of the line
^F or <Right> <forward-char> move forward one char
Esc F <forward-word> move forward one word
<Tab> <complete> complete filename, alias, or label
^T <complete-query> complete address with query
^K <kill-eol> delete to the end of the line
Esc d <kill-eow> delete to the end of the word
^W <kill-word> kill the word in front of the cursor
^U <kill-line> delete entire line
^V <quote-char> quote the next typed key
<Up> <history-up> recall previous string from history
<Down> <history-down> recall next string from history
^R <history-search> use current input to search history
<BackSpace> <backspace> kill the char in front of the cursor
Esc u <upcase-word> convert word to upper case
Esc l <downcase-word> convert word to lower case
Esc c <capitalize-word> capitalize the word
^G n/a abort
<Return> n/a finish editing

^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

4.2. History

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:

  • .neomuttrc commands

  • addresses and aliases

  • shell commands

  • mailboxes

  • filenames

  • patterns

  • everything else

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.

5. Reading Mail

Similar to many other mail clients, there are two modes in which mail is read in NeoMutt. The first is a list of messages in the mailbox, which is called the index menu in NeoMutt. The second mode is the display of the message contents. This is called the pager.

The next few sections describe the functions provided in each of these modes.

5.1. The Message Index

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.

Table 2.7. Most common message index keys

Key Description
c change to a different mailbox
Esc c change to a folder in read-only mode
C copy the current message to another mailbox
Esc C decode a message and copy it to a folder
Esc s decode a message and save it to a folder
D delete messages matching a pattern
d delete the current message
F mark as important
l show messages matching a pattern
N mark message as new
o change the current sort method
O reverse sort the mailbox
q save changes and exit
s save-message
T tag messages matching a pattern
t toggle the tag on a message
Esc t toggle tag on entire message thread
U undelete messages matching a pattern
u undelete-message
v view-attachments
x abort changes and exit
<Return> display-message
<Tab> jump to the next new or unread message
@ show the author's full e-mail address
$ save changes to mailbox
/ search
Esc / search-reverse
^L clear and redraw the screen
^T untag messages matching a pattern

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.

Table 2.8. Message status flags

Flag Description
D message is deleted (is marked for deletion)
d message has attachments marked for deletion
K contains a PGP public key
N message is new
O message is old
P message is PGP encrypted
r message has been replied to
S message is signed, and the signature is successfully verified
s message is signed
! message is flagged
* message is tagged
n thread contains new messages (only if collapsed)
o thread contains old messages (only if collapsed)

Table 2.9. Message recipient flags

Flag Description
+ message is to you and you only
T message is to you, but also to or CC'ed to others
C message is CC'ed to you
F message is from you
L message is sent to a subscribed mailing list
R message has your address in the Reply-To field

5.2. The Pager

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.

Table 2.10. Most common pager keys

Key Description
<Return> go down one line
<Space> display the next page (or next message if at the end of a message)
- go back to the previous page
n search for next match
S skip beyond quoted text
T toggle display of quoted text
? show keybindings
/ regular expression search
Esc / backward regular expression search
\ toggle highlighting of search matches
^ jump to the top of the message

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

Table 2.11. ANSI escape sequences

Escape code Description
0 All attributes off
1 Bold on
3 Italics on
4 Underline on
5 Blink on
7 Reverse video on
3 <color> Foreground color is <color> (see Table 2.12, “Color sequences”)
4 <color> Background color is <color> (see Table 2.12, “Color sequences”)

Table 2.12. Color sequences

Color code Color
0 Black
1 Red
2 Green
3 Yellow
4 Blue
5 Magenta
6 Cyan
7 White

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


If you change the colors for your display, for example by changing the color associated with color2 for your xterm, then that color will be used instead of green.


Note that the search commands in the pager take regular expressions, which are not quite the same as the more complex patterns used by the search command in the index. This is because patterns are used to select messages by criteria whereas the pager already displays a selected message.

5.3. Threaded Mode

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

Table 2.13. Most common thread mode keys

Key Function Description
^D <delete-thread> delete all messages in the current thread
^U <undelete-thread> undelete all messages in the current thread
^N <next-thread> jump to the start of the next thread
^P <previous-thread> jump to the start of the previous thread
^R <read-thread> mark the current thread as read
Esc d <delete-subthread> delete all messages in the current subthread
Esc u <undelete-subthread> undelete all messages in the current subthread
Esc n <next-subthread> jump to the start of the next subthread
Esc p <previous-subthread> jump to the start of the previous subthread
Esc r <read-subthread> mark the current subthread as read
Esc t <tag-thread> toggle the tag on the current thread
Esc v <collapse-thread> toggle collapse for the current thread
Esc V <collapse-all> toggle collapse for all threads
P <parent-message> jump to parent message in thread

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

Table 2.14. Special Thread Characters

Character Description Notes
& hidden message see $hide_limited and $hide_top_limited
? missing message see $hide_missing and $hide_top_missing
* pseudo thread see $strict_threads; not displayed when $narrow_tree is set
= duplicate thread see $duplicate_threads; not displayed when $narrow_tree is set

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.

5.4. Miscellaneous Functions

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


Calculate statistics for all monitored mailboxes declared using the mailboxes command. It will calculate statistics despite $mail_check_stats being unset.

<create-alias> (default: a)

Creates a new alias based upon the current message (or prompts for a new one). Once editing is complete, an alias command is added to the file specified by the $alias_file variable for future use


NeoMutt does not read the $alias_file upon startup so you must explicitly source the file.

<check-traditional-pgp> (default: Esc P)

This function will search the current message for content signed or encrypted with PGP the traditional way, that is, without proper MIME tagging. Technically, this function will temporarily change the MIME content types of the body parts containing PGP data; this is similar to the <edit-type> function's effect.


This command (available in the index and pager) allows you to edit the raw current message as it's present in the mail folder. After you have finished editing, the changed message will be appended to the current folder, and the original message will be marked for deletion; if the message is unchanged it won't be replaced.

<edit> is a synonym of this for backwards compatibility.

See also <edit-or-view-raw-message> , <view-raw-message> .


Alias of <edit-raw-message> for backwards compatibility.

<edit-or-view-raw-message> (default: e)

This command (available in the index and pager) is the same as <edit-raw-message> if the mailbox is writable, otherwise it the same as <view-raw-message> .

<edit-type> (default: ^E on the attachment menu, and in the pager and index menus; ^T on the compose menu)

This command is used to temporarily edit an attachment's content type to fix, for instance, bogus character set parameters. When invoked from the index or from the pager, you'll have the opportunity to edit the top-level attachment's content type. On the attachment menu, you can change any attachment's content type. These changes are not persistent, and get lost upon changing folders.

Note that this command is also available on the compose menu. There, it's used to fine-tune the properties of attachments you are going to send.

<enter-command> (default: :)

This command is used to execute any command you would normally put in a configuration file. A common use is to check the settings of variables, or in conjunction with macros to change settings on the fly.

<extract-keys> (default: ^K)

This command extracts PGP public keys from the current or tagged message(s) and adds them to your PGP public key ring.

<forget-passphrase> (default: ^F)

This command wipes the passphrase(s) from memory. It is useful, if you misspelled the passphrase.

<list-reply> (default: L)

Reply to the current or tagged message(s) by extracting any addresses which match the regular expressions given by the lists or subscribe commands, but also honor any Mail-Followup-To header(s) if the $honor_followup_to configuration variable is set. In addition, the List-Post header field is examined for mailto: URLs specifying a mailing list address. Using this when replying to messages posted to mailing lists helps avoid duplicate copies being sent to the author of the message you are replying to.


Send an email to the address specified in the List-Subscribe header as specified in RFC2369.


Send an email to the address specified in the List-Unsubscribe header as specified in RFC2369.

<pipe-message> (default: |)

Asks for an external Unix command and pipes the current or tagged message(s) to it. The variables $pipe_decode, $pipe_decode_weed, $pipe_split, $pipe_sep and $wait_key control the exact behavior of this function.

<resend-message> (default: Esc e)

NeoMutt takes the current message as a template for a new message. This function is best described as "recall from arbitrary folders". It can conveniently be used to forward MIME messages while preserving the original mail structure. Note that the amount of headers included here depends on the value of the $weed variable.

This function is also available from the attachment menu. You can use this to easily resend a message which was included with a bounce message as a message/rfc822 body part.

<shell-escape> (default: !)

Asks for an external Unix command and executes it. The $wait_key can be used to control whether NeoMutt will wait for a key to be pressed when the command returns (presumably to let the user read the output of the command), based on the return status of the named command. If no command is given, an interactive shell is executed.

<skip-headers> (default: H)

This function will skip to the first line of the body, past the headers of the current message, regardless of current position.


This command (available in the index and pager) opens the raw message read-only in an editor. This command does not allow editing the message, use <edit-raw-message> for this.

See also <edit-raw-message> , <edit-or-view-raw-message> .

<skip-quoted> (default: S)

This function will make the internal pager go forward to the next segment of non-quoted body text (whether the first line of the body after headers, or following a line of quoted text), or print a message if no further unquoted text can be found.

The variable $pager_skip_quoted_context can be used to show some quoted context prior to the selected line.

<toggle-quoted> (default: T)

The pager uses the $quote_regex variable to detect quoted text when displaying the body of the message. This function toggles the display of the quoted material in the message. It is particularly useful when being interested in just the response and there is a large amount of quoted text in the way.

The variable $toggle_quoted_show_levels can be used to show some context by continuing to show that number of levels rather than hiding all quoted levels.

6. Sending Mail

6.1. Introduction

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

Table 2.15. Most common mail sending keys

Key Function Description
m <mail> compose a new message
r <reply> reply to sender
g <group-reply> reply to all recipients
  <group-chat-reply> reply to all recipients preserving To/Cc
L <list-reply> reply to a mailing list
L <list-subscribe> send a subscription email to a mailing list
L <list-unsubscribe> send an unsubscription email to a mailing list
f <forward> forward message
b <bounce> bounce (remail) message
Esc k <mail-key> mail a PGP public key to someone

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:

Simple reply

Reply to the author directly.

Group reply

Reply to the author; cc all other recipients; consults alternates and excludes you.

Group Chat reply

Reply to the author and other recipients in the To list; cc other recipients in the Cc list; consults alternates and excludes you.

List reply

Reply to all mailing list addresses found, either specified via configuration or auto-detected. See Section 14, “Mailing Lists” for details.

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.

Table 2.16. Most common compose menu keys

Key Function Description
a <attach-file> attach a file
A <attach-message> attach message(s) to the message
Esc k <attach-key> attach a PGP public key
d <edit-description> edit description on attachment
D <detach-file> detach a file
t <edit-to> edit the To field
Esc f <edit-from> edit the From field
r <edit-reply-to> edit the Reply-To field
c <edit-cc> edit the Cc field
b <edit-bcc> edit the Bcc field
y <send-message> send the message
s <edit-subject> edit the Subject
S <smime-menu> select S/MIME options
f <edit-fcc> specify an Fcc mailbox
p <pgp-menu> select PGP options
P <postpone-message> postpone this message until later
q <quit> quit (abort) sending the message
w <write-fcc> write the message to a folder
i <ispell> check spelling (if available on your system)
^F <forget-passphrase> wipe passphrase(s) from memory

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.


Note that certain operations like composing a new mail, replying, forwarding, etc. are not permitted when you are in that folder. The %r in $status_format will change to a A to indicate that you are in attach-message mode.

After exiting the compose menu via <send-message>, the message will be sent. If configured and enabled, this can happen 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.

6.2. Editing the Message Header

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.

6.2.1. Fcc: Pseudo Header

If you specify either of

Mutt-Fcc: filename

Fcc: filename

as a header, NeoMutt will pick up filename just as if you had used the <edit-fcc> function in the compose menu. It can later be changed from the compose menu.

6.2.2. Attach: Pseudo Header

You can also attach files to your message by specifying either of

Mutt-Attach: filename [ description ]

Attach: filename [ description ]

where filename is the file to attach and description is an optional string to use as the description of the attached file. Spaces in filenames have to be escaped using backslash ( \). The file can be removed as well as more added from the compose menu.

6.2.3. Pgp: Pseudo Header

If you want to use PGP, you can specify either of

Mutt-PGP: [ E | S | S <id> ]

Pgp: [ E | S | S <id> ]

E selects encryption, S selects signing and S<id> selects signing with the given key, setting $pgp_sign_as for the duration of the message composition session. The selection can later be changed in the compose menu.

6.2.4. Smime: Pseudo Header

If you want to use S/MIME, you can specify either of

Mutt-SMIME: [ E | S | S <id> ]

Smime: [ E | S | S <id> ]

E selects encryption, S selects signing and S<id> selects signing with the given key, setting $smime_sign_as for the duration of the message composition session. The selection can later be changed in the compose menu.

6.2.5. In-Reply-To: Header

When replying to messages, the In-Reply-To: header contains the Message-Id of the message(s) you reply to. If you remove or modify its value, NeoMutt will not generate a References: field, which allows you to create a new message thread, for example to create a new message to a mailing list without having to enter the mailing list's address.

If you intend to start a new thread by replying, please make really sure you remove the In-Reply-To: header in your editor. Otherwise, though you'll produce a technically valid reply, some netiquette guardians will be annoyed by this so-called thread hijacking.

6.3. Sending Cryptographically Signed/Encrypted Messages

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

Table 2.17. PGP key menu flags

Flag Description
R The key has been revoked and can't be used.
X The key is expired and can't be used.
d You have marked the key as disabled.
c There are unknown critical self-signature packets.

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

Table 2.18. PGP key menu validity

Flag (classic PGP) Flag (GPGME) Description
N/A ? indicates unknown validity
? q indicates undefined validity
- n indicates a never valid key (untrusted association)
space m indicates marginal validity (partially trusted)
+ f indicates full validity (fully trusted)
N/A u indicates ultimate validity
N/A x the entry is an X509 certificate (S/MIME)

6.4. Sending Format=Flowed Messages

6.4.1. Concept

format=flowed-style messages (or f=f for short) are text/plain messages that consist of paragraphs which a receiver's mail client may reformat to its own needs, which mostly means to customize line lengths regardless of what the sender sent. Technically this is achieved by letting lines of a flowable paragraph end in spaces except for the last line.

While for text-mode clients like NeoMutt it's best to assume only a standard 80x24 character cell terminal, it may be desired to let the receiver decide completely how to view a message.

6.4.2. NeoMutt Support

NeoMutt only supports setting the required format=flowed MIME parameter on outgoing messages if the $text_flowed variable is set, specifically it does not add the trailing spaces.

After editing, NeoMutt properly space-stuffs the message. Space-stuffing is required by RFC3676, defining format=flowed, and means to prepend a space to:

  • all lines starting with a space

  • lines starting with the word From followed by space

  • all lines starting with > , which is not intended to be a quote character


NeoMutt only supports space-stuffing for the first two types of lines but not for the third: It is impossible to safely detect whether a leading > character starts a quote or not.

All leading spaces are to be removed by receiving clients to restore the original message prior to further processing.

6.4.3. Editor Considerations

As NeoMutt provides no additional features to compose f=f messages, it's completely up to the user and his editor to produce proper messages. Please consider your editor's documentation if you intend to send f=f messages.

For example, vim provides the w flag for its formatoptions setting to assist in creating f=f messages, see :help fo-table for details.

6.4.4. Reformatting

NeoMutt has some support for reformatting when viewing and replying to format=flowed messages. In order to take advantage of these, $reflow_text must be set.

  • Paragraphs are automatically reflowed and wrapped at a width specified by $reflow_wrap.

  • In its original format, the quoting style of format=flowed messages can be difficult to read, and doesn't intermix well with non-flowed replies. Setting $reflow_space_quotes adds spaces after each level of quoting when in the pager and replying in a non-flowed format (i.e. with $text_flowed unset).

  • If $reflow_space_quotes is unset, NeoMutt will still add one trailing space after all the quotes in the pager (but not when replying).

7. Forwarding and Bouncing Mail

Bouncing and forwarding let you send an existing message to recipients that you specify. Bouncing a message sends a verbatim copy of a message to alternative addresses as if they were the message's original recipients specified in the Bcc header. Forwarding a message, on the other hand, allows you to modify the message before it is resent (for example, by adding your own comments). Bouncing is done using the <bounce> function and forwarding using the <forward> function bound to b and f respectively.

Forwarding can be done by including the original message in the new message's body (surrounded by indicating lines: see $forward_attribution_intro and $forward_attribution_trailer) or including it as a MIME attachment, depending on the value of the $mime_forward variable. Decoding of attachments, like in the pager, can be controlled by the $forward_decode and $mime_forward_decode variables, respectively. The desired forwarding format may depend on the content, therefore $mime_forward is a quadoption which, for example, can be set to ask-no.

NeoMutt's default ( $mime_forward= no and $forward_decode= yes) is to use standard inline forwarding. In that mode all text-decodable parts are included in the new message body. Other attachments from the original email can also be attached to the new message, based on the quadoption $forward_attachments.

The inclusion of headers is controlled by the current setting of the $weed variable, unless $mime_forward is set. The subject of the email is controlled by $forward_format.

By default a forwarded message does not reference the messages it contains. When $forward_references is set, a forwarded message includes the In-Reply-To: and References: headers, just like a reply would. Hence the forwarded message becomes part of the original thread instead of starting a new one.

Editing the message to forward follows the same procedure as sending or replying to a message does, but can be disabled via the quadoption $forward_edit.

8. Postponing Mail

At times it is desirable to delay sending a message that you have already begun to compose. When the <postpone-message> function is used in the compose menu, the body of your message and attachments are stored in the mailbox specified by the $postponed variable. This means that you can recall the message even if you exit NeoMutt and then restart it at a later time.

Once a message is postponed, there are several ways to resume it. From the command line you can use the -p option, or if you compose a new message from the index or pager you will be prompted if postponed messages exist. If multiple messages are currently postponed, the postponed menu will pop up and you can select which message you would like to resume.


If you postpone a reply to a message, the reply setting of the message is only updated when you actually finish the message and send it. Also, you must be in the same folder with the message you replied to for the status of the message to be updated.

See also the $postpone quad-option.

9. Logging

NeoMutt has different types of logging/error messages

  • Primitive Errors: errors emitted by C library functions such as fopen().

  • Errors

  • Warnings

  • Message: Informational messages such as Sorting mailbox....

  • Debug: Debug messages usually only interesting while debugging.

These log messages are shown in the command bar at the bottom of the UI (usually below the status line) and errors are shown in a different colour than the other message types. The colours used for displaying can be adjusted with color error ... and color message ..., respectively. See the description of colorfor the precise syntax.

The command bar shows only the last message. To show the last 100 messages (this includes all types of messages from debug to error) the function <show-log-messages> can be used.

Debug messages are not shown by default. To enable them NeoMutt must be compiled with +debug. Furthermore, the debug log level must be set with the -d command line parameter at startup. The -d parameter expects a debug level which can range from 1 to 5 and affects verbosity of the debug messages. A value of 2 is recommended for the start. If debug logging is enabled, all log messages (i.e. errors, warnings, ..., debug) are additionally written to the file ~/.neomuttdebug0.

10. Encryption and Signing

NeoMutt supports encrypting and signing emails when used interactively. In batch mode, cryptographic operations are disabled, so these options can't be used to sign an email sent via a cron job, for instance.

The recommended way to enable OpenPGP and S/MIME is to use GPGME. This library is integrated into NeoMutt and can perform all the common crypto functions the user will need.

# Enable GPGME
set crypt_use_gpgme

If you have complex crypto needs, then you can enable the classic mode by disabling GPGME and setting all pgp_command_* and smime_command_* config variables.

For example config, see: gpg.rc and smime.rc in the Contrib repository.

# Use manual crypto functions
unset crypt_use_gpgme
set pgp_clear_sign_command = "..."
set smime_decrypt_command = "..."

10.1. OpenPGP Configuration

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.

10.2. S/MIME Configuration

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.

Search by Algolia