This article by Jason McIntosh was originally written for Mac OS X Hacks, published in 2003 by O'Reilly Media.

Using IMAP with Apple's Mail Application

Most modern email clients, including Mac OS X applications such as Apple's own Mail, Qualcomm's Eudora, or Microsoft's Entourage, default to using the same mail transfer protocol: the venerable Post Office Protocol, more commonly known as POP. POP defines a simple set of instructions that lets users connect to a mail server account, download new mail, and then disconnect. Nearly every ISP's mail server supports POP, so it's a safe choice for mail-fetching client applications to support as well.

More recently, an alternative protocol known as the Internet Message Access Protocol (IMAP) has been steadily gaining popularity and support from Internet providers. IMAP contains a more sophisticated command set that allows users to store and organize mail on the server, instead of simply downloading and deleting it.

IMAP gives the most benefit to people who connect to a mail server using more than one computer, since an IMAP-enabled mail account will look the same on all these machines, from overall mailbox structure down to the status of individual messages, and any changes made to a mailbox on one machine become visible to the rest.

This hack will guide you through setting up and using an IMAP-enabled mail account through Mac OS X's Mail application, covering IMAP-specific concepts and terminology as they come up.

Checking for IMAP Service

Of course, before you can start having fun with IMAP, your mail server must support it! You can find out simply by asking your ISP or network administrator, or you could poke your mail server machine directly to find out, by launching the Terminal application and trying this:

% telnet mail.server.net  143

Replace mail.server.net with the hostname of your mail server. If you've installed a local IMAP server, use localhost. The 143 is the standard port number (think television channel) on which the IMAP server listens.

If you have an IMAP service at your disposal, you'll receive a response a little something like this:

Trying 127.0.0.1...  Connected to localhost. Escape character is '^]'.  * OK [CAPABILITY IMAP4REV1 LOGIN-REFERRALS AUTH=LOGIN] localhost IMAP4rev1  2001.315 at Mon, 29 Jul 2002 15:31:46 -0700 (PDT)

If so, you're good to go. If you instead receive a blunt "Connection refused" or something altogether different, check in with your service operator.

To end the IMAP session you just started, type foo LOGOUT and press Return.

Creating an IMAP Mail Account

Launch Mail (Applications Mail from the Finder). To create a new account, you'll visit Mail's Preferences dialog, Mail Preferences . . . , and select the Accounts tab. Click the Create Account button. Select IMAP Account from the Account Type menu on the resulting sheet (see Figure 7-5), and fill in the text fields with information appropriate to this account, just as you would for a POP account.

Figure 7-5. Creating a new IMAP account

Specifying Account Options

Visit the Advanced tab to see Mail's IMAP-specific options, shown in Figure 7-6. (The controls that appear under this tab depend upon the type of account you've selected under the Account Information tab.) Mail will fill the "Connect to server using port:" text field with 143, the usual TCP port of a mail server's IMAP service. Change this value only if you know that your host runs its IMAP service on a different port. Activate the Use SSL checkbox if your host supports secure IMAP (a.k.a. IMAPS) and you wish to take advantage of it.

Figure 7-6. Setting IMAP options

Check the "Compact mailboxes when closing" checkbox if you want Mail to purge your mailboxes of deleted messages when you quit the application; if left unchecked, deleted emails will remain within mailboxes, invisible to Mail but still accessible by other means.

Account directory

The Account Directory text field lets you specify the location of this account's cache folder on your local filesystem. Unless you have good reason to do otherwise, leave this field blank; Mail will use its default location of ~/Library/Mail/IMAP/account-name, which should work just fine.

You'll notice that once you've started to use the account, this field becomes grayed out and uneditable, so choose wisely and type carefully.

IMAP path prefix

The Account Path Prefix text field specifies the path that Mail will prepend to all mailbox names when it's trying to locate them on the mail server. If you keep all your mailboxes in a directory called mail within your home directory, then you should put ~/mail here.

On the other hand, if you never log into your mail server machine directly, or are otherwise not sure what to put here, then you're probably safe putting nothing here at all and letting the server figure it out for you.

Message caching

To help keep things efficient, Mail keeps local caches of your IMAP accounts' content, even though the real messages reside on the server. By default, an account's cache lives in ~/Library/Mail/IMAP, unless you specified a different location when you created the account. Every account gets its own folder there, named IMAP/account name.

Through the Message Caching pull-down menu, you can specify how much of your incoming email Mail should cache and when it should cache it:

Cache all messages and attachments locally

This will direct Mail to download the entirety of every new message upon connection. This will allow you to read these messages and their attachments when you're offline, much as you can do through a POP account.

This is the default selection for a new Mail IMAP account.

Cache messages' bodies locally

When selected, Mail will cache all new messages' text bodies, as well as a list of any attachments for each, but not the attachments themselves (unless they're relatively small). If you specifically request to see a message's attachment (by clicking on the attachment's icon in the message view window), Mail will fetch a fresh copy from the server for you.

This is a good choice if you like the convenience of having all your textual email stored locally (which allows nice features like indexing and searching) but would like to avoid downloading large attachments you may not always want.

Cache messages when read

This directs Mail to hold off on any message caching when fetching new mail. It will display new mail in the message list as usual but doesn't actually fetch a message's content until you select one for reading. Once it loads a message, Mail places the body into the cache. Subsequent visits to this message will read from the cached copy (unless the server's version of the message changes).

Like the previous menu choice, this does not cache large attachments.

Don't cache any messages

Mail forgets about caching entirely. Every time you access a message, Mail will fetch its contents from the server anew, regardless of whether you've read it before.

While you'd think this a good idea if running a local IMAP server after all, why have two local copies of every message in fact, if you want to take advantage of Mail's searchability and indexing, you'll need caching on.

Mac.com Accounts

As testimony to the magical properties of IMAP, the Mac.com (http://www.mac.com) accounts that Apple provides to its customers as part of its .Mac package use IMAP as its protocol. This lets you consistently access and organize your Mac.com mail from any machine with an IMAP client Macintosh or otherwise.

Setting up a Mac.com-flavored IMAP account is easy; just select Mac.com Account from Mail's Account Type pull-down menu, instead of IMAP Account. It's really just a shortcut that cues Mail to fill in the account configuration text fields to point to Apple's mail servers.

Organizing Mailboxes

In the mailbox list underneath an IMAP account's header, you'll find a list containing an inbox, any mailboxes you create, and any mailboxes Mail creates in order to support some of its own special features.

Inbox

An IMAP server abstracts all a user's new and otherwise unsorted mail into a single mailbox called Inbox, so you'll always have at least this mailbox available to you.

Creating and editing IMAP mailboxes

Mail's commands for creating and organizing mailboxes and folders, found under the Mailbox menu, remain consistent across all its account types, IMAP included. When you create, rename, and delete mailboxes through the commands in this menu or move mailboxes around by dragging their icons in the mailbox list drawer, Mail echoes these actions on your IMAP account's structure. Thus, all the changes you make in one session with Mail will carry across to any future connections you make to this IMAP account with any mail client.

Special mailboxes

While Mail takes full advantage of IMAP's ability to let you create and organize mailboxes any way you like, the application also has the ability to map its own functionality onto some special server-side mailboxes, if you let it. In all of the following cases, Mail will create these mailboxes on the server as necessary:

Drafts

By default, messages that you save as a draft (File Save As Draft, -S, or the message window's Save As Draft toolbar button) stay in Mail's special Outbox mailbox, stored only on your Mac. If you wish, you can instead store unfinished messages on an IMAP mailbox, so they'll be available to choose and complete from other machines.

To do so, visit the Composing tab of Mail's Preferences panel (Mail Preferences) and select one of your IMAP mailboxes from the "Save unsent mail in" pull-down menu.

Sent Messages

It's worth noting that Mail does not keep its Sent Messages mailbox on the IMAP server; it's only on your Mac. Mail stores copies of all the mail you send through all your accounts, IMAP and otherwise, here.

If you want to keep server-side copies of sent mail, choose an IMAP mailbox from the "Save sent mail in" pull-down menu found under the Preference panel's Composing tab.

Trash

If you have the "Move deleted mail to a folder named" checkbox set under the Viewing tab of the Preferences panel, Mail will create a folder on the server to serve as a trash can, where deleted mail will move itself.

You don't need to have a special folder for maintaining deleted messages, since IMAP lets you store deleted mail in any mailbox. However, Mail doesn't let you see any deleted messages except for ones in this special mailbox, and only if you have this checkbox activated.

Organizing Messages

An email message sitting in an IMAP mailbox can have some number of message flags set on it, recording the actions performed on this message, such as the user's reading, replying to, or deleting it. When you reply to a message on your office PC, for example, and then later connect to your mailbox at home, that message will remember the fact you already replied to it, and be able to report this to you.

Mail works with most flags in a fairly straightforward fashion, but it gets a little squirrelly when it comes to IMAP's Deleted flag.

There's nothing particularly magical about how message flags work; they exist simply as headers the IMAP server adds to the messages on its end as their status changes.

Message Flags

Mail displays IMAP flags through symbols in the Flag and Status columns of a mailbox's message list (see Figure 7-7).

Figure 7-7. Message flags

Recent

A message gets a Recent flag if the current IMAP connection is the first to have seen it. Mail places a blue dot in this message's Status column, marking it as a new, unread message. Mail unsets this flag once the user reads a message.

Seen

A message with a Seen flag has been read.

Mail reacts to the absence of this flag; a message lacking a Seen flag (which all Recent messages do, by definition) gets a blue dot. Mail does not distinguish between unread mail that arrived since the current session started (and has a Recent flag) and unread mail carried over from a previous IMAP session (and therefore has no message flags).

Selecting Message Mark As Unread (Option--M) removes this flag from selected messages, and Message Mark As Read (Option--M) sets it. (One of these two commands appears in the Message menu, depending upon the status of the selected messages.)

Answered

Replying to an IMAP message prompts Mail to set its Answered flag. Mail displays such messages with a little U-turn arrow in its status column, unless the message lacks a Seen flag.

Flagged

The Flagged flag can mean whatever you want. Generally, it's meant to signal that a message requires urgent attention.

In Mail, you can toggle this flag for the selected messages through Message Mark As (Un)Flagged (Option--G). Flagged messages receive little flag icons in the message list's flag column.

Draft

Mail sets a message's Draft flag if it's an unfinished, unsent message you're storing in an IMAP mailbox (see "Drafts" item in the previous Special Mailboxes section).

Deleted

Mail gives messages Delete flags when you delete them (pressing the Delete key on your keyboard, selecting Message Delete, or dragging them into your Dock's Trash icon). This seems fairly straightforward, and it does more or less what you want, but this flag's actual implications are convoluted enough that it's worth spending a little time on the subject.

Deleting Messages

IMAP uses a two-step process for deleting messages. Any message can set a Deleted flag on itself, which marks it as susceptible to actual deletion but doesn't actually get rid of it or even move it out of its original mailbox. A separate IMAP command purges a mailbox of all the deleted messages it contains.

Different mail clients have different ways of representing deleted (but not yet erased) messages to the user. Mail chooses to simply not show deleted mail at all, unless it's inside the designated Trash mailbox.

Mail's IMAP response to deleting mail changes depending upon how you've set the "Move deleted mail to a folder named" checkbox. If you've checked it, then deleting a piece of mail will cause Mail to move it to your chosen Trash mailbox, rather than setting its Delete flag.

If, instead, you've left that checkbox unchecked, Mail will set the message's Deleted flags but otherwise leave them be. Since Mail refuses to display deleted mail in mailboxes other than the Trash mailbox, this action will also make the message vanish from sight, even though it continues to exist on the server (and perhaps remain visible to other mail clients).

That same checkbox also dictates Mail's behavior with actually erasing Deleted messages. If checked, Mail gives you a Mailbox Empty Trash Mailbox (-K) command. This will have Mail send the IMAP EXPUNGE command to its Trash mailbox, and since it contains only messages with the Deleted flags set, they'll all go away (unless you've been weird and snuck other mail in there through sneaky means; those would stick around). Deleted messages in other mailboxes, however, simply remain present and invisible to you, at least as long as you use Mail as your client.

If you leave this box unchecked, then Mail instead offers the Mailbox Compact Mailbox (-K) command. This will simply expunge the selected mailbox, permanently erasing all its unseen deleted messages and seeming to shrink the mailbox's size without affecting any of its visible messages. (Compact, in this case, is Mail's positive way of spinning the fact that it doesn't have a way to deal with deleted mail in arbitrary IMAP mailboxes, and so they appear as so much deadweight.)

Note that both these commands share the -K keybinding, so pressing this combo will always erase deleted mail, one way or another.