Foundations of Python Network Programming 978-1-4302-3004-5

CHAPTER 15 ■ IMAP
Like many Internet protocols (HTTP comes immediately to mind), IMAP internally uses CR-LF
('\r\n' in Python) to designate the end of a line. Some IMAP servers will have problems if you upload a
message that uses any other character for the end of a line. Therefore, you must always be careful to
have the correct line endings when you translate uploaded messages. This problem is more common
than you might expect, since most local mailbox formats use only '\n' for the end of each line.
However, you must also be cautious in how carefully you change the line endings, because some
messages may use '\r\n' somewhere inside despite using only '\n' for the first few dozen lines, and
IMAP clients have been known to fail if a message uses both different line endings! The solution is a
simple one, thanks to Python’s powerful splitlines() string method that recognizes all three possible
line endings; simply call the function on your message and then re-join the lines with the standard line
ending:
>>> 'one\rtwo\nthree\r\nfour'.splitlines()
['one', 'two', 'three', 'four']
>>> '\r\n'.join('one\rtwo\nthree\r\nfour'.splitlines())
'one\r\ntwo\r\nthree\r\nfour'
The actual act of appending a message, once you have the line endings correct, is to call the
append() method on your IMAP client:
c.append('INBOX', my_message)
You can also supply a list of flags as a keyword argument, as well as a msg_time to be used as its
arrival time by passing a normal Python datetime object.
Asynchrony
Finally, a major admission needs be made about this chapter’s approach toward IMAP: even though we
have described IMAP as though the protocol were synchronous, it in fact supports clients that want to
send dozens of requests down the socket to the server and then receive the answers back in whatever
order the server can most efficiently fetch the mail from disk and respond.
The IMAPClient library hides this protocol flexibility by always sending one request, waiting for the
response, and then returning that value. But other libraries—and in particular the IMAP capabilities
provided inside Twisted Python—let you take advantage of its asynchronicity.
But for most Python programmers needing to script mailbox interactions, the synchronous
approach taken in this chapter should work just fine.
Summary
IMAP is a robust protocol for accessing e-mail messages stored on a remote server. Many IMAP libraries
exist for Python; imaplib is built into the Standard Library, but requires you to do all sorts of low-level
response parsing by yourself. A far better choice is IMAPClient by Menno Smits, which you can install
from the Python Package Index.
On an IMAP server, your e-mail messages are grouped into folders, some of which will come predefined
by your particular IMAP provider and some of which you can create yourself. An IMAP client can
create folders, delete folders, insert new messages into a folder, and move existing messages between
folders.
Once a folder has been selected, which is the IMAP rough equivalent of a “change directory”
command on a filesystem, messages can be listed and fetched very flexibly. Instead of having to
download every message in its entirety—though, of course, that is an option—the client can ask for
particular information from a message, like a few headers and its message structure, in order to build a
261