Nmail: Terminal-based email client for Linux and macOS

nmail is a terminal-based email client for Linux and macOS with a user interface similar to alpine / pine.

• Support for IMAP and SMTP protocols
• Local cache using sqlite (optionally AES256-encrypted)
• Multi-threaded (email fetch and send done in background)
• Address book auto-generated based on email messages
• Viewing HTML emails (converted to text in terminal, or in external browser)
• Opening/viewing attachments in external program
• Simple setup wizard for Gmail, iCloud and Outlook/Hotmail
• UI similar to Alpine / Pine
• Compose message using external editor ($EDITOR)
• View message using external viewer ($PAGER)
• Saving and continuing draft messages
• Compose HTML emails using Markdown (see markdown_html_compose option)
• Email search
• Compose emails while offline
• Color customization
• Signature

• Local mailbox downloaded by third-party application (OfflineIMAP, fdm, etc)
• Multiple email accounts in a single session
• Special handling for Gmail labels
• Threaded view

Usage:

Command-line Options:

Configuration files:

Examples:

nmail is developed and tested on Linux and macOS. Current version has been tested on:

• macOS Sequoia 15.5
• Ubuntu 24.04 LTS

Brew

MacPorts

Arch

There are two AUR packages available - nmail (stable release) and nmail-git (latest git).

Guix

Get Source

If using macOS, Alpine, Arch, Fedora, Gentoo, Raspbian or Ubuntu, one can use the make.sh script provided.

Dependencies

Build / Install

Dependencies

macOS

Arch

Debian-based (Ubuntu, Raspbian, etc)

Fedora

Gentoo

Build

Install

Certain external programs will be utilized by default if installed on the system, primarily to improve handling of HTML-formatted emails. For best user experience the following packages are recommended to be installed.

macOS

Debian-based (Ubuntu, Raspbian, etc)

Use the setup wizard to set up nmail for the account. Example (replace [email protected] with your actual gmail address):

Note: Refer to Gmail Prerequisites for enabling IMAP access and password authentication.

Use the setup wizard to set up nmail for the account. Example:

Note: Refer to Gmail Prerequisites for enabling IMAP access and obtaining OAuth 2.0 access.

Use the setup wizard to set up nmail for the account. Example (replace [email protected] with your actual outlook / hotmail address):

Use the setup wizard to set up nmail for the account. Example:

Run nmail once in order for it to automatically generate the default config file:

Then open the config file ~/.config/nmail/main.conf in your favourite text editor and fill out the required fields:

Full example of a config file ~/.config/nmail/main.conf:

The from-address to use. Required for sending emails.

Indicates whether nmail shall encrypt local address book cache or not. Enabling it has some performance impact when starting and exiting nmail (default disabled).

Specifies whether to abort execution (crash) if assertions fail. Primarily intended for debugging.

Specifies whether nmail shall use password authentication (pass) or Gmail OAuth 2.0 authentication (gmail-oauth2).

Indicates whether nmail shall encrypt local OAuth 2.0 access token store (default enabled).

Allows overriding environment variable $BROWSER which controls the default web browser to use, for example for OAuth log in.

Indicates whether nmail shall encrypt local message cache or not. Enabling it has some performance impact when starting and exiting nmail, as well as when navigating to different folders (default disabled).

Indicates whether nmail shall encrypt local search index or not. Enabling it has some performance impact when starting and exiting nmail (default disabled).

This field should generally be left 0. It indicates whether nmail shall upload sent emails to configured sent folder. Many email service providers (gmail, outlook, etc) do this on server side, so this should only be enabled if emails sent using nmail do not automatically gets stored in the sent folder.

Specifies whether to delete messages by copying them to trash and then deleting from current folder, instead of using the IMAP move command. This is disabled by default, except for GMail IMAP where it is enabled to work around a server-side issue, for details see Issue #172.

Specifies whether to enable core dumps on application crash.

Specifies a custom downloads directory path to save attachments to, for example downloads_dir=~/Downloads. If not specified, the current working dir is used.

Name of drafts folder - needed if using functionality to postpone email editing.

The field editor_cmd allows overriding which external editor to use when composing / editing an email using an external editor (Ctrl-E). If not specified, nmail will use the editor specified by the environment variable $EDITOR. If $EDITOR is not set, nmail will use nano.

By default when using Ctrl-T to select attachment files, the nmail internal file picker is used. By specifying this parameter an external command may be used instead. The command must output selected file(s) separated by line breaks, on stdout. Examples:

nnn: file_picker_cmd=TMP=$(mktemp); 2>&1 nnn -p ${TMP}; (cat ${TMP} | tr '\0' '\n' | uniq; rm ${TMP})

ranger: file_picker_cmd=TMP=$(mktemp); 2>&1 ranger --choosefiles=${TMP}; (cat ${TMP}; rm ${TMP})

This field allows excluding certain folders from being accessible in nmail and also from being indexed by the search engine. This is mainly useful for email service providers with "virtual" folders that are holding copies of emails in other folders. When using the setup-wizard to configure a Gmail account, this field will be configured to "[Gmail]/All Mail","[Gmail]/Important","[Gmail]/Starred". As an alternative to configuring this parameter for Gmail, folders can be excluded from IMAP access on server side. In Gmail web interface, navigate to "Settings", "See all settings", "Labels" and untick "Show in IMAP" for "Starred", "Important" and "All Mail".

This field allows overriding the external viewer used when previewing messages composed using markdown. The viewer may be a terminal-based program, e.g. w3m -o confirm_qq=false. By default nmail uses open on macOS and xdg-open >/dev/null 2>&1 on Linux.

This field allows customizing how nmail should convert HTML emails to text. If not specified, nmail uses a helper script html2nmail which in turn uses pandoc (for html without tables), w3m, lynx or elinks if available on the system (in that order). The exact command used is one of:

• pandoc -f html -t plain+literate_haskell --wrap=preserve
• w3m -T text/html -I utf-8 -dump
• lynx -assume_charset=utf-8 -display_charset=utf-8 -nomargins -dump
• elinks -dump-charset utf-8 -dump

Note that while pandoc generally produces a better text-equivalent to an html email, it is also slower than the other tools. For usage on a lower spec'ed system, consider using any of the other conversion utilities instead.

This field allows overriding the external viewer used when viewing message html using V. If not specified, nmail checks if w3m, lynx, elinks is available on the system (in that order), with fallback to xdg-open (Linux) and open (macOS). The exact default commands used:

• LESSOPEN="|$(which lesspipe.sh lesspipe | head -1) %s" w3m -o confirm_qq=0 -o use_mouse=0 -o use_lessopen=1
• lynx
• elinks
• xdg-open >/dev/null 2>&1 or open

This parameter controls whether imap idle should watch the inbox for new messages (default enabled) or the currently selected imap folder.

This parameter controls the imap idle timeout in minutes (default 29). This should generally not be changed, refer to RFC 2177 for details.

IMAP hostname / address. Required for fetching emails.

IMAP port. Required for fetching emails.

IMAP inbox folder name. Required for nmail to open the proper default folder.

Specifies whether to dump warning and error log messages to stdout upon exit.

This field allows overriding the command used for externally viewing a message (.eml file) with W. By default nmail uses open on macOS and xdg-open >/dev/null 2>&1 on Linux.

Real name of sender. Recommended when sending emails.

Specify timeout for IMAP and SMTP operations in seconds. If using a very slow network connection and sending very large emails it may be necessary to increase this timeout. By setting it to 0 network operations will not time out. Default 30 seconds.

The field pager_cmd allows overriding which external pager / text viewer to use when viewing an email using an external pager (E). If not specified, nmail will use the pager specified by the environment variable $PAGER. If $PAGER is not set, nmail will use less.

This field allows overriding the external viewer used when viewing email parts and attachments. By default nmail uses open on macOS and xdg-open >/dev/null 2>&1 on Linux.

Determines whether nmail shall fetch headers for all messages when viewing a folder, or only the latest based on message uid. By disabling this option there is no guarantee folder message lists are sorted by timestamp, as only headers for the last messages stored/added in the folder will be retrieved from server. Also note that some other nmail features may operate in degraded mode when this setting is disabled. The ability to disable pre-fetching of all headers is mainly to encompass use-cases where one wants to minimize network usage, or use nmail without persistant cache. Default enabled.

Messages are pre-fetched from server based on the prefetch_level config setting. The following levels are supported:

With level 0-2 configured, pre-fetch level 3 - a single full sync - may be triggered at run-time by pressing s from the message list.

Indicates whether nmail shall encrypt local message offline queue or not (default enabled).

Specifies whether nmail shall store the password(s) (default enabled).

Controls whether to send client local IP address (otherwise local hostname) in SMTP handshaking when sending outgoing emails (default enabled).

IMAP sent folder name. Used by nmail if client_store_sent is enabled to store copies of outgoing emails.

Use server timestamps for messages, rather than the timestamp in the message header (default disabled).

SMTP hostname / address. Required for sending emails.

SMTP port. Required for fetching emails. Default 587.

The field smtp_user should generally be left blank, and only be specified in case the email account has different username and password for sending emails (or if one wants to use one email service provider for receiving and another for sending emails). If not specified, the configured user field will be used.

Controls whether to enable Server Name Indication (SNI) during TLS handshaking.

This field specifies a custom command to use for spell checking composed messages. If not specified, nmail checks if aspell or ispell is available on the system (in that order), and uses the first found. The command used is one of:

• aspell -c
• spell -o -x

This field allows customizing how nmail should convert composed plain text markdown message to corresponding text/html part. If not specified, nmail checks if pandoc or markdown is available on the system (in that order), and uses the first found. The exact command used is one of:

• pandoc -s -f gfm -t html
• markdown

IMAP trash folder name. Needs to be specified in order to delete emails.

Email account username for IMAP (and SMTP).

Allows forcing nmail to enable specified logging level:

For internal use only. Stores version used for last successful execution. May be used for debugging startup crash / hang regressions.

nmail does currently not support multiple email accounts (in a single session). It is however possible to run multiple nmail instances in parallel with different config directories (and thus different email accounts), but it will be just that - multiple instances - each in its own terminal. To facilitate such usage one can set up aliases for accessing different accounts, e.g.:

The email navigator / viewer supports the following commands:

The attachments / parts viewer supports the following commands:

The built-in email compose editor in nmail supports the following:

The email headers To, Cc and Attchmnt support comma-separated values, ex:

Attachment paths may be local (just filename) or absolute (full path).

Press / in the message list view to search the local cache for an email. The local cache can be fully syncronized with server by pressing s. The search engine supports queries with "quoted strings", +musthave, -mustnothave, partialstring*, AND, OR, XOR and NOT.

Search terms may be prefixed by body:, subject:, from:, to: or folder: to search only specified fields. By default search query terms are combined with AND unless specified. Results are sorted by email timestamp.

Press ' in the message list view to search the server for emails in the current active folder. The server search supports space-separated terms which may be prefixed by body:, subject:, from: or to:. The search query terms are implicitly combined with logical "and". Results are sorted by email timestamp.

Press < or Left to exit search results and go back to current folder message list.

Refer to Debugging for details.

A Telegram group https://t.me/nmailusers is available for users to discuss nmail usage and related topics.

nmail caches data locally to improve performance. Cached data can be encrypted by setting by setting cache_encrypt=1 in main.conf. Message databases are then encrypted using OpenSSL AES256-CBC with a key derived from a random salt and the email account password. Folder names are hashed using SHA256 (thus not encrypted).

Storing the account password (save_pass=1 in main.conf) is not secure. While nmail encrypts the password, the key is trivial to determine from the source code. Only store the password if measurements are taken to ensure ~/.config/nmail/secret.conf cannot by accessed by a third-party.

Aside from main.conf covered above, the following files can be used to configure nmail.

This configuration file controls the UI aspects of nmail. Default configuration file (platform-dependent defaults are left empty below):

Controls which character to indicate that an email has attachments (default: 📎). For a more plain layout one can use an ascii character: +.

Specifies whether trash folder may be selected as automove target folder.

Controls whether to reply at the bottom of emails (default disabled).

Allow cancelling email compose without confirmation prompt (default disabled).

Enable terminal color output (default enabled).

Specify interval in seconds for local backups during compose (default 10). If the system running nmail is unexpectedly shutdown while user is composing an email, then upon next nmail startup any backuped compose message will be automatically uploaded to the draft folder. Setting this parameter to 0 disables local backups.

Specify how nmail shall wrap lines in outgoing emails. Supported options:

Allow deleting emails (moving to trash folder) without confirmation prompt (default disabled).

While viewing full headers (by pressing h) nmail displays RFC 822 headers by default. This parameter allows enabling nmail to also display local / internal header fields, such as server timestamp. Default disabled.

Show supported keyboard shortcuts at bottom of screen (default enabled).

Notify user when unsupported keyboard shortcuts are input (default enabled).

Email subjects are normalized (stripped of re:, fwd:) when sorting emails by subject, and when replying to, or forwarding an email. By default only the English prefixes re and fwd? (regex for fwd and fw) are removed. This parameter allows extending the removal to other localized prefixes. Example configuration for a Swedish user:

For a French user:

For a German user:

Default value for each new email, whether nmail shall enable markdown HTML compose. I.e. whether nmail shall generate a text/html message part based on processing the composed message as Markdown, when sending sending emails from nmail. This can be overridden on a per-email basis by pressing CTRL-N when editing an email (default disabled).

Indicate new messages with terminal bell (default enabled).

Determines whether file selection view shall remember previous directory (default enabled).

Controls whether to start with previous find query when performing repeated find queries (default disabled).

Determines whether to persist move-to-folder list filter (default enabled).

Controls whether to start with previous search query when performing repeated search queries (default disabled).

Determines whether to keep current message list selection when filtering/sorting mode is changed (default enabled).

Specifies whether each folder listing shall persist its filtering/sorting mode (default enabled).

Determines whether showing plain text (vs. html converted to text) is preferred. If the preferred email part is not present, nmail automatically attempts to show the other. This option can be re-configured at run-time by pressing t when viewing an email (default enabled).

Allow postponing email compose without confirmation prompt (default disabled).

Allow exiting nmail without confirmation prompt (default enabled).

Specify whether nmail shall respect email line wrapping of format=flowed type (default enabled).

Control whether nmail shall rewrap quoted lines (default enabled).

Determines whether folder name should be shown in search results. This option can be re-configured at run-time by pressing \ when viewing search results (default disabled).

Allow sending email during compose without confirmation prompt (default disabled).

Determines whether to show embedded images in text/html part when viewing it using external viewer; press right arrow when viewing a message to go to parts view, and then select the text/html part and press right arrow again (default enabled).

Specify how nmail shall show progress indication when fetching or indexing emails. Supported options:

Determines whether to show rich headers (bcc field) during email compose. This option can be re-configured in run-time by pressing CTRL-R when composing an email (default disabled).

Determines whether to suffix emails with a signature (default disabled). When enabled, nmail will use ~/.config/nmail/signature.txt if present, or otherwise use ~/.signature for signature plain text content. When composing markdown formatted emails, nmail will use ~/.config/nmail/signature.html if present, for the html part, and otherwise simply convert the plain text signature to html.

Note: For custom html signature to work properly, the plain text signature should not be present more than once in the composed message, thus a very short plain text signature may not be ideal.

Example signature files: signature.txt, signature.html

Tabs are expanded to spaces when viewed in nmail. This parameter controls the space between tab stops (default 8).

Specifies custom terminal title, ex: terminal_title=nmail - [email protected].

Specifies whether to display current folder message count in the top bar.

Specifies whether nmail shall display version number in the top bar.

Controls which character to indicate that an email is unread (default: N). For a more graphical interface, an emoji such as ✉ can be used.

Specifies whether nmail shall unwrap quoted lines before wrapping them when composing a message reply.

This configuration file holds user interface key bindings. Default content:

The key bindings may be specified in the following formats:

• Ncurses macro (ex: KEY_CTRLK)
• Hex key code (ex: 0x22e)
• Octal key code sequence (ex: \033\177)
• Plain-text lower-case ASCII (ex: r)
• Disable key binding (KEY_NONE)

To determine the key code sequence for a key, one can run nmail in key code dump mode nmail -k which will output the octal code, and ncurses macro name (if present).

This configuration file controls the configurable colors of nmail. For this configuration to take effect, colors_enabled=1 must be set in ~/.config/nmail/ui.conf.

Example color config files are provided in /usr/local/share/nmail/themes and can be used by overwriting ~/.config/nmail/colors.conf.

This color theme is similar to htop's default, see screenshot below with nmail and htop.

To use this config:

Alternatively one may manually edit colors.conf. Colors may be specified using standard palette names (black, red, green, yellow, blue, magenta, cyan, white, gray, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan and bright_white) or using integer palette numbers (0, 1, 2, etc).

To use default terminal color, leave the color empty or set it to normal. To use inverted / reverse color set both fg and bg values to reverse.

For terminals supporting custom palettes it is also possible to specify colors using six digit hex format with 0x prefix, e.g. 0xa0a0a0. For each item background _bg and foreground _fg can be specified. Default configuration file:

User prompt dialogs and notifications at bottom of the screen, just above the help bar.

Help shortcut description texts at bottom of the screen, i.e. Compose in C Compose.

Help shortcut key binding texts at bottom of the screen, i.e. C in C Compose.

Highlighted text, such as current message in message view, current folder in folder list, text strings found in message find, etc.

Quoted message text (lines starting with >).

Default text color.

Selected messages in message list view.

Top / title bar.

This configuration file allows users to set up custom OAuth 2.0 client id and client secret. If not specified, nmail uses its own application id and secret. Default configuration file:

Custom OAuth 2.0 client id.

Custom OAuth 2.0 client secret.

Gmail prevents IMAP access by default.

In order to enable IMAP access go to the Gmail web interface - typically mail.google.com - and navigate to Settings -> Forwarding and POP/IMAP -> IMAP access and select: Enable IMAP

Gmail prevents password authentication by default. To enable password-authenticated IMAP access, one must set up an "app password".

To set up an "app password", navigate to https://myaccount.google.com/apppasswords and select app "Mail" and an appropriate device, e.g. "Mac", then click Generate.

Google OAuth 2.0 application review has not yet been requested for nmail, and as such users need to request an invitation to use this. Please send an email to d99kris at gmail dot com with subject nmail google oauth2 invite from the google account address you would like to be invited.

Alternatively a user may set up their own OAuth 2.0 application with Google and configure ~/.config/nmail/auth.conf accordingly.

The nmail message cache may be exported to the Maildir format using the following command:

A basic ~/.muttrc config file for reading the exported Maildir in mutt:

Note: nmail is not designed for working with other email clients, this export option is mainly available as a data recovery option in case access to an email account is lost, and one needs a local Maildir archive to import into a new email account. Such import is not supported by nmail, but is supported by some other email clients, like Thunderbird.

nmail is implemented in C++. Its source tree includes the source code from the following third-party libraries:

• apathy - Copyright 2013 Dan Lecocq - MIT License
• cereal - Copyright 2014 Randolph Voorhies, Shane Grant - BSD-3 License
• cxx-prettyprint - Copyright 2010 Louis Delacroix - Boost License
• cyrus-imap - Copyright 1994-2000 Carnegie Mellon University - BSD-3 License
• libetpan - Copyright 2001-2005 Dinh Viet Hoa - BSD-3 License
• sqlite_modern_cpp - Copyright 2017 aminroosta - MIT License

Uncrustify is used to maintain consistent source code formatting, example:

Refer to the Privacy Policy for details.

nmail is distributed under the MIT license. See LICENSE file.

alternative to alpine, command line, console-based, email client, linux, macos, ncurses, terminal-based.