Email IMAP Setup with isync

4 minute read

The blog post “Email Setup with isync, notmuch, afew, msmtp and Emacs” prompted a few questions. The questions were around synchronizing email in general.

I did promise to write up more blog posts to explain the pieces I brushed over quickly for brevity and ease of understanding. Or so I thought !


Let’s talk Maildir. Wikipedia defines it as the following.

The Maildir e-mail format is a common way of storing email messages in which each message is stored in a separate file with a unique name, and each mail folder is a file system directory. The local file system handles file locking as messages are added, moved and deleted. A major design goal of Maildir is to eliminate the need for program code to handle file locking and unlocking.

It is basically what I mentioned before. Think of your emails as folders and files. The image will get clearer, so let’s dig even deeper.

If you go into a Maildir directory, let’s say Inbox and list all the directories in there, you’ll find tree of them.

$ ls
cur/  new/  tmp/

These directories have a purpose.

  • tmp/: This directory stores all temporary files and files in the process of being delivered.
  • new/: This directory stores all new files that have not yet been seen by any email client.
  • cur/: This directory stores all the files that have been previously seen.

This is basically how emails are going to be represented on your disk. You will need to find an email client which can parse these files and work with them.


The Internet Mail Access Protocol, shortened to IMAP, is an

Internet standard protocol used by email clients to retrieve email messages from a mail server over a TCP/IP connection.

In simple terms, it is a way of communication that allows synchronization between a client and an email server.

What can you do with that information ?

Now, you have all the pieces of the puzzle to figure out how to think about your email on disk and how to synchronize it. It might be a good idea to dive a little bit into my configuration and why I chose these settings to begin with. Shall we ?


Most email servers nowadays offer you an IMAP (POP3 was another protocol used widely back in the day) endpoint to connect to. You might be using Outlook or Thunderbird or maybe even Claws-mail as an email client. They usually show you the emails in a neat GUI (Graphical User Interface) with all the read and unread mail and the folders. If you’ve had the chance to configure one of these clients a few years ago, you would’ve needed to find the IMAP host and port of the server. These clients talk IMAP too.

isync is an application to synchronize mailboxes. I use it to connect to my email server using IMAP and synchronize my emails to my hard drive as a Maildir.


The very first section of the configuration is the IMAP section.

IMAPAccount Personal
User [email protected]
Pass "yourPassword"
# One can use a command which returns the password
# Such as a password manager or a bash script
#PassCmd sh script/path
CertificateFile /etc/ssl/certs/ca-certificates.crt

IMAPStore personal-remote
Account Personal

In here, we configure the IMAP settings. Most notably here is of course Host, User and Pass/PassCmd. These settings refer to your server and you should populate them with that information. The IMAPStore is used further in the configuration, this gives a name for the IMAP Store. In simple terms, if you want to refer to your server you use personal-remote.


The next section of the configuration is the Maildir part. You can think of this as where do you want your emails to be saved on disk.

MaildirStore personal-local
Subfolders Verbatim
Path ~/.mail/
Inbox ~/.mail/Inbox

This should be self explanatory but I’d like to point out the MaildirStore key. This refers to email on disk. So, if you want to refer to your emails on disk you use personal-local.

At this point, you are thinking to yourself what the hell does that mean ? What is this dude talking about ! Don’t worry, I got you.

Synchronize to your taste

This is where all what you’ve learned comes together. The fun part ! The part where you get to choose how you want to do things.

Here’s what I want. I want to synchronize my server Inbox with my on disk Inbox both ways. If the Inbox folder does not exist on disk, create it. The name of the Inbox on the server is Inbox. This can be translated to the following.

Channel sync-personal-inbox
Master :personal-remote:"Inbox"
Slave :personal-local:Inbox
Create Slave
SyncState *
CopyArrivalDate yes

I want to do the same with Archive and Sent.

Channel sync-personal-archive
Master :personal-remote:"Archive"
Slave :personal-local:Archive
Create Slave
SyncState *
CopyArrivalDate yes

Channel sync-personal-sent
Master :personal-remote:"Sent"
Slave :personal-local:Sent
Create Slave
SyncState *
CopyArrivalDate yes

At this point, I still have my trash. The trash on the server is called Junk but I want it to be Trash on disk. I can do that easily as follows.

Channel sync-personal-trash
Master :personal-remote:"Junk"
Slave :personal-local:Trash
Create Slave
SyncState *
CopyArrivalDate yes

I choose to synchronize my emails both ways. If you prefer, for example, not to download the sent emails and only synchronize them up to the server, you can do that with SyncState. Check the mbsync manual pages.

Tie the knot

At the end, add all the channel names configured above under the save Group with the same account name.

Group Personal
Channel sync-personal-inbox
Channel sync-personal-archive
Channel sync-personal-sent
Channel sync-personal-trash


This is pretty much it. It is that simple. This is how I synchronize my email. How do you ?