• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1:mod:`imaplib` --- IMAP4 protocol client
2========================================
3
4.. module:: imaplib
5   :synopsis: IMAP4 protocol client (requires sockets).
6
7.. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
8.. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
9.. revised by ESR, January 2000
10.. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
11.. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
12   November 2002
13
14**Source code:** :source:`Lib/imaplib.py`
15
16.. index::
17   pair: IMAP4; protocol
18   pair: IMAP4_SSL; protocol
19   pair: IMAP4_stream; protocol
20
21--------------
22
23This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
24:class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
25implement a large subset of the IMAP4rev1 client protocol as defined in
26:rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
27note that the ``STATUS`` command is not supported in IMAP4.
28
29Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
30base class:
31
32
33.. class:: IMAP4(host='', port=IMAP4_PORT, timeout=None)
34
35   This class implements the actual IMAP4 protocol.  The connection is created and
36   protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
37   initialized. If *host* is not specified, ``''`` (the local host) is used. If
38   *port* is omitted, the standard IMAP4 port (143) is used. The optional *timeout*
39   parameter specifies a timeout in seconds for the connection attempt.
40   If timeout is not given or is None, the global default socket timeout is used.
41
42   The :class:`IMAP4` class supports the :keyword:`with` statement.  When used
43   like this, the IMAP4 ``LOGOUT`` command is issued automatically when the
44   :keyword:`!with` statement exits.  E.g.::
45
46    >>> from imaplib import IMAP4
47    >>> with IMAP4("domain.org") as M:
48    ...     M.noop()
49    ...
50    ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
51
52   .. versionchanged:: 3.5
53      Support for the :keyword:`with` statement was added.
54
55   .. versionchanged:: 3.9
56      The optional *timeout* parameter was added.
57
58Three exceptions are defined as attributes of the :class:`IMAP4` class:
59
60
61.. exception:: IMAP4.error
62
63   Exception raised on any errors.  The reason for the exception is passed to the
64   constructor as a string.
65
66
67.. exception:: IMAP4.abort
68
69   IMAP4 server errors cause this exception to be raised.  This is a sub-class of
70   :exc:`IMAP4.error`.  Note that closing the instance and instantiating a new one
71   will usually allow recovery from this exception.
72
73
74.. exception:: IMAP4.readonly
75
76   This exception is raised when a writable mailbox has its status changed by the
77   server.  This is a sub-class of :exc:`IMAP4.error`.  Some other client now has
78   write permission, and the mailbox will need to be re-opened to re-obtain write
79   permission.
80
81
82There's also a subclass for secure connections:
83
84
85.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, \
86                     certfile=None, ssl_context=None, timeout=None)
87
88   This is a subclass derived from :class:`IMAP4` that connects over an SSL
89   encrypted socket (to use this class you need a socket module that was compiled
90   with SSL support).  If *host* is not specified, ``''`` (the local host) is used.
91   If *port* is omitted, the standard IMAP4-over-SSL port (993) is used.
92   *ssl_context* is a :class:`ssl.SSLContext` object which allows bundling
93   SSL configuration options, certificates and private keys into a single
94   (potentially long-lived) structure.  Please read :ref:`ssl-security` for
95   best practices.
96
97   *keyfile* and *certfile* are a legacy alternative to *ssl_context* - they
98   can point to PEM-formatted private key and certificate chain files for
99   the SSL connection.  Note that the *keyfile*/*certfile* parameters are
100   mutually exclusive with *ssl_context*, a :class:`ValueError` is raised
101   if *keyfile*/*certfile* is provided along with *ssl_context*.
102
103   The optional *timeout* parameter specifies a timeout in seconds for the
104   connection attempt. If timeout is not given or is None, the global default
105   socket timeout is used.
106
107   .. versionchanged:: 3.3
108      *ssl_context* parameter was added.
109
110   .. versionchanged:: 3.4
111      The class now supports hostname check with
112      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
113      :data:`ssl.HAS_SNI`).
114
115   .. deprecated:: 3.6
116
117       *keyfile* and *certfile* are deprecated in favor of *ssl_context*.
118       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
119       :func:`ssl.create_default_context` select the system's trusted CA
120       certificates for you.
121
122   .. versionchanged:: 3.9
123      The optional *timeout* parameter was added.
124
125The second subclass allows for connections created by a child process:
126
127
128.. class:: IMAP4_stream(command)
129
130   This is a subclass derived from :class:`IMAP4` that connects to the
131   ``stdin/stdout`` file descriptors created by passing *command* to
132   ``subprocess.Popen()``.
133
134
135The following utility functions are defined:
136
137
138.. function:: Internaldate2tuple(datestr)
139
140   Parse an IMAP4 ``INTERNALDATE`` string and return corresponding local
141   time.  The return value is a :class:`time.struct_time` tuple or
142   ``None`` if the string has wrong format.
143
144.. function:: Int2AP(num)
145
146   Converts an integer into a bytes representation using characters from the set
147   [``A`` .. ``P``].
148
149
150.. function:: ParseFlags(flagstr)
151
152   Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.
153
154
155.. function:: Time2Internaldate(date_time)
156
157   Convert *date_time* to an IMAP4 ``INTERNALDATE`` representation.
158   The return value is a string in the form: ``"DD-Mmm-YYYY HH:MM:SS
159   +HHMM"`` (including double-quotes).  The *date_time* argument can
160   be a number (int or float) representing seconds since epoch (as
161   returned by :func:`time.time`), a 9-tuple representing local time
162   an instance of :class:`time.struct_time` (as returned by
163   :func:`time.localtime`), an aware instance of
164   :class:`datetime.datetime`, or a double-quoted string.  In the last
165   case, it is assumed to already be in the correct format.
166
167Note that IMAP4 message numbers change as the mailbox changes; in particular,
168after an ``EXPUNGE`` command performs deletions the remaining messages are
169renumbered. So it is highly advisable to use UIDs instead, with the UID command.
170
171At the end of the module, there is a test section that contains a more extensive
172example of usage.
173
174
175.. seealso::
176
177   Documents describing the protocol, sources for servers
178   implementing it, by the University of Washington's IMAP Information Center
179   can all be found at (**Source Code**) https://github.com/uw-imap/imap (**Not Maintained**).
180
181
182.. _imap4-objects:
183
184IMAP4 Objects
185-------------
186
187All IMAP4rev1 commands are represented by methods of the same name, either
188upper-case or lower-case.
189
190All arguments to commands are converted to strings, except for ``AUTHENTICATE``,
191and the last argument to ``APPEND`` which is passed as an IMAP4 literal.  If
192necessary (the string contains IMAP4 protocol-sensitive characters and isn't
193enclosed with either parentheses or double quotes) each string is quoted.
194However, the *password* argument to the ``LOGIN`` command is always quoted. If
195you want to avoid having an argument string quoted (eg: the *flags* argument to
196``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
197
198Each command returns a tuple: ``(type, [data, ...])`` where *type* is usually
199``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
200or mandated results from the command. Each *data* is either a ``bytes``, or a
201tuple. If a tuple, then the first part is the header of the response, and the
202second part contains the data (ie: 'literal' value).
203
204The *message_set* options to commands below is a string specifying one or more
205messages to be acted upon.  It may be a simple message number (``'1'``), a range
206of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
207commas (``'1:3,6:9'``).  A range can contain an asterisk to indicate an infinite
208upper bound (``'3:*'``).
209
210An :class:`IMAP4` instance has the following methods:
211
212
213.. method:: IMAP4.append(mailbox, flags, date_time, message)
214
215   Append *message* to named mailbox.
216
217
218.. method:: IMAP4.authenticate(mechanism, authobject)
219
220   Authenticate command --- requires response processing.
221
222   *mechanism* specifies which authentication mechanism is to be used - it should
223   appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.
224
225   *authobject* must be a callable object::
226
227      data = authobject(response)
228
229   It will be called to process server continuation responses; the *response*
230   argument it is passed will be ``bytes``.  It should return ``bytes`` *data*
231   that will be base64 encoded and sent to the server.  It should return
232   ``None`` if the client abort response ``*`` should be sent instead.
233
234   .. versionchanged:: 3.5
235      string usernames and passwords are now encoded to ``utf-8`` instead of
236      being limited to ASCII.
237
238
239.. method:: IMAP4.check()
240
241   Checkpoint mailbox on server.
242
243
244.. method:: IMAP4.close()
245
246   Close currently selected mailbox. Deleted messages are removed from writable
247   mailbox. This is the recommended command before ``LOGOUT``.
248
249
250.. method:: IMAP4.copy(message_set, new_mailbox)
251
252   Copy *message_set* messages onto end of *new_mailbox*.
253
254
255.. method:: IMAP4.create(mailbox)
256
257   Create new mailbox named *mailbox*.
258
259
260.. method:: IMAP4.delete(mailbox)
261
262   Delete old mailbox named *mailbox*.
263
264
265.. method:: IMAP4.deleteacl(mailbox, who)
266
267   Delete the ACLs (remove any rights) set for who on mailbox.
268
269
270.. method:: IMAP4.enable(capability)
271
272   Enable *capability* (see :rfc:`5161`).  Most capabilities do not need to be
273   enabled.  Currently only the ``UTF8=ACCEPT`` capability is supported
274   (see :RFC:`6855`).
275
276   .. versionadded:: 3.5
277      The :meth:`enable` method itself, and :RFC:`6855` support.
278
279
280.. method:: IMAP4.expunge()
281
282   Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
283   response for each deleted message. Returned data contains a list of ``EXPUNGE``
284   message numbers in order received.
285
286
287.. method:: IMAP4.fetch(message_set, message_parts)
288
289   Fetch (parts of) messages.  *message_parts* should be a string of message part
290   names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``.  Returned data
291   are tuples of message part envelope and data.
292
293
294.. method:: IMAP4.getacl(mailbox)
295
296   Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported
297   by the ``Cyrus`` server.
298
299
300.. method:: IMAP4.getannotation(mailbox, entry, attribute)
301
302   Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
303   non-standard, but is supported by the ``Cyrus`` server.
304
305
306.. method:: IMAP4.getquota(root)
307
308   Get the ``quota`` *root*'s resource usage and limits. This method is part of the
309   IMAP4 QUOTA extension defined in rfc2087.
310
311
312.. method:: IMAP4.getquotaroot(mailbox)
313
314   Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
315   of the IMAP4 QUOTA extension defined in rfc2087.
316
317
318.. method:: IMAP4.list([directory[, pattern]])
319
320   List mailbox names in *directory* matching *pattern*.  *directory* defaults to
321   the top-level mail folder, and *pattern* defaults to match anything.  Returned
322   data contains a list of ``LIST`` responses.
323
324
325.. method:: IMAP4.login(user, password)
326
327   Identify the client using a plaintext password. The *password* will be quoted.
328
329
330.. method:: IMAP4.login_cram_md5(user, password)
331
332   Force use of ``CRAM-MD5`` authentication when identifying the client to protect
333   the password.  Will only work if the server ``CAPABILITY`` response includes the
334   phrase ``AUTH=CRAM-MD5``.
335
336
337.. method:: IMAP4.logout()
338
339   Shutdown connection to server. Returns server ``BYE`` response.
340
341   .. versionchanged:: 3.8
342      The method no longer ignores silently arbitrary exceptions.
343
344
345.. method:: IMAP4.lsub(directory='""', pattern='*')
346
347   List subscribed mailbox names in directory matching pattern. *directory*
348   defaults to the top level directory and *pattern* defaults to match any mailbox.
349   Returned data are tuples of message part envelope and data.
350
351
352.. method:: IMAP4.myrights(mailbox)
353
354   Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
355
356
357.. method:: IMAP4.namespace()
358
359   Returns IMAP namespaces as defined in :rfc:`2342`.
360
361
362.. method:: IMAP4.noop()
363
364   Send ``NOOP`` to server.
365
366
367.. method:: IMAP4.open(host, port, timeout=None)
368
369   Opens socket to *port* at *host*. The optional *timeout* parameter
370   specifies a timeout in seconds for the connection attempt.
371   If timeout is not given or is None, the global default socket timeout
372   is used. Also note that if the *timeout* parameter is set to be zero,
373   it will raise a :class:`ValueError` to reject creating a non-blocking socket.
374   This method is implicitly called by the :class:`IMAP4` constructor.
375   The connection objects established by this method will be used in
376   the :meth:`IMAP4.read`, :meth:`IMAP4.readline`, :meth:`IMAP4.send`,
377   and :meth:`IMAP4.shutdown` methods. You may override this method.
378
379   .. audit-event:: imaplib.open self,host,port imaplib.IMAP4.open
380
381   .. versionchanged:: 3.9
382      The *timeout* parameter was added.
383
384.. method:: IMAP4.partial(message_num, message_part, start, length)
385
386   Fetch truncated part of a message. Returned data is a tuple of message part
387   envelope and data.
388
389
390.. method:: IMAP4.proxyauth(user)
391
392   Assume authentication as *user*. Allows an authorised administrator to proxy
393   into any user's mailbox.
394
395
396.. method:: IMAP4.read(size)
397
398   Reads *size* bytes from the remote server. You may override this method.
399
400
401.. method:: IMAP4.readline()
402
403   Reads one line from the remote server. You may override this method.
404
405
406.. method:: IMAP4.recent()
407
408   Prompt server for an update. Returned data is ``None`` if no new messages, else
409   value of ``RECENT`` response.
410
411
412.. method:: IMAP4.rename(oldmailbox, newmailbox)
413
414   Rename mailbox named *oldmailbox* to *newmailbox*.
415
416
417.. method:: IMAP4.response(code)
418
419   Return data for response *code* if received, or ``None``. Returns the given
420   code, instead of the usual type.
421
422
423.. method:: IMAP4.search(charset, criterion[, ...])
424
425   Search mailbox for matching messages.  *charset* may be ``None``, in which case
426   no ``CHARSET`` will be specified in the request to the server.  The IMAP
427   protocol requires that at least one criterion be specified; an exception will be
428   raised when the server returns an error.  *charset* must be ``None`` if
429   the ``UTF8=ACCEPT`` capability was enabled using the :meth:`enable`
430   command.
431
432   Example::
433
434      # M is a connected IMAP4 instance...
435      typ, msgnums = M.search(None, 'FROM', '"LDJ"')
436
437      # or:
438      typ, msgnums = M.search(None, '(FROM "LDJ")')
439
440
441.. method:: IMAP4.select(mailbox='INBOX', readonly=False)
442
443   Select a mailbox. Returned data is the count of messages in *mailbox*
444   (``EXISTS`` response).  The default *mailbox* is ``'INBOX'``.  If the *readonly*
445   flag is set, modifications to the mailbox are not allowed.
446
447
448.. method:: IMAP4.send(data)
449
450   Sends ``data`` to the remote server. You may override this method.
451
452   .. audit-event:: imaplib.send self,data imaplib.IMAP4.send
453
454
455.. method:: IMAP4.setacl(mailbox, who, what)
456
457   Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by
458   the ``Cyrus`` server.
459
460
461.. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])
462
463   Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
464   supported by the ``Cyrus`` server.
465
466
467.. method:: IMAP4.setquota(root, limits)
468
469   Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
470   QUOTA extension defined in rfc2087.
471
472
473.. method:: IMAP4.shutdown()
474
475   Close connection established in ``open``.  This method is implicitly
476   called by :meth:`IMAP4.logout`.  You may override this method.
477
478
479.. method:: IMAP4.socket()
480
481   Returns socket instance used to connect to server.
482
483
484.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
485
486   The ``sort`` command is a variant of ``search`` with sorting semantics for the
487   results.  Returned data contains a space separated list of matching message
488   numbers.
489
490   Sort has two arguments before the *search_criterion* argument(s); a
491   parenthesized list of *sort_criteria*, and the searching *charset*.  Note that
492   unlike ``search``, the searching *charset* argument is mandatory.  There is also
493   a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search``
494   corresponds to ``search``.  The ``sort`` command first searches the mailbox for
495   messages that match the given searching criteria using the charset argument for
496   the interpretation of strings in the searching criteria.  It then returns the
497   numbers of matching messages.
498
499   This is an ``IMAP4rev1`` extension command.
500
501
502.. method:: IMAP4.starttls(ssl_context=None)
503
504   Send a ``STARTTLS`` command.  The *ssl_context* argument is optional
505   and should be a :class:`ssl.SSLContext` object.  This will enable
506   encryption on the IMAP connection.  Please read :ref:`ssl-security` for
507   best practices.
508
509   .. versionadded:: 3.2
510
511   .. versionchanged:: 3.4
512      The method now supports hostname check with
513      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
514      :data:`ssl.HAS_SNI`).
515
516
517.. method:: IMAP4.status(mailbox, names)
518
519   Request named status conditions for *mailbox*.
520
521
522.. method:: IMAP4.store(message_set, command, flag_list)
523
524   Alters flag dispositions for messages in mailbox.  *command* is specified by
525   section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
526   optionally with a suffix of ".SILENT".
527
528   For example, to set the delete flag on all messages::
529
530      typ, data = M.search(None, 'ALL')
531      for num in data[0].split():
532         M.store(num, '+FLAGS', '\\Deleted')
533      M.expunge()
534
535   .. note::
536
537      Creating flags containing ']' (for example: "[test]") violates
538      :rfc:`3501` (the IMAP protocol).  However, imaplib has historically
539      allowed creation of such tags, and popular IMAP servers, such as Gmail,
540      accept and produce such flags.  There are non-Python programs which also
541      create such tags.  Although it is an RFC violation and IMAP clients and
542      servers are supposed to be strict, imaplib nonetheless continues to allow
543      such tags to be created for backward compatibility reasons, and as of
544      Python 3.6, handles them if they are sent from the server, since this
545      improves real-world compatibility.
546
547.. method:: IMAP4.subscribe(mailbox)
548
549   Subscribe to new mailbox.
550
551
552.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
553
554   The ``thread`` command is a variant of ``search`` with threading semantics for
555   the results.  Returned data contains a space separated list of thread members.
556
557   Thread members consist of zero or more messages numbers, delimited by spaces,
558   indicating successive parent and child.
559
560   Thread has two arguments before the *search_criterion* argument(s); a
561   *threading_algorithm*, and the searching *charset*.  Note that unlike
562   ``search``, the searching *charset* argument is mandatory.  There is also a
563   ``uid thread`` command which corresponds to ``thread`` the way that ``uid
564   search`` corresponds to ``search``.  The ``thread`` command first searches the
565   mailbox for messages that match the given searching criteria using the charset
566   argument for the interpretation of strings in the searching criteria. It then
567   returns the matching messages threaded according to the specified threading
568   algorithm.
569
570   This is an ``IMAP4rev1`` extension command.
571
572
573.. method:: IMAP4.uid(command, arg[, ...])
574
575   Execute command args with messages identified by UID, rather than message
576   number.  Returns response appropriate to command.  At least one argument must be
577   supplied; if none are provided, the server will return an error and an exception
578   will be raised.
579
580
581.. method:: IMAP4.unsubscribe(mailbox)
582
583   Unsubscribe from old mailbox.
584
585.. method:: IMAP4.unselect()
586
587   :meth:`imaplib.IMAP4.unselect` frees server's resources associated with the
588   selected mailbox and returns the server to the authenticated
589   state. This command performs the same actions as :meth:`imaplib.IMAP4.close`, except
590   that no messages are permanently removed from the currently
591   selected mailbox.
592
593   .. versionadded:: 3.9
594
595.. method:: IMAP4.xatom(name[, ...])
596
597   Allow simple extension commands notified by server in ``CAPABILITY`` response.
598
599
600The following attributes are defined on instances of :class:`IMAP4`:
601
602.. attribute:: IMAP4.PROTOCOL_VERSION
603
604   The most recent supported protocol in the ``CAPABILITY`` response from the
605   server.
606
607
608.. attribute:: IMAP4.debug
609
610   Integer value to control debugging output.  The initialize value is taken from
611   the module variable ``Debug``.  Values greater than three trace each command.
612
613
614.. attribute:: IMAP4.utf8_enabled
615
616   Boolean value that is normally ``False``, but is set to ``True`` if an
617   :meth:`enable` command is successfully issued for the ``UTF8=ACCEPT``
618   capability.
619
620   .. versionadded:: 3.5
621
622
623.. _imap4-example:
624
625IMAP4 Example
626-------------
627
628Here is a minimal example (without error checking) that opens a mailbox and
629retrieves and prints all messages::
630
631   import getpass, imaplib
632
633   M = imaplib.IMAP4()
634   M.login(getpass.getuser(), getpass.getpass())
635   M.select()
636   typ, data = M.search(None, 'ALL')
637   for num in data[0].split():
638       typ, data = M.fetch(num, '(RFC822)')
639       print('Message %s\n%s\n' % (num, data[0][1]))
640   M.close()
641   M.logout()
642
643