Foundations of Python Network Programming

Chapter 15 ■ IMap

268

the IMap prOtOCOL

purpose: read, arrange, and delete e-mail from e-mail folders

Standard: rFC 3501 (2003)

runs atop: tCp/Ip

Default port: 143 (cleartext), 993 (SSL)

Library: imaplib, IMapClient

Exceptions: socket.error, socket.gaierror, IMAP4.error,

IMAP4.abort, IMAP4.readonly

IMap clients can also synchronize themselves with an IMap server. Someone about to leave on a business trip might

download an IMap folder to a laptop. then, on the road, e-mail might be read, deleted, or replied to, and the user’s

e-mail program would record these actions. When the laptop finally reconnects to the network, their e-mail client can

mark the messages on the server with the same “read” or “replied” flags already set locally, and it can go ahead and

delete the messages from the server that were already deleted locally so that the user does not see them twice.

The result is one of IMAP’s biggest advantages over POP: users can see the same e-mail, in the same state, from
all of their laptop and desktop machines. POP users can only see the same e-mail multiple times (if they tell their
e-mail clients to leave e-mail on the server), or each message will be downloaded only once to the machine on which
they happen to read it (if the e-mail clients delete the mail), which means that their e-mail winds up scattered across
all of the machines from which they check it. IMAP users avoid this dilemma.
Of course, IMAP can also be used in exactly the same manner as POP—to download mail, store it locally, and
delete the messages immediately from the server—for those who do not want or need its advanced features.
There are several versions of the IMAP protocol available. The most recent, and by far the most popular, is known
as IMAP4rev1. In fact, the term “IMAP” is today generally synonymous with IMAP4rev1. This chapter assumes that all
IMAP servers are IMAP4rev1 servers. Very old IMAP servers, which are quite uncommon, may not support all of the
features discussed in this chapter.
You can also access a good how-to tutorial about writing an IMAP client at the following links:

http://www.dovecot.org/imap-client-coding-howto.html
http://www.imapwiki.org/ClientImplementation

If you are doing anything beyond simply writing a small, single-purpose client to summarize the messages in
your in box or automatically download attachments, then you should read the information at the foregoing resources
thoroughly—or read a book on IMAP, if you want a more thorough reference—so that you can correctly handle all of
the situations you might run into with different servers and their implementations of IMAP. This chapter will teach
just the basics, with a focus on how best to connect from Python.

Understanding IMAP in Python

The Python Standard Library contains an IMAP client interface, named imaplib, which offers rudimentary access to
the protocol. Unfortunately, it limits itself to knowing how to send requests and deliver their responses back to your
code. It makes no actual attempt to implement the detailed rules in the IMAP specification for parsing the returned
data. As an example of how values returned from imaplib are usually too raw to be useful in a program, take a look at
Listing 15-1. It is a simple script that uses imaplib to connect to an IMAP account, list the “capabilities” that the server
advertises, and then display the status code and data returned by the LIST command.