# 11.9 `imaplib` -- IMAP4 protocol client

This module defines a class, `IMAP4`, which encapsulates a connection to an IMAP4 server and implements 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.

A single class is provided by the `imaplib` module:

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.

Two 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.

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.

See Also:

Documents describing the protocol, and sources and binaries for servers implementing it, can all be found at the University of Washington's IMAP Information Center (http://www.cac.washington.edu/imap/).

Subsections

- 11.9.1 IMAP4 Objects
- 11.9.2 IMAP4 Example