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

CHAPTER 15 ■ IMAP
Message Ranges
Most IMAP commands that work with messages can work with one or more messages. This can make
processing far faster if you need a whole group of messages. Instead of issuing separate commands and
receiving separate responses for each individual message, you can operate on a group of messages as a
whole. The operation works faster since you no longer have to deal with a network round-trip for every
single command.
When you supply a message number, you can instead supply a comma-separated list of message
numbers. And, if you want all messages whose numbers are in a range but you do not want to have to list
all of their numbers (or if you do not even know their numbers—maybe you want “everything starting
with message one” without having to fetch their numbers first), you can use a colon to separate the start
and end message numbers. An asterisk means “and all of the rest of the messages.” Here is an example
specification:
2,4:6,20:*
It means “message 2,” “messages 4 through 6,” and “message 20 through the end of the mail folder.”
Summary Information
When you first select a folder, the IMAP server provides some summary information about it—about the
folder itself and also about its messages.
The summary is returned by IMAPClient as a dictionary. Here are the keys that most IMAP servers
will return when you run select_folder():
• EXISTS: An integer giving the number of messages in the folder
• FLAGS: A list of the flags that can be set on messages in this folder
• RECENT: Specifies the server’s approximation of the number of messages that have
appeared in the folder since the last time an IMAP client ran select_folder() on
it.
• PERMANENTFLAGS: Specifies the list of custom flags that can be set on messages; this
is usually empty.
• UIDNEXT: The server’s guess about the UID that will be assigned to the next
incoming (or uploaded) message
• UIDVALIDITY: A string that can be used by clients to verify that the UID numbering
has not changed; if you come back to a folder and this is a different value than the
last time you connected, then the UID number has started over and your stored
UID values are no longer valid.
• UNSEEN: Specifies the message number of the first unseen message (one without
the \Seen flag) in the folder
Of these flags, servers are only required to return FLAGS, EXISTS, and RECENT, though most will
include at least UIDVALIDITY as well. Listing 15–5 shows an example program that reads and displays the
summary information of my INBOX mail folder.
249