1 :mod:`imaplib` --- IMAP4 protocol client
2 ========================================
5 :synopsis: IMAP4 protocol client (requires sockets).
6 .. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
7 .. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
8 .. revised by ESR, January 2000
9 .. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
10 .. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
16 pair: IMAP4_SSL; protocol
17 pair: IMAP4_stream; protocol
19 This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
20 :class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
21 implement a large subset of the IMAP4rev1 client protocol as defined in
22 :rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
23 note that the ``STATUS`` command is not supported in IMAP4.
25 Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
29 .. class:: IMAP4([host[, port]])
31 This class implements the actual IMAP4 protocol. The connection is created and
32 protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
33 initialized. If *host* is not specified, ``''`` (the local host) is used. If
34 *port* is omitted, the standard IMAP4 port (143) is used.
36 Three exceptions are defined as attributes of the :class:`IMAP4` class:
39 .. exception:: IMAP4.error
41 Exception raised on any errors. The reason for the exception is passed to the
42 constructor as a string.
45 .. exception:: IMAP4.abort
47 IMAP4 server errors cause this exception to be raised. This is a sub-class of
48 :exc:`IMAP4.error`. Note that closing the instance and instantiating a new one
49 will usually allow recovery from this exception.
52 .. exception:: IMAP4.readonly
54 This exception is raised when a writable mailbox has its status changed by the
55 server. This is a sub-class of :exc:`IMAP4.error`. Some other client now has
56 write permission, and the mailbox will need to be re-opened to re-obtain write
59 There's also a subclass for secure connections:
62 .. class:: IMAP4_SSL([host[, port[, keyfile[, certfile]]]])
64 This is a subclass derived from :class:`IMAP4` that connects over an SSL
65 encrypted socket (to use this class you need a socket module that was compiled
66 with SSL support). If *host* is not specified, ``''`` (the local host) is used.
67 If *port* is omitted, the standard IMAP4-over-SSL port (993) is used. *keyfile*
68 and *certfile* are also optional - they can contain a PEM formatted private key
69 and certificate chain file for the SSL connection.
71 The second subclass allows for connections created by a child process:
74 .. class:: IMAP4_stream(command)
76 This is a subclass derived from :class:`IMAP4` that connects to the
77 ``stdin/stdout`` file descriptors created by passing *command* to
82 The following utility functions are defined:
85 .. function:: Internaldate2tuple(datestr)
87 Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a
88 :mod:`time` module tuple.
91 .. function:: Int2AP(num)
93 Converts an integer into a string representation using characters from the set
97 .. function:: ParseFlags(flagstr)
99 Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.
102 .. function:: Time2Internaldate(date_time)
104 Converts a :mod:`time` module tuple to an IMAP4 ``INTERNALDATE`` representation.
105 Returns a string in the form: ``"DD-Mmm-YYYY HH:MM:SS +HHMM"`` (including
108 Note that IMAP4 message numbers change as the mailbox changes; in particular,
109 after an ``EXPUNGE`` command performs deletions the remaining messages are
110 renumbered. So it is highly advisable to use UIDs instead, with the UID command.
112 At the end of the module, there is a test section that contains a more extensive
118 Documents describing the protocol, and sources and binaries for servers
119 implementing it, can all be found at the University of Washington's *IMAP
120 Information Center* (http://www.washington.edu/imap/).
128 All IMAP4rev1 commands are represented by methods of the same name, either
129 upper-case or lower-case.
131 All arguments to commands are converted to strings, except for ``AUTHENTICATE``,
132 and the last argument to ``APPEND`` which is passed as an IMAP4 literal. If
133 necessary (the string contains IMAP4 protocol-sensitive characters and isn't
134 enclosed with either parentheses or double quotes) each string is quoted.
135 However, the *password* argument to the ``LOGIN`` command is always quoted. If
136 you want to avoid having an argument string quoted (eg: the *flags* argument to
137 ``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
139 Each command returns a tuple: ``(type, [data, ...])`` where *type* is usually
140 ``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
141 or mandated results from the command. Each *data* is either a string, or a
142 tuple. If a tuple, then the first part is the header of the response, and the
143 second part contains the data (ie: 'literal' value).
145 The *message_set* options to commands below is a string specifying one or more
146 messages to be acted upon. It may be a simple message number (``'1'``), a range
147 of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
148 commas (``'1:3,6:9'``). A range can contain an asterisk to indicate an infinite
149 upper bound (``'3:*'``).
151 An :class:`IMAP4` instance has the following methods:
154 .. method:: IMAP4.append(mailbox, flags, date_time, message)
156 Append *message* to named mailbox.
159 .. method:: IMAP4.authenticate(mechanism, authobject)
161 Authenticate command --- requires response processing.
163 *mechanism* specifies which authentication mechanism is to be used - it should
164 appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.
166 *authobject* must be a callable object::
168 data = authobject(response)
170 It will be called to process server continuation responses. It should return
171 ``data`` that will be encoded and sent to server. It should return ``None`` if
172 the client abort response ``*`` should be sent instead.
175 .. method:: IMAP4.check()
177 Checkpoint mailbox on server.
180 .. method:: IMAP4.close()
182 Close currently selected mailbox. Deleted messages are removed from writable
183 mailbox. This is the recommended command before ``LOGOUT``.
186 .. method:: IMAP4.copy(message_set, new_mailbox)
188 Copy *message_set* messages onto end of *new_mailbox*.
191 .. method:: IMAP4.create(mailbox)
193 Create new mailbox named *mailbox*.
196 .. method:: IMAP4.delete(mailbox)
198 Delete old mailbox named *mailbox*.
201 .. method:: IMAP4.deleteacl(mailbox, who)
203 Delete the ACLs (remove any rights) set for who on mailbox.
205 .. versionadded:: 2.4
208 .. method:: IMAP4.expunge()
210 Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
211 response for each deleted message. Returned data contains a list of ``EXPUNGE``
212 message numbers in order received.
215 .. method:: IMAP4.fetch(message_set, message_parts)
217 Fetch (parts of) messages. *message_parts* should be a string of message part
218 names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``. Returned data
219 are tuples of message part envelope and data.
222 .. method:: IMAP4.getacl(mailbox)
224 Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported
225 by the ``Cyrus`` server.
228 .. method:: IMAP4.getannotation(mailbox, entry, attribute)
230 Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
231 non-standard, but is supported by the ``Cyrus`` server.
233 .. versionadded:: 2.5
236 .. method:: IMAP4.getquota(root)
238 Get the ``quota`` *root*'s resource usage and limits. This method is part of the
239 IMAP4 QUOTA extension defined in rfc2087.
241 .. versionadded:: 2.3
244 .. method:: IMAP4.getquotaroot(mailbox)
246 Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
247 of the IMAP4 QUOTA extension defined in rfc2087.
249 .. versionadded:: 2.3
252 .. method:: IMAP4.list([directory[, pattern]])
254 List mailbox names in *directory* matching *pattern*. *directory* defaults to
255 the top-level mail folder, and *pattern* defaults to match anything. Returned
256 data contains a list of ``LIST`` responses.
259 .. method:: IMAP4.login(user, password)
261 Identify the client using a plaintext password. The *password* will be quoted.
264 .. method:: IMAP4.login_cram_md5(user, password)
266 Force use of ``CRAM-MD5`` authentication when identifying the client to protect
267 the password. Will only work if the server ``CAPABILITY`` response includes the
268 phrase ``AUTH=CRAM-MD5``.
270 .. versionadded:: 2.3
273 .. method:: IMAP4.logout()
275 Shutdown connection to server. Returns server ``BYE`` response.
278 .. method:: IMAP4.lsub([directory[, pattern]])
280 List subscribed mailbox names in directory matching pattern. *directory*
281 defaults to the top level directory and *pattern* defaults to match any mailbox.
282 Returned data are tuples of message part envelope and data.
285 .. method:: IMAP4.myrights(mailbox)
287 Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
289 .. versionadded:: 2.4
292 .. method:: IMAP4.namespace()
294 Returns IMAP namespaces as defined in RFC2342.
296 .. versionadded:: 2.3
299 .. method:: IMAP4.noop()
301 Send ``NOOP`` to server.
304 .. method:: IMAP4.open(host, port)
306 Opens socket to *port* at *host*. The connection objects established by this
307 method will be used in the ``read``, ``readline``, ``send``, and ``shutdown``
308 methods. You may override this method.
311 .. method:: IMAP4.partial(message_num, message_part, start, length)
313 Fetch truncated part of a message. Returned data is a tuple of message part
317 .. method:: IMAP4.proxyauth(user)
319 Assume authentication as *user*. Allows an authorised administrator to proxy
320 into any user's mailbox.
322 .. versionadded:: 2.3
325 .. method:: IMAP4.read(size)
327 Reads *size* bytes from the remote server. You may override this method.
330 .. method:: IMAP4.readline()
332 Reads one line from the remote server. You may override this method.
335 .. method:: IMAP4.recent()
337 Prompt server for an update. Returned data is ``None`` if no new messages, else
338 value of ``RECENT`` response.
341 .. method:: IMAP4.rename(oldmailbox, newmailbox)
343 Rename mailbox named *oldmailbox* to *newmailbox*.
346 .. method:: IMAP4.response(code)
348 Return data for response *code* if received, or ``None``. Returns the given
349 code, instead of the usual type.
352 .. method:: IMAP4.search(charset, criterion[, ...])
354 Search mailbox for matching messages. *charset* may be ``None``, in which case
355 no ``CHARSET`` will be specified in the request to the server. The IMAP
356 protocol requires that at least one criterion be specified; an exception will be
357 raised when the server returns an error.
361 # M is a connected IMAP4 instance...
362 typ, msgnums = M.search(None, 'FROM', '"LDJ"')
365 typ, msgnums = M.search(None, '(FROM "LDJ")')
368 .. method:: IMAP4.select([mailbox[, readonly]])
370 Select a mailbox. Returned data is the count of messages in *mailbox*
371 (``EXISTS`` response). The default *mailbox* is ``'INBOX'``. If the *readonly*
372 flag is set, modifications to the mailbox are not allowed.
375 .. method:: IMAP4.send(data)
377 Sends ``data`` to the remote server. You may override this method.
380 .. method:: IMAP4.setacl(mailbox, who, what)
382 Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by
383 the ``Cyrus`` server.
386 .. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])
388 Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
389 supported by the ``Cyrus`` server.
391 .. versionadded:: 2.5
394 .. method:: IMAP4.setquota(root, limits)
396 Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
397 QUOTA extension defined in rfc2087.
399 .. versionadded:: 2.3
402 .. method:: IMAP4.shutdown()
404 Close connection established in ``open``. You may override this method.
407 .. method:: IMAP4.socket()
409 Returns socket instance used to connect to server.
412 .. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
414 The ``sort`` command is a variant of ``search`` with sorting semantics for the
415 results. Returned data contains a space separated list of matching message
418 Sort has two arguments before the *search_criterion* argument(s); a
419 parenthesized list of *sort_criteria*, and the searching *charset*. Note that
420 unlike ``search``, the searching *charset* argument is mandatory. There is also
421 a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search``
422 corresponds to ``search``. The ``sort`` command first searches the mailbox for
423 messages that match the given searching criteria using the charset argument for
424 the interpretation of strings in the searching criteria. It then returns the
425 numbers of matching messages.
427 This is an ``IMAP4rev1`` extension command.
430 .. method:: IMAP4.status(mailbox, names)
432 Request named status conditions for *mailbox*.
435 .. method:: IMAP4.store(message_set, command, flag_list)
437 Alters flag dispositions for messages in mailbox. *command* is specified by
438 section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
439 optionally with a suffix of ".SILENT".
441 For example, to set the delete flag on all messages::
443 typ, data = M.search(None, 'ALL')
444 for num in data[0].split():
445 M.store(num, '+FLAGS', '\\Deleted')
449 .. method:: IMAP4.subscribe(mailbox)
451 Subscribe to new mailbox.
454 .. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
456 The ``thread`` command is a variant of ``search`` with threading semantics for
457 the results. Returned data contains a space separated list of thread members.
459 Thread members consist of zero or more messages numbers, delimited by spaces,
460 indicating successive parent and child.
462 Thread has two arguments before the *search_criterion* argument(s); a
463 *threading_algorithm*, and the searching *charset*. Note that unlike
464 ``search``, the searching *charset* argument is mandatory. There is also a
465 ``uid thread`` command which corresponds to ``thread`` the way that ``uid
466 search`` corresponds to ``search``. The ``thread`` command first searches the
467 mailbox for messages that match the given searching criteria using the charset
468 argument for the interpretation of strings in the searching criteria. It then
469 returns the matching messages threaded according to the specified threading
472 This is an ``IMAP4rev1`` extension command.
474 .. versionadded:: 2.4
477 .. method:: IMAP4.uid(command, arg[, ...])
479 Execute command args with messages identified by UID, rather than message
480 number. Returns response appropriate to command. At least one argument must be
481 supplied; if none are provided, the server will return an error and an exception
485 .. method:: IMAP4.unsubscribe(mailbox)
487 Unsubscribe from old mailbox.
490 .. method:: IMAP4.xatom(name[, arg[, ...]])
492 Allow simple extension commands notified by server in ``CAPABILITY`` response.
494 Instances of :class:`IMAP4_SSL` have just one additional method:
497 .. method:: IMAP4_SSL.ssl()
499 Returns SSLObject instance used for the secure connection with the server.
501 The following attributes are defined on instances of :class:`IMAP4`:
504 .. attribute:: IMAP4.PROTOCOL_VERSION
506 The most recent supported protocol in the ``CAPABILITY`` response from the
510 .. attribute:: IMAP4.debug
512 Integer value to control debugging output. The initialize value is taken from
513 the module variable ``Debug``. Values greater than three trace each command.
521 Here is a minimal example (without error checking) that opens a mailbox and
522 retrieves and prints all messages::
524 import getpass, imaplib
527 M.login(getpass.getuser(), getpass.getpass())
529 typ, data = M.search(None, 'ALL')
530 for num in data[0].split():
531 typ, data = M.fetch(num, '(RFC822)')
532 print 'Message %s\n%s\n' % (num, data[0][1])