11.10 imaplib -- IMAP4 protocol client

Python PEP

previous page next page

11.10 `imaplib` -- IMAP4 protocol client

This module defines three classes, IMAP4, IMAP4_SSL and IMAP4_stream, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in RFC 2060. It is backward compatible with IMAP4 (RFC 1730) servers, but note that the "STATUS" command is not supported in IMAP4.

Three classes are provided by the imaplib module, IMAP4 is the base class:

class IMAP4( [host[, port]]): This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If host is not specified, '' (the local host) is used. If port is omitted, the standard IMAP4 port (143) is used.

Three exceptions are defined as attributes of the IMAP4 class:

exception IMAP4.error: Exception raised on any errors. The reason for the exception is passed to the constructor as a string.

exception IMAP4.abort: IMAP4 server errors cause this exception to be raised. This is a sub-class of IMAP4.error. Note that closing the instance and instantiating a new one will usually allow recovery from this exception.

exception IMAP4.readonly: This exception is raised when a writable mailbox has its status changed by the server. This is a sub-class of IMAP4.error. Some other client now has write permission, and the mailbox will need to be re-opened to re-obtain write permission.

There's also a subclass for secure connections:

class IMAP4_SSL( [host[, port[, keyfile[, certfile]]]]): This is a subclass derived from IMAP4 that connects over an SSL encrypted socket (to use this class you need a socket module that was compiled with SSL support). If host is not specified, '' (the local host) is used. If port is omitted, the standard IMAP4-over-SSL port (993) is used. keyfile and certfile are also optional - they can contain a PEM formatted private key and certificate chain file for the SSL connection.

The second subclass allows for connections created by a child process:

class IMAP4_stream( command): This is a subclass derived from IMAP4 that connects to the stdin/stdout file descriptors created by passing command to os.popen2(). New in version 2.3.

The following utility functions are defined:

Internaldate2tuple( datestr): Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a time module tuple.

Int2AP( num): Converts an integer into a string representation using characters from the set [A .. P].

ParseFlags( flagstr): Converts an IMAP4 "FLAGS" response to a tuple of individual flags.

Time2Internaldate( date_time): Converts a time module tuple to an IMAP4 "INTERNALDATE" representation. Returns a string in the form: "DD-Mmm-YYYY HH:MM:SS +HHMM" (including double-quotes).

Note that IMAP4 message numbers change as the mailbox changes; in particular, after an "EXPUNGE" command performs deletions the remaining messages are renumbered. So it is highly advisable to use UIDs instead, with the UID command.

At the end of the module, there is a test section that contains a more extensive example of usage.