Install Mutt

On Linux, you can install Mutt from your distribution’s software repository and then create a .mutt directory to hold its configuration files:

$ sudo dnf install mutt
$ mkdir ~/.mutt


Mutt is a mail user agent (MUA), meaning its job is to read, compose, and send email
to an outbound mail spool.

Eventually, you’ll be able to install it with the python3 -m pip command, but as of this writing, you must install OfflineIMAP manually because it’s still being ported from Python 2 to Python 3.

OfflineIMAP requires imaplib2, which is also in heavy development, so I prefer doing a manual install of that, as well. The process is the same: clone the source code repository with Git, change into the directory, and install with pip.

First, install the rfc6555 dependency:

$ python3 -m pip install --user rfc6555

Next, install imaplib2 from source:

$ git clone git@github.com:jazzband/imaplib2.git
$ pushd imaplib2.git
$ python3 -m pip install --upgrade --user .
$ popd

Finally, install OfflineIMAP from source:

$ git clone git@github.com:OfflineIMAP/offlineimap3.git
$ pushd offlineimap3.git
$ python3 -m pip install --upgrade --user .
$ popd

Configure OfflineIMAP

OfflineIMAP reads the configuration file ~/.offlineimaprc by default. A template for this file, named offlineimap.conf, is included in the Git repository you cloned to install OfflineIMAP. Move the example file to your home directory:

$ mv offlineimap3.git/offlineimap.conf ~/.offlineimaprc

Open the file in your favorite text editor and read through it. It’s a well-commented file, and it’s good to get familiar with the options available. Here’s my .offlineimaprc as an example, with comments removed for brevity. Some values may be slightly different for you, but this gives you a reasonable idea of what your end product ought to look like:

[general]
ui = ttyui
accounts = %your-gmail-username%
pythonfile = ~/.mutt/password_prompt.py
fsync = False

[Account %your-gmail-username%]
localrepository = %your-gmail-username%-Local
remoterepository = %your-gmail-username%-Remote
status_backend = sqlite
postsynchook = notmuch new

[Repository %your-gmail-username%-Local]
type = Maildir
localfolders = ~/.mail/%your-gmail-username%-gmail.com
nametrans = lambda folder: {'drafts':  '[Gmail]/Drafts',
                            'sent':    '[Gmail]/Sent Mail',
                            'flagged': '[Gmail]/Starred',
                            'trash':   '[Gmail]/Trash',
                            'archive': '[Gmail]/All Mail',
                            }.get(folder, folder)

[Repository %your-gmail-username%-Remote]
maxconnections = 1
type = Gmail
remoteuser = %your-gmail-username%@gmail.com
remotepasseval = '%your-gmail-API-password%'
## remotepasseval = get_api_pass()
sslcacertfile = /etc/ssl/certs/ca-bundle.crt
realdelete = no
nametrans = lambda folder: {'[Gmail]/Drafts':    'drafts',
                            '[Gmail]/Sent Mail': 'sent',
                            '[Gmail]/Starred':   'flagged',
                            '[Gmail]/Trash':     'trash',
                            '[Gmail]/All Mail':  'archive',
                            }.get(folder, folder)
folderfilter = lambda folder: folder not in ['[Gmail]/Trash',
                                             '[Gmail]/Important',
                                             '[Gmail]/Spam',
                                             ]

here are two replaceable values in this file: %your-gmail-username% and %your-gmail-API-password%. Replace the first with your Gmail user name. That’s the part of your email address on the left of the @gmail.com part. You must acquire the second value from Google through a two-factor authentication (2FA) setup process (even though you don’t need to use 2FA to check email).

Set up 2FA for Gmail

Google expects its users to use the Gmail website for email, so when you attempt to access your email outside of Gmail’s interface, you’re essentially doing so as a developer (even if you don’t consider yourself a developer). In other words, you’re creating what Google considers an “app.” To obtain a developer-level app password, you must set up 2FA; through that process, you get an app password, which Mutt can use to log in outside the usual browser interface.

Enable IMAP in Gmail

There’s one last thing before you can say goodbye to the Gmail web interface forever: You must enable IMAP access to your Gmail account.

To do this, go to the Gmail web interface, click the “cog” icon in the upper-right corner, and select See all settings. In Gmail Settings, click the POP/IMAP tab, and enable the radio button next to Enable IMAP. Save your settings. Now Gmail is configured to give you access to your email outside a web browser.

Configure Mutt

Now that you’re all set up for Mutt, you’ll be happy to learn that configuring Mutt is the easy part. As with .bashrc, .zshrc, and .emacs files, there are many examples of very good .muttrc files available on the internet.

Launch Mutt

Before launching Mutt, run offlineimap from a terminal to sync your computer with the remote server. The first run of this takes a long time, so leave it running overnight.

Once your account has synchronized, you can launch Mutt:

$ mutt

Mutt prompts you for permission to create the directories it needs to organize your email activity and then displays a view of your inbox.