My first mutt A quick beginners guide for anybody adopting the mutt mailer

Collecting mail

Mutt doesn’t want to collect your mail

In an ideal world, all your email arrives automatically at the machine that you use to read your mail - you just open up your mailspool and find it there. If this is the case for you, then you don’t need to read this page.

The rest of us are in the situation where the final destination of our email is some IMAP or POP3 mailserver hosted by somebody else. Mutt can talk to that server directly, and if your connection is fast and reliable that may be all you ever need - see the mail accounts section.

But there are good reasons to keep a local copy: mutt has no disconnected mode, searching across folders needs local files, and a mailbox you own on your own disk is a mailbox nobody can close. What you want then is a separate program that mirrors the remote account into a local Maildir. Doing this from inside mutt with folder-hooks is possible and thoroughly unsatisfactory.

mbsync

isync, whose command is called mbsync , is the usual choice. It does bidirectional synchronisation between an IMAP account and a local Maildir: mail you read or delete locally is marked read or deleted on the server, and vice versa. It is small, fast, written in C, and copes well with very large mailboxes.

Configuration goes in ~/.mbsyncrc. You describe the remote store, the local store, and a Channel joining them:

IMAPAccount example
Host imap.example.com
User you@example.com
PassCmd "gpg --batch -dq ~/.mutt/account.gpg"
TLSType IMAPS

IMAPStore example-remote
Account example

MaildirStore example-local
Path ~/Mail/
Inbox ~/Mail/inbox
SubFolders Verbatim

Channel example
Far :example-remote:
Near :example-local:
Patterns *
Create Both
Expunge Both
SyncState *

Then mbsync example synchronises that channel, or:

mbsync -a

The Arch Wiki isync page has working example configurations for the common providers, which is the quickest way to get started.

Point mutt at the resulting Maildir and you are done:

set folder = ~/Mail
set spoolfile = +inbox

To call mbsync from within mutt, add a macro to your ~/.muttrc file. A macro is a series of commands bound to a key or word like this:

macro generic G \
<shell-escape>'mbsync -a'<enter> \
'Sync mail with mbsync'

This macro applies to the generic view, the key it is bound to is G (shift and g), the description that appears in the help menu is Sync mail with mbsync and the command that is executed is equivalent to typing !mbsync -a in mutt and hitting enter. Most people also run it periodically from cron or a systemd timer.

OfflineIMAP

OfflineIMAP does the same job in Python. It is more flexible than mbsync about awkward folder layouts and label handling, and correspondingly slower and more fiddly. Note that the current version is offlineimap3 ; anything you find referring to the Python 2 releases is long out of date.

If you are choosing between the two and have no particular requirement, choose mbsync.

getmail and fetchmail

If all you want is to fetch mail from a POP3 account and drop it in a local folder, without any of the two-way business, use a retriever instead.

getmail6 is the maintained fork of Charles Cazabon’s getmail, updated for Python 3. It reads POP3 and IMAP, delivers straight to a Maildir or to a mail delivery agent, and is configured with a straightforward ~/.getmail/getmailrc file. The original getmail at pyropus.ca is Python 2 and should not be used.

fetchmail is the venerable alternative. It can transfer mail from practically every kind of remote mail store, however buggy that remote server may be, which is its main remaining argument. It normally hands mail to a local SMTP server, which means running one; you can avoid that with an mda line in your ~/.fetchmailrc file to pass mail straight to a delivery agent instead.

mpop is a third option, a small POP3 client by the author of msmtp and configured much the same way.

Which of these do I need?

Last updated 31 August 2026.