Configuring mbsync for Apple Mail

As a first step in realizing my goal of running mu4e as my email client, I had to get mbsync running. Mbsync is a process that communicates with one or more IMAP servers to keep your email clients in sync. My primary email is through Apple so one of my goals was to be able to use mu4e on my Macs but still have fully synced access to mail on my iPhone and iPad. That’s pretty easy because Apple mail is IMAP based and keeping multiple clients in sync is the point of IMAP.

There are two problems to solve for getting mbsync working on the Mac. The first is specifying your mail server password to mbsync. You could, of course, just put the password in your mbsync configuration file but that’s horribly insecure and, happily, unnecessary. Here’re the directions for setting up a password in your keychain from the sample configuration that comes with mbsync.

# On Mac OS X, run "KeyChain Access" -- File->New Password Item. Fill out form using
#  "Keychain Item Name" http://IMAPSERVER  (note: the "http://" is a hack)
#  "Account Name" USERNAME
#  "Password" PASSWORD

That brings us to the second problem: what to use for a password. You might think your icloud password is what’s needed here but if you have two-factor authentication enabled—which you almost certainly do if you’re running Sierra or later—you need to generate an application specific password. You can do that by following these instructions. Failure to understand this point was the source of almost all my problems in getting things working.

I keep all my saved emails in a single folder for reasons I’ve discussed before. Your setup may be a little different but if so you just need to adjust the list of mailboxes on the Patterns line in the configuration below. I added an icloud subdirectory under Maildir because I intend to add a separate mail repository for Gmail later. Right now, the configuration communicates only with the Apple mail server.

Here is my .mbsyncrc file. It normally lives in your home directory.

# Based on
IMAPAccount icloud
User XXX #not etc.
PassCmd "security find-generic-password -s mbsync-icloud-password -w"
Port 993
SSLVersions TLSv1.2
AuthMechs PLAIN

IMAPStore icloud-remote
Account icloud

MaildirStore icloud-local
Path ~/Maildir/icloud/
Inbox ~/Maildir/icloud/inbox
Trash Trash

# Channels and Groups 
# (so that we can rename local directories and flatten the hierarchy)
Channel icloud-folders
Master :icloud-remote:
Slave :icloud-local:
Patterns "INBOX" "Saved" "Drafts" "Archive" "Sent*" "Trash"
Create Both
Expunge Both
SyncState *

Group icloud
Channel icloud-folders

Once you get everything set up you can try retrieving your mail with

mbsync -a

or, if you have more than one mail server configured

mbsync icloud #or whatever your mail group name is

In the case of Apple, the server doesn’t like users sucking up bandwidth so if you have a large repository on the server, it may drop off after a while. That’s not fatal because you can just restart the download and it will take up where it left off. You can help a bit by rate limiting your network I/O as described by Ben Maughan in this post. That post also has a nice configuration for Gmail if that’s what you need. After the initial download everything will work smoothly.

Shortly, I’ll publish my next post in this series about mu4e with a discussion of my mu4e configuration.

This entry was posted in General and tagged , . Bookmark the permalink.
  • krisbrowne42

    Application Passwords! I didn't know iCloud had them, but that makes perfect sense with the move to 2FA. I've been using them with gmail for what feels like a decade...