Gmail from the command line with Mutt (Mac OS X)

Don’t need no GUI.

Feb 6, 2015 · 5 min read

Another day, another task I’ve decided to start doing on the command line. After setting myself up with Twitter CLI and abandoning it shortly thereafter (the command line interface strips Twitter of its actual magic, I feel), I moved onto Gmail, excited by the prospect of swiftly sending and receiving emails without having to greatly interrupt my development workflow.

Introducing Mutt. This awesome email client for the command line goes all the way back to 1998!

Getting started

Install Homebrew if you don’t have it already:

ruby -e "$(curl -fsSL"

With Homebrew installed, install Mutt:

brew install mutt

Once that is finished, we’re ready to start configuring Mutt to work with our Gmail account. Let’s open up Mutt’s configuration file in nano (a Terminal text editor):

nano ~/.muttrc

You will see an empty file like the one above. Paste the following in and edit everything in uppercase according to your account details:

set imap_user = “
set imap_pass = “YOUR-PASSWORD”
set smtp_url = “smtp://”
set smtp_pass = “YOUR-PASSWORD”
set from = “”
set realname = “YOUR NAME”
set folder = “imaps://"
set spoolfile = “+INBOX”
set postponed = “+[Gmail]/Drafts”
set header_cache = ~/.mutt/cache/headers
set message_cachedir = ~/.mutt/cache/bodies
set certificate_file = ~/.mutt/certificates
set move = no
set smtp_authenticators = ‘gssapi:login’

When you’re done, press Control-O (to Write Out) followed by enter. Then press Control-X to exit nano.

If all went well, you will now be able to access your gmail account from the Terminal with the following command:


(If you provided the correct information in .muttrc but are still unable to connect, it’s possible that Google has blocked the sign-in for security reasons. If that happens, you will receive an email from Google stating “We recently blocked a sign-in attempt to your Google Account” with instructions on how to grant access to your account from “less secure apps.” Just follow the link and change your settings to turn on access for less secure apps.)

Inside Mutt

I bought some things at some places and now they own me forever.

If, like me, you’ve gotten into the habit of never deleting any emails, you’ll see a massive output when you first start Mutt. It may be overwhelming at first, but soon you’ll learn to set some configuration options that will help you sort and filter your emails with simple key commands.

But first let’s start by sending an email. You can pick an email from your list to reply to and press r (reply), or start a brand new email by pressing m (mail).

If you chose to start a new message, Mutt will first ask if you want to ‘recall a postponed message’, i.e. a draft. Press y (yes) to be taken to a list of drafts in your account or n (no) to create a new email. Mutt will then prompt you to specify a To address and a Subject.

When that’s done, you’ll be brought to the message editor in Vim:

Vim is another Terminal text editor like nano, but with its own unique commands. If you’re totally unfamiliar with it, you might want to reference a Vim command cheatsheet, but for the purposes of this exercise, only a couple of basic commands are needed.

Press i (insert) to start typing your message. Once you’re done, press the ESC key, followed by :wq (write and quit) to exit Vim.

From here, press y to send your email. You did it!

Advanced Mutt

Now that you’re command-line emailing like a pro, let’s configure Mutt to best suit your needs.

Out of the box, Mutt will return you every email in your inbox and you probably don’t want that. Mutt’s ‘limit’ feature lets you ask for emails according to date, subject, sender, unread status, and more.

To access limit, simply press l (that’s a lowercase L) in Mutt. From here, you can pass Mutt a variety of different options (note the tildes!):

  • ~U —returns all unread emails
  • ~B deadline —returns all emails containing a specific keyword, in this case ‘deadline’
  • ~s pizza —returns all emails with a specified subject, in this case ‘pizza’
  • ~d 01/01/15–01/02/15 —returns emails sent between a specified date range in MM/DD/YYYY format

This is just a small sampling! To see all of the options available and how to use them, refer to the Mutt docs.

If you have a long or complex limit command, you probably don’t want to have to type it out in full each time. For example, I typically like to be shown emails less than 7 days old and having to type l ~d<7d every time I use Mutt is decidedly unideal.

Thankfully we can easily create macro shortcuts to map these Mutt commands to key commands on our machine. Let’s return to our .muttrc file:

nano ~/.muttrc

Below your email settings, configure your macro. Here’s what mine looks like:

macro index .. <limit>~d<7d

This means that when I press .. on my keyboard in Mutt, it will trigger the limit feature with the option ~d<7d which will return emails less than 7 days old. Not bad at all!

Unlike most email clients, Mutt does not come with a ‘check mail’ command that will pull in any new messages while you’re already inside the program. So let’s create our own!

In .muttrc, add the following:

bind index G imap-fetch-mail

Pressing G (get) in Mutt will now fetch any new emails from the IMAP server.

I hope this tutorial was useful for anyone wanting to integrate Gmail into their command line interface. Mutt can be configured for other mail providers. Please see Mutt’s extensive documentation to learn more about the awesome things you can do with it.


    Written by


    Web developer.

    Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
    Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
    Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade