:mod:`imaplib` --- IMAP4 protocol client
This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
:class:`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 :mod:`imaplib` module, :class:`IMAP4` is the base class:
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 :class:`IMAP4` class:
There's also a subclass for secure connections:
This is a subclass derived from :class:`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:
This is a subclass derived from :class:`IMAP4` that connects to the
stdin/stdout
file descriptors created by passing command to
subprocess.Popen()
.
The following utility functions are defined:
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.
IMAP4 Objects
All IMAP4rev1 commands are represented by methods of the same name, either upper-case or lower-case.
All arguments to commands are converted to strings, except for AUTHENTICATE
,
and the last argument to APPEND
which is passed as an IMAP4 literal. If
necessary (the string contains IMAP4 protocol-sensitive characters and isn't
enclosed with either parentheses or double quotes) each string is quoted.
However, the password argument to the LOGIN
command is always quoted. If
you want to avoid having an argument string quoted (eg: the flags argument to
STORE
) then enclose the string in parentheses (eg: r'(\Deleted)'
).
Each command returns a tuple: (type, [data, ...])
where type is usually
'OK'
or 'NO'
, and data is either the text from the command response,
or mandated results from the command. Each data is either a string, or a
tuple. If a tuple, then the first part is the header of the response, and the
second part contains the data (ie: 'literal' value).
The message_set options to commands below is a string specifying one or more
messages to be acted upon. It may be a simple message number ('1'
), a range
of message numbers ('2:4'
), or a group of non-contiguous ranges separated by
commas ('1:3,6:9'
). A range can contain an asterisk to indicate an infinite
upper bound ('3:*'
).
An :class:`IMAP4` instance has the following methods:
The following attributes are defined on instances of :class:`IMAP4`:
IMAP4 Example
Here is a minimal example (without error checking) that opens a mailbox and retrieves and prints all messages:
import getpass, imaplib
M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
typ, data = M.fetch(num, '(RFC822)')
print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()