17db96d56Sopenharmony_ci:mod:`imaplib` --- IMAP4 protocol client
27db96d56Sopenharmony_ci========================================
37db96d56Sopenharmony_ci
47db96d56Sopenharmony_ci.. module:: imaplib
57db96d56Sopenharmony_ci   :synopsis: IMAP4 protocol client (requires sockets).
67db96d56Sopenharmony_ci
77db96d56Sopenharmony_ci.. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
87db96d56Sopenharmony_ci.. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
97db96d56Sopenharmony_ci.. revised by ESR, January 2000
107db96d56Sopenharmony_ci.. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
117db96d56Sopenharmony_ci.. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
127db96d56Sopenharmony_ci   November 2002
137db96d56Sopenharmony_ci
147db96d56Sopenharmony_ci**Source code:** :source:`Lib/imaplib.py`
157db96d56Sopenharmony_ci
167db96d56Sopenharmony_ci.. index::
177db96d56Sopenharmony_ci   pair: IMAP4; protocol
187db96d56Sopenharmony_ci   pair: IMAP4_SSL; protocol
197db96d56Sopenharmony_ci   pair: IMAP4_stream; protocol
207db96d56Sopenharmony_ci
217db96d56Sopenharmony_ci--------------
227db96d56Sopenharmony_ci
237db96d56Sopenharmony_ciThis module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
247db96d56Sopenharmony_ci:class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
257db96d56Sopenharmony_ciimplement a large subset of the IMAP4rev1 client protocol as defined in
267db96d56Sopenharmony_ci:rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
277db96d56Sopenharmony_cinote that the ``STATUS`` command is not supported in IMAP4.
287db96d56Sopenharmony_ci
297db96d56Sopenharmony_ci.. include:: ../includes/wasm-notavail.rst
307db96d56Sopenharmony_ci
317db96d56Sopenharmony_ciThree classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
327db96d56Sopenharmony_cibase class:
337db96d56Sopenharmony_ci
347db96d56Sopenharmony_ci
357db96d56Sopenharmony_ci.. class:: IMAP4(host='', port=IMAP4_PORT, timeout=None)
367db96d56Sopenharmony_ci
377db96d56Sopenharmony_ci   This class implements the actual IMAP4 protocol.  The connection is created and
387db96d56Sopenharmony_ci   protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
397db96d56Sopenharmony_ci   initialized. If *host* is not specified, ``''`` (the local host) is used. If
407db96d56Sopenharmony_ci   *port* is omitted, the standard IMAP4 port (143) is used. The optional *timeout*
417db96d56Sopenharmony_ci   parameter specifies a timeout in seconds for the connection attempt.
427db96d56Sopenharmony_ci   If timeout is not given or is None, the global default socket timeout is used.
437db96d56Sopenharmony_ci
447db96d56Sopenharmony_ci   The :class:`IMAP4` class supports the :keyword:`with` statement.  When used
457db96d56Sopenharmony_ci   like this, the IMAP4 ``LOGOUT`` command is issued automatically when the
467db96d56Sopenharmony_ci   :keyword:`!with` statement exits.  E.g.::
477db96d56Sopenharmony_ci
487db96d56Sopenharmony_ci    >>> from imaplib import IMAP4
497db96d56Sopenharmony_ci    >>> with IMAP4("domain.org") as M:
507db96d56Sopenharmony_ci    ...     M.noop()
517db96d56Sopenharmony_ci    ...
527db96d56Sopenharmony_ci    ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
537db96d56Sopenharmony_ci
547db96d56Sopenharmony_ci   .. versionchanged:: 3.5
557db96d56Sopenharmony_ci      Support for the :keyword:`with` statement was added.
567db96d56Sopenharmony_ci
577db96d56Sopenharmony_ci   .. versionchanged:: 3.9
587db96d56Sopenharmony_ci      The optional *timeout* parameter was added.
597db96d56Sopenharmony_ci
607db96d56Sopenharmony_ciThree exceptions are defined as attributes of the :class:`IMAP4` class:
617db96d56Sopenharmony_ci
627db96d56Sopenharmony_ci
637db96d56Sopenharmony_ci.. exception:: IMAP4.error
647db96d56Sopenharmony_ci
657db96d56Sopenharmony_ci   Exception raised on any errors.  The reason for the exception is passed to the
667db96d56Sopenharmony_ci   constructor as a string.
677db96d56Sopenharmony_ci
687db96d56Sopenharmony_ci
697db96d56Sopenharmony_ci.. exception:: IMAP4.abort
707db96d56Sopenharmony_ci
717db96d56Sopenharmony_ci   IMAP4 server errors cause this exception to be raised.  This is a sub-class of
727db96d56Sopenharmony_ci   :exc:`IMAP4.error`.  Note that closing the instance and instantiating a new one
737db96d56Sopenharmony_ci   will usually allow recovery from this exception.
747db96d56Sopenharmony_ci
757db96d56Sopenharmony_ci
767db96d56Sopenharmony_ci.. exception:: IMAP4.readonly
777db96d56Sopenharmony_ci
787db96d56Sopenharmony_ci   This exception is raised when a writable mailbox has its status changed by the
797db96d56Sopenharmony_ci   server.  This is a sub-class of :exc:`IMAP4.error`.  Some other client now has
807db96d56Sopenharmony_ci   write permission, and the mailbox will need to be re-opened to re-obtain write
817db96d56Sopenharmony_ci   permission.
827db96d56Sopenharmony_ci
837db96d56Sopenharmony_ci
847db96d56Sopenharmony_ciThere's also a subclass for secure connections:
857db96d56Sopenharmony_ci
867db96d56Sopenharmony_ci
877db96d56Sopenharmony_ci.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, \
887db96d56Sopenharmony_ci                     certfile=None, ssl_context=None, timeout=None)
897db96d56Sopenharmony_ci
907db96d56Sopenharmony_ci   This is a subclass derived from :class:`IMAP4` that connects over an SSL
917db96d56Sopenharmony_ci   encrypted socket (to use this class you need a socket module that was compiled
927db96d56Sopenharmony_ci   with SSL support).  If *host* is not specified, ``''`` (the local host) is used.
937db96d56Sopenharmony_ci   If *port* is omitted, the standard IMAP4-over-SSL port (993) is used.
947db96d56Sopenharmony_ci   *ssl_context* is a :class:`ssl.SSLContext` object which allows bundling
957db96d56Sopenharmony_ci   SSL configuration options, certificates and private keys into a single
967db96d56Sopenharmony_ci   (potentially long-lived) structure.  Please read :ref:`ssl-security` for
977db96d56Sopenharmony_ci   best practices.
987db96d56Sopenharmony_ci
997db96d56Sopenharmony_ci   *keyfile* and *certfile* are a legacy alternative to *ssl_context* - they
1007db96d56Sopenharmony_ci   can point to PEM-formatted private key and certificate chain files for
1017db96d56Sopenharmony_ci   the SSL connection.  Note that the *keyfile*/*certfile* parameters are
1027db96d56Sopenharmony_ci   mutually exclusive with *ssl_context*, a :class:`ValueError` is raised
1037db96d56Sopenharmony_ci   if *keyfile*/*certfile* is provided along with *ssl_context*.
1047db96d56Sopenharmony_ci
1057db96d56Sopenharmony_ci   The optional *timeout* parameter specifies a timeout in seconds for the
1067db96d56Sopenharmony_ci   connection attempt. If timeout is not given or is None, the global default
1077db96d56Sopenharmony_ci   socket timeout is used.
1087db96d56Sopenharmony_ci
1097db96d56Sopenharmony_ci   .. versionchanged:: 3.3
1107db96d56Sopenharmony_ci      *ssl_context* parameter was added.
1117db96d56Sopenharmony_ci
1127db96d56Sopenharmony_ci   .. versionchanged:: 3.4
1137db96d56Sopenharmony_ci      The class now supports hostname check with
1147db96d56Sopenharmony_ci      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
1157db96d56Sopenharmony_ci      :data:`ssl.HAS_SNI`).
1167db96d56Sopenharmony_ci
1177db96d56Sopenharmony_ci   .. deprecated:: 3.6
1187db96d56Sopenharmony_ci
1197db96d56Sopenharmony_ci       *keyfile* and *certfile* are deprecated in favor of *ssl_context*.
1207db96d56Sopenharmony_ci       Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let
1217db96d56Sopenharmony_ci       :func:`ssl.create_default_context` select the system's trusted CA
1227db96d56Sopenharmony_ci       certificates for you.
1237db96d56Sopenharmony_ci
1247db96d56Sopenharmony_ci   .. versionchanged:: 3.9
1257db96d56Sopenharmony_ci      The optional *timeout* parameter was added.
1267db96d56Sopenharmony_ci
1277db96d56Sopenharmony_ciThe second subclass allows for connections created by a child process:
1287db96d56Sopenharmony_ci
1297db96d56Sopenharmony_ci
1307db96d56Sopenharmony_ci.. class:: IMAP4_stream(command)
1317db96d56Sopenharmony_ci
1327db96d56Sopenharmony_ci   This is a subclass derived from :class:`IMAP4` that connects to the
1337db96d56Sopenharmony_ci   ``stdin/stdout`` file descriptors created by passing *command* to
1347db96d56Sopenharmony_ci   ``subprocess.Popen()``.
1357db96d56Sopenharmony_ci
1367db96d56Sopenharmony_ci
1377db96d56Sopenharmony_ciThe following utility functions are defined:
1387db96d56Sopenharmony_ci
1397db96d56Sopenharmony_ci
1407db96d56Sopenharmony_ci.. function:: Internaldate2tuple(datestr)
1417db96d56Sopenharmony_ci
1427db96d56Sopenharmony_ci   Parse an IMAP4 ``INTERNALDATE`` string and return corresponding local
1437db96d56Sopenharmony_ci   time.  The return value is a :class:`time.struct_time` tuple or
1447db96d56Sopenharmony_ci   ``None`` if the string has wrong format.
1457db96d56Sopenharmony_ci
1467db96d56Sopenharmony_ci.. function:: Int2AP(num)
1477db96d56Sopenharmony_ci
1487db96d56Sopenharmony_ci   Converts an integer into a bytes representation using characters from the set
1497db96d56Sopenharmony_ci   [``A`` .. ``P``].
1507db96d56Sopenharmony_ci
1517db96d56Sopenharmony_ci
1527db96d56Sopenharmony_ci.. function:: ParseFlags(flagstr)
1537db96d56Sopenharmony_ci
1547db96d56Sopenharmony_ci   Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.
1557db96d56Sopenharmony_ci
1567db96d56Sopenharmony_ci
1577db96d56Sopenharmony_ci.. function:: Time2Internaldate(date_time)
1587db96d56Sopenharmony_ci
1597db96d56Sopenharmony_ci   Convert *date_time* to an IMAP4 ``INTERNALDATE`` representation.
1607db96d56Sopenharmony_ci   The return value is a string in the form: ``"DD-Mmm-YYYY HH:MM:SS
1617db96d56Sopenharmony_ci   +HHMM"`` (including double-quotes).  The *date_time* argument can
1627db96d56Sopenharmony_ci   be a number (int or float) representing seconds since epoch (as
1637db96d56Sopenharmony_ci   returned by :func:`time.time`), a 9-tuple representing local time
1647db96d56Sopenharmony_ci   an instance of :class:`time.struct_time` (as returned by
1657db96d56Sopenharmony_ci   :func:`time.localtime`), an aware instance of
1667db96d56Sopenharmony_ci   :class:`datetime.datetime`, or a double-quoted string.  In the last
1677db96d56Sopenharmony_ci   case, it is assumed to already be in the correct format.
1687db96d56Sopenharmony_ci
1697db96d56Sopenharmony_ciNote that IMAP4 message numbers change as the mailbox changes; in particular,
1707db96d56Sopenharmony_ciafter an ``EXPUNGE`` command performs deletions the remaining messages are
1717db96d56Sopenharmony_cirenumbered. So it is highly advisable to use UIDs instead, with the UID command.
1727db96d56Sopenharmony_ci
1737db96d56Sopenharmony_ciAt the end of the module, there is a test section that contains a more extensive
1747db96d56Sopenharmony_ciexample of usage.
1757db96d56Sopenharmony_ci
1767db96d56Sopenharmony_ci
1777db96d56Sopenharmony_ci.. seealso::
1787db96d56Sopenharmony_ci
1797db96d56Sopenharmony_ci   Documents describing the protocol, sources for servers
1807db96d56Sopenharmony_ci   implementing it, by the University of Washington's IMAP Information Center
1817db96d56Sopenharmony_ci   can all be found at (**Source Code**) https://github.com/uw-imap/imap (**Not Maintained**).
1827db96d56Sopenharmony_ci
1837db96d56Sopenharmony_ci
1847db96d56Sopenharmony_ci.. _imap4-objects:
1857db96d56Sopenharmony_ci
1867db96d56Sopenharmony_ciIMAP4 Objects
1877db96d56Sopenharmony_ci-------------
1887db96d56Sopenharmony_ci
1897db96d56Sopenharmony_ciAll IMAP4rev1 commands are represented by methods of the same name, either
1907db96d56Sopenharmony_ciupper-case or lower-case.
1917db96d56Sopenharmony_ci
1927db96d56Sopenharmony_ciAll arguments to commands are converted to strings, except for ``AUTHENTICATE``,
1937db96d56Sopenharmony_ciand the last argument to ``APPEND`` which is passed as an IMAP4 literal.  If
1947db96d56Sopenharmony_cinecessary (the string contains IMAP4 protocol-sensitive characters and isn't
1957db96d56Sopenharmony_cienclosed with either parentheses or double quotes) each string is quoted.
1967db96d56Sopenharmony_ciHowever, the *password* argument to the ``LOGIN`` command is always quoted. If
1977db96d56Sopenharmony_ciyou want to avoid having an argument string quoted (eg: the *flags* argument to
1987db96d56Sopenharmony_ci``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
1997db96d56Sopenharmony_ci
2007db96d56Sopenharmony_ciEach command returns a tuple: ``(type, [data, ...])`` where *type* is usually
2017db96d56Sopenharmony_ci``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
2027db96d56Sopenharmony_cior mandated results from the command. Each *data* is either a ``bytes``, or a
2037db96d56Sopenharmony_cituple. If a tuple, then the first part is the header of the response, and the
2047db96d56Sopenharmony_cisecond part contains the data (ie: 'literal' value).
2057db96d56Sopenharmony_ci
2067db96d56Sopenharmony_ciThe *message_set* options to commands below is a string specifying one or more
2077db96d56Sopenharmony_cimessages to be acted upon.  It may be a simple message number (``'1'``), a range
2087db96d56Sopenharmony_ciof message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
2097db96d56Sopenharmony_cicommas (``'1:3,6:9'``).  A range can contain an asterisk to indicate an infinite
2107db96d56Sopenharmony_ciupper bound (``'3:*'``).
2117db96d56Sopenharmony_ci
2127db96d56Sopenharmony_ciAn :class:`IMAP4` instance has the following methods:
2137db96d56Sopenharmony_ci
2147db96d56Sopenharmony_ci
2157db96d56Sopenharmony_ci.. method:: IMAP4.append(mailbox, flags, date_time, message)
2167db96d56Sopenharmony_ci
2177db96d56Sopenharmony_ci   Append *message* to named mailbox.
2187db96d56Sopenharmony_ci
2197db96d56Sopenharmony_ci
2207db96d56Sopenharmony_ci.. method:: IMAP4.authenticate(mechanism, authobject)
2217db96d56Sopenharmony_ci
2227db96d56Sopenharmony_ci   Authenticate command --- requires response processing.
2237db96d56Sopenharmony_ci
2247db96d56Sopenharmony_ci   *mechanism* specifies which authentication mechanism is to be used - it should
2257db96d56Sopenharmony_ci   appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.
2267db96d56Sopenharmony_ci
2277db96d56Sopenharmony_ci   *authobject* must be a callable object::
2287db96d56Sopenharmony_ci
2297db96d56Sopenharmony_ci      data = authobject(response)
2307db96d56Sopenharmony_ci
2317db96d56Sopenharmony_ci   It will be called to process server continuation responses; the *response*
2327db96d56Sopenharmony_ci   argument it is passed will be ``bytes``.  It should return ``bytes`` *data*
2337db96d56Sopenharmony_ci   that will be base64 encoded and sent to the server.  It should return
2347db96d56Sopenharmony_ci   ``None`` if the client abort response ``*`` should be sent instead.
2357db96d56Sopenharmony_ci
2367db96d56Sopenharmony_ci   .. versionchanged:: 3.5
2377db96d56Sopenharmony_ci      string usernames and passwords are now encoded to ``utf-8`` instead of
2387db96d56Sopenharmony_ci      being limited to ASCII.
2397db96d56Sopenharmony_ci
2407db96d56Sopenharmony_ci
2417db96d56Sopenharmony_ci.. method:: IMAP4.check()
2427db96d56Sopenharmony_ci
2437db96d56Sopenharmony_ci   Checkpoint mailbox on server.
2447db96d56Sopenharmony_ci
2457db96d56Sopenharmony_ci
2467db96d56Sopenharmony_ci.. method:: IMAP4.close()
2477db96d56Sopenharmony_ci
2487db96d56Sopenharmony_ci   Close currently selected mailbox. Deleted messages are removed from writable
2497db96d56Sopenharmony_ci   mailbox. This is the recommended command before ``LOGOUT``.
2507db96d56Sopenharmony_ci
2517db96d56Sopenharmony_ci
2527db96d56Sopenharmony_ci.. method:: IMAP4.copy(message_set, new_mailbox)
2537db96d56Sopenharmony_ci
2547db96d56Sopenharmony_ci   Copy *message_set* messages onto end of *new_mailbox*.
2557db96d56Sopenharmony_ci
2567db96d56Sopenharmony_ci
2577db96d56Sopenharmony_ci.. method:: IMAP4.create(mailbox)
2587db96d56Sopenharmony_ci
2597db96d56Sopenharmony_ci   Create new mailbox named *mailbox*.
2607db96d56Sopenharmony_ci
2617db96d56Sopenharmony_ci
2627db96d56Sopenharmony_ci.. method:: IMAP4.delete(mailbox)
2637db96d56Sopenharmony_ci
2647db96d56Sopenharmony_ci   Delete old mailbox named *mailbox*.
2657db96d56Sopenharmony_ci
2667db96d56Sopenharmony_ci
2677db96d56Sopenharmony_ci.. method:: IMAP4.deleteacl(mailbox, who)
2687db96d56Sopenharmony_ci
2697db96d56Sopenharmony_ci   Delete the ACLs (remove any rights) set for who on mailbox.
2707db96d56Sopenharmony_ci
2717db96d56Sopenharmony_ci
2727db96d56Sopenharmony_ci.. method:: IMAP4.enable(capability)
2737db96d56Sopenharmony_ci
2747db96d56Sopenharmony_ci   Enable *capability* (see :rfc:`5161`).  Most capabilities do not need to be
2757db96d56Sopenharmony_ci   enabled.  Currently only the ``UTF8=ACCEPT`` capability is supported
2767db96d56Sopenharmony_ci   (see :RFC:`6855`).
2777db96d56Sopenharmony_ci
2787db96d56Sopenharmony_ci   .. versionadded:: 3.5
2797db96d56Sopenharmony_ci      The :meth:`enable` method itself, and :RFC:`6855` support.
2807db96d56Sopenharmony_ci
2817db96d56Sopenharmony_ci
2827db96d56Sopenharmony_ci.. method:: IMAP4.expunge()
2837db96d56Sopenharmony_ci
2847db96d56Sopenharmony_ci   Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
2857db96d56Sopenharmony_ci   response for each deleted message. Returned data contains a list of ``EXPUNGE``
2867db96d56Sopenharmony_ci   message numbers in order received.
2877db96d56Sopenharmony_ci
2887db96d56Sopenharmony_ci
2897db96d56Sopenharmony_ci.. method:: IMAP4.fetch(message_set, message_parts)
2907db96d56Sopenharmony_ci
2917db96d56Sopenharmony_ci   Fetch (parts of) messages.  *message_parts* should be a string of message part
2927db96d56Sopenharmony_ci   names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``.  Returned data
2937db96d56Sopenharmony_ci   are tuples of message part envelope and data.
2947db96d56Sopenharmony_ci
2957db96d56Sopenharmony_ci
2967db96d56Sopenharmony_ci.. method:: IMAP4.getacl(mailbox)
2977db96d56Sopenharmony_ci
2987db96d56Sopenharmony_ci   Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported
2997db96d56Sopenharmony_ci   by the ``Cyrus`` server.
3007db96d56Sopenharmony_ci
3017db96d56Sopenharmony_ci
3027db96d56Sopenharmony_ci.. method:: IMAP4.getannotation(mailbox, entry, attribute)
3037db96d56Sopenharmony_ci
3047db96d56Sopenharmony_ci   Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
3057db96d56Sopenharmony_ci   non-standard, but is supported by the ``Cyrus`` server.
3067db96d56Sopenharmony_ci
3077db96d56Sopenharmony_ci
3087db96d56Sopenharmony_ci.. method:: IMAP4.getquota(root)
3097db96d56Sopenharmony_ci
3107db96d56Sopenharmony_ci   Get the ``quota`` *root*'s resource usage and limits. This method is part of the
3117db96d56Sopenharmony_ci   IMAP4 QUOTA extension defined in rfc2087.
3127db96d56Sopenharmony_ci
3137db96d56Sopenharmony_ci
3147db96d56Sopenharmony_ci.. method:: IMAP4.getquotaroot(mailbox)
3157db96d56Sopenharmony_ci
3167db96d56Sopenharmony_ci   Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
3177db96d56Sopenharmony_ci   of the IMAP4 QUOTA extension defined in rfc2087.
3187db96d56Sopenharmony_ci
3197db96d56Sopenharmony_ci
3207db96d56Sopenharmony_ci.. method:: IMAP4.list([directory[, pattern]])
3217db96d56Sopenharmony_ci
3227db96d56Sopenharmony_ci   List mailbox names in *directory* matching *pattern*.  *directory* defaults to
3237db96d56Sopenharmony_ci   the top-level mail folder, and *pattern* defaults to match anything.  Returned
3247db96d56Sopenharmony_ci   data contains a list of ``LIST`` responses.
3257db96d56Sopenharmony_ci
3267db96d56Sopenharmony_ci
3277db96d56Sopenharmony_ci.. method:: IMAP4.login(user, password)
3287db96d56Sopenharmony_ci
3297db96d56Sopenharmony_ci   Identify the client using a plaintext password. The *password* will be quoted.
3307db96d56Sopenharmony_ci
3317db96d56Sopenharmony_ci
3327db96d56Sopenharmony_ci.. method:: IMAP4.login_cram_md5(user, password)
3337db96d56Sopenharmony_ci
3347db96d56Sopenharmony_ci   Force use of ``CRAM-MD5`` authentication when identifying the client to protect
3357db96d56Sopenharmony_ci   the password.  Will only work if the server ``CAPABILITY`` response includes the
3367db96d56Sopenharmony_ci   phrase ``AUTH=CRAM-MD5``.
3377db96d56Sopenharmony_ci
3387db96d56Sopenharmony_ci
3397db96d56Sopenharmony_ci.. method:: IMAP4.logout()
3407db96d56Sopenharmony_ci
3417db96d56Sopenharmony_ci   Shutdown connection to server. Returns server ``BYE`` response.
3427db96d56Sopenharmony_ci
3437db96d56Sopenharmony_ci   .. versionchanged:: 3.8
3447db96d56Sopenharmony_ci      The method no longer ignores silently arbitrary exceptions.
3457db96d56Sopenharmony_ci
3467db96d56Sopenharmony_ci
3477db96d56Sopenharmony_ci.. method:: IMAP4.lsub(directory='""', pattern='*')
3487db96d56Sopenharmony_ci
3497db96d56Sopenharmony_ci   List subscribed mailbox names in directory matching pattern. *directory*
3507db96d56Sopenharmony_ci   defaults to the top level directory and *pattern* defaults to match any mailbox.
3517db96d56Sopenharmony_ci   Returned data are tuples of message part envelope and data.
3527db96d56Sopenharmony_ci
3537db96d56Sopenharmony_ci
3547db96d56Sopenharmony_ci.. method:: IMAP4.myrights(mailbox)
3557db96d56Sopenharmony_ci
3567db96d56Sopenharmony_ci   Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
3577db96d56Sopenharmony_ci
3587db96d56Sopenharmony_ci
3597db96d56Sopenharmony_ci.. method:: IMAP4.namespace()
3607db96d56Sopenharmony_ci
3617db96d56Sopenharmony_ci   Returns IMAP namespaces as defined in :rfc:`2342`.
3627db96d56Sopenharmony_ci
3637db96d56Sopenharmony_ci
3647db96d56Sopenharmony_ci.. method:: IMAP4.noop()
3657db96d56Sopenharmony_ci
3667db96d56Sopenharmony_ci   Send ``NOOP`` to server.
3677db96d56Sopenharmony_ci
3687db96d56Sopenharmony_ci
3697db96d56Sopenharmony_ci.. method:: IMAP4.open(host, port, timeout=None)
3707db96d56Sopenharmony_ci
3717db96d56Sopenharmony_ci   Opens socket to *port* at *host*. The optional *timeout* parameter
3727db96d56Sopenharmony_ci   specifies a timeout in seconds for the connection attempt.
3737db96d56Sopenharmony_ci   If timeout is not given or is None, the global default socket timeout
3747db96d56Sopenharmony_ci   is used. Also note that if the *timeout* parameter is set to be zero,
3757db96d56Sopenharmony_ci   it will raise a :class:`ValueError` to reject creating a non-blocking socket.
3767db96d56Sopenharmony_ci   This method is implicitly called by the :class:`IMAP4` constructor.
3777db96d56Sopenharmony_ci   The connection objects established by this method will be used in
3787db96d56Sopenharmony_ci   the :meth:`IMAP4.read`, :meth:`IMAP4.readline`, :meth:`IMAP4.send`,
3797db96d56Sopenharmony_ci   and :meth:`IMAP4.shutdown` methods. You may override this method.
3807db96d56Sopenharmony_ci
3817db96d56Sopenharmony_ci   .. audit-event:: imaplib.open self,host,port imaplib.IMAP4.open
3827db96d56Sopenharmony_ci
3837db96d56Sopenharmony_ci   .. versionchanged:: 3.9
3847db96d56Sopenharmony_ci      The *timeout* parameter was added.
3857db96d56Sopenharmony_ci
3867db96d56Sopenharmony_ci.. method:: IMAP4.partial(message_num, message_part, start, length)
3877db96d56Sopenharmony_ci
3887db96d56Sopenharmony_ci   Fetch truncated part of a message. Returned data is a tuple of message part
3897db96d56Sopenharmony_ci   envelope and data.
3907db96d56Sopenharmony_ci
3917db96d56Sopenharmony_ci
3927db96d56Sopenharmony_ci.. method:: IMAP4.proxyauth(user)
3937db96d56Sopenharmony_ci
3947db96d56Sopenharmony_ci   Assume authentication as *user*. Allows an authorised administrator to proxy
3957db96d56Sopenharmony_ci   into any user's mailbox.
3967db96d56Sopenharmony_ci
3977db96d56Sopenharmony_ci
3987db96d56Sopenharmony_ci.. method:: IMAP4.read(size)
3997db96d56Sopenharmony_ci
4007db96d56Sopenharmony_ci   Reads *size* bytes from the remote server. You may override this method.
4017db96d56Sopenharmony_ci
4027db96d56Sopenharmony_ci
4037db96d56Sopenharmony_ci.. method:: IMAP4.readline()
4047db96d56Sopenharmony_ci
4057db96d56Sopenharmony_ci   Reads one line from the remote server. You may override this method.
4067db96d56Sopenharmony_ci
4077db96d56Sopenharmony_ci
4087db96d56Sopenharmony_ci.. method:: IMAP4.recent()
4097db96d56Sopenharmony_ci
4107db96d56Sopenharmony_ci   Prompt server for an update. Returned data is ``None`` if no new messages, else
4117db96d56Sopenharmony_ci   value of ``RECENT`` response.
4127db96d56Sopenharmony_ci
4137db96d56Sopenharmony_ci
4147db96d56Sopenharmony_ci.. method:: IMAP4.rename(oldmailbox, newmailbox)
4157db96d56Sopenharmony_ci
4167db96d56Sopenharmony_ci   Rename mailbox named *oldmailbox* to *newmailbox*.
4177db96d56Sopenharmony_ci
4187db96d56Sopenharmony_ci
4197db96d56Sopenharmony_ci.. method:: IMAP4.response(code)
4207db96d56Sopenharmony_ci
4217db96d56Sopenharmony_ci   Return data for response *code* if received, or ``None``. Returns the given
4227db96d56Sopenharmony_ci   code, instead of the usual type.
4237db96d56Sopenharmony_ci
4247db96d56Sopenharmony_ci
4257db96d56Sopenharmony_ci.. method:: IMAP4.search(charset, criterion[, ...])
4267db96d56Sopenharmony_ci
4277db96d56Sopenharmony_ci   Search mailbox for matching messages.  *charset* may be ``None``, in which case
4287db96d56Sopenharmony_ci   no ``CHARSET`` will be specified in the request to the server.  The IMAP
4297db96d56Sopenharmony_ci   protocol requires that at least one criterion be specified; an exception will be
4307db96d56Sopenharmony_ci   raised when the server returns an error.  *charset* must be ``None`` if
4317db96d56Sopenharmony_ci   the ``UTF8=ACCEPT`` capability was enabled using the :meth:`enable`
4327db96d56Sopenharmony_ci   command.
4337db96d56Sopenharmony_ci
4347db96d56Sopenharmony_ci   Example::
4357db96d56Sopenharmony_ci
4367db96d56Sopenharmony_ci      # M is a connected IMAP4 instance...
4377db96d56Sopenharmony_ci      typ, msgnums = M.search(None, 'FROM', '"LDJ"')
4387db96d56Sopenharmony_ci
4397db96d56Sopenharmony_ci      # or:
4407db96d56Sopenharmony_ci      typ, msgnums = M.search(None, '(FROM "LDJ")')
4417db96d56Sopenharmony_ci
4427db96d56Sopenharmony_ci
4437db96d56Sopenharmony_ci.. method:: IMAP4.select(mailbox='INBOX', readonly=False)
4447db96d56Sopenharmony_ci
4457db96d56Sopenharmony_ci   Select a mailbox. Returned data is the count of messages in *mailbox*
4467db96d56Sopenharmony_ci   (``EXISTS`` response).  The default *mailbox* is ``'INBOX'``.  If the *readonly*
4477db96d56Sopenharmony_ci   flag is set, modifications to the mailbox are not allowed.
4487db96d56Sopenharmony_ci
4497db96d56Sopenharmony_ci
4507db96d56Sopenharmony_ci.. method:: IMAP4.send(data)
4517db96d56Sopenharmony_ci
4527db96d56Sopenharmony_ci   Sends ``data`` to the remote server. You may override this method.
4537db96d56Sopenharmony_ci
4547db96d56Sopenharmony_ci   .. audit-event:: imaplib.send self,data imaplib.IMAP4.send
4557db96d56Sopenharmony_ci
4567db96d56Sopenharmony_ci
4577db96d56Sopenharmony_ci.. method:: IMAP4.setacl(mailbox, who, what)
4587db96d56Sopenharmony_ci
4597db96d56Sopenharmony_ci   Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by
4607db96d56Sopenharmony_ci   the ``Cyrus`` server.
4617db96d56Sopenharmony_ci
4627db96d56Sopenharmony_ci
4637db96d56Sopenharmony_ci.. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])
4647db96d56Sopenharmony_ci
4657db96d56Sopenharmony_ci   Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
4667db96d56Sopenharmony_ci   supported by the ``Cyrus`` server.
4677db96d56Sopenharmony_ci
4687db96d56Sopenharmony_ci
4697db96d56Sopenharmony_ci.. method:: IMAP4.setquota(root, limits)
4707db96d56Sopenharmony_ci
4717db96d56Sopenharmony_ci   Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
4727db96d56Sopenharmony_ci   QUOTA extension defined in rfc2087.
4737db96d56Sopenharmony_ci
4747db96d56Sopenharmony_ci
4757db96d56Sopenharmony_ci.. method:: IMAP4.shutdown()
4767db96d56Sopenharmony_ci
4777db96d56Sopenharmony_ci   Close connection established in ``open``.  This method is implicitly
4787db96d56Sopenharmony_ci   called by :meth:`IMAP4.logout`.  You may override this method.
4797db96d56Sopenharmony_ci
4807db96d56Sopenharmony_ci
4817db96d56Sopenharmony_ci.. method:: IMAP4.socket()
4827db96d56Sopenharmony_ci
4837db96d56Sopenharmony_ci   Returns socket instance used to connect to server.
4847db96d56Sopenharmony_ci
4857db96d56Sopenharmony_ci
4867db96d56Sopenharmony_ci.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
4877db96d56Sopenharmony_ci
4887db96d56Sopenharmony_ci   The ``sort`` command is a variant of ``search`` with sorting semantics for the
4897db96d56Sopenharmony_ci   results.  Returned data contains a space separated list of matching message
4907db96d56Sopenharmony_ci   numbers.
4917db96d56Sopenharmony_ci
4927db96d56Sopenharmony_ci   Sort has two arguments before the *search_criterion* argument(s); a
4937db96d56Sopenharmony_ci   parenthesized list of *sort_criteria*, and the searching *charset*.  Note that
4947db96d56Sopenharmony_ci   unlike ``search``, the searching *charset* argument is mandatory.  There is also
4957db96d56Sopenharmony_ci   a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search``
4967db96d56Sopenharmony_ci   corresponds to ``search``.  The ``sort`` command first searches the mailbox for
4977db96d56Sopenharmony_ci   messages that match the given searching criteria using the charset argument for
4987db96d56Sopenharmony_ci   the interpretation of strings in the searching criteria.  It then returns the
4997db96d56Sopenharmony_ci   numbers of matching messages.
5007db96d56Sopenharmony_ci
5017db96d56Sopenharmony_ci   This is an ``IMAP4rev1`` extension command.
5027db96d56Sopenharmony_ci
5037db96d56Sopenharmony_ci
5047db96d56Sopenharmony_ci.. method:: IMAP4.starttls(ssl_context=None)
5057db96d56Sopenharmony_ci
5067db96d56Sopenharmony_ci   Send a ``STARTTLS`` command.  The *ssl_context* argument is optional
5077db96d56Sopenharmony_ci   and should be a :class:`ssl.SSLContext` object.  This will enable
5087db96d56Sopenharmony_ci   encryption on the IMAP connection.  Please read :ref:`ssl-security` for
5097db96d56Sopenharmony_ci   best practices.
5107db96d56Sopenharmony_ci
5117db96d56Sopenharmony_ci   .. versionadded:: 3.2
5127db96d56Sopenharmony_ci
5137db96d56Sopenharmony_ci   .. versionchanged:: 3.4
5147db96d56Sopenharmony_ci      The method now supports hostname check with
5157db96d56Sopenharmony_ci      :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see
5167db96d56Sopenharmony_ci      :data:`ssl.HAS_SNI`).
5177db96d56Sopenharmony_ci
5187db96d56Sopenharmony_ci
5197db96d56Sopenharmony_ci.. method:: IMAP4.status(mailbox, names)
5207db96d56Sopenharmony_ci
5217db96d56Sopenharmony_ci   Request named status conditions for *mailbox*.
5227db96d56Sopenharmony_ci
5237db96d56Sopenharmony_ci
5247db96d56Sopenharmony_ci.. method:: IMAP4.store(message_set, command, flag_list)
5257db96d56Sopenharmony_ci
5267db96d56Sopenharmony_ci   Alters flag dispositions for messages in mailbox.  *command* is specified by
5277db96d56Sopenharmony_ci   section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
5287db96d56Sopenharmony_ci   optionally with a suffix of ".SILENT".
5297db96d56Sopenharmony_ci
5307db96d56Sopenharmony_ci   For example, to set the delete flag on all messages::
5317db96d56Sopenharmony_ci
5327db96d56Sopenharmony_ci      typ, data = M.search(None, 'ALL')
5337db96d56Sopenharmony_ci      for num in data[0].split():
5347db96d56Sopenharmony_ci         M.store(num, '+FLAGS', '\\Deleted')
5357db96d56Sopenharmony_ci      M.expunge()
5367db96d56Sopenharmony_ci
5377db96d56Sopenharmony_ci   .. note::
5387db96d56Sopenharmony_ci
5397db96d56Sopenharmony_ci      Creating flags containing ']' (for example: "[test]") violates
5407db96d56Sopenharmony_ci      :rfc:`3501` (the IMAP protocol).  However, imaplib has historically
5417db96d56Sopenharmony_ci      allowed creation of such tags, and popular IMAP servers, such as Gmail,
5427db96d56Sopenharmony_ci      accept and produce such flags.  There are non-Python programs which also
5437db96d56Sopenharmony_ci      create such tags.  Although it is an RFC violation and IMAP clients and
5447db96d56Sopenharmony_ci      servers are supposed to be strict, imaplib nonetheless continues to allow
5457db96d56Sopenharmony_ci      such tags to be created for backward compatibility reasons, and as of
5467db96d56Sopenharmony_ci      Python 3.6, handles them if they are sent from the server, since this
5477db96d56Sopenharmony_ci      improves real-world compatibility.
5487db96d56Sopenharmony_ci
5497db96d56Sopenharmony_ci.. method:: IMAP4.subscribe(mailbox)
5507db96d56Sopenharmony_ci
5517db96d56Sopenharmony_ci   Subscribe to new mailbox.
5527db96d56Sopenharmony_ci
5537db96d56Sopenharmony_ci
5547db96d56Sopenharmony_ci.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
5557db96d56Sopenharmony_ci
5567db96d56Sopenharmony_ci   The ``thread`` command is a variant of ``search`` with threading semantics for
5577db96d56Sopenharmony_ci   the results.  Returned data contains a space separated list of thread members.
5587db96d56Sopenharmony_ci
5597db96d56Sopenharmony_ci   Thread members consist of zero or more messages numbers, delimited by spaces,
5607db96d56Sopenharmony_ci   indicating successive parent and child.
5617db96d56Sopenharmony_ci
5627db96d56Sopenharmony_ci   Thread has two arguments before the *search_criterion* argument(s); a
5637db96d56Sopenharmony_ci   *threading_algorithm*, and the searching *charset*.  Note that unlike
5647db96d56Sopenharmony_ci   ``search``, the searching *charset* argument is mandatory.  There is also a
5657db96d56Sopenharmony_ci   ``uid thread`` command which corresponds to ``thread`` the way that ``uid
5667db96d56Sopenharmony_ci   search`` corresponds to ``search``.  The ``thread`` command first searches the
5677db96d56Sopenharmony_ci   mailbox for messages that match the given searching criteria using the charset
5687db96d56Sopenharmony_ci   argument for the interpretation of strings in the searching criteria. It then
5697db96d56Sopenharmony_ci   returns the matching messages threaded according to the specified threading
5707db96d56Sopenharmony_ci   algorithm.
5717db96d56Sopenharmony_ci
5727db96d56Sopenharmony_ci   This is an ``IMAP4rev1`` extension command.
5737db96d56Sopenharmony_ci
5747db96d56Sopenharmony_ci
5757db96d56Sopenharmony_ci.. method:: IMAP4.uid(command, arg[, ...])
5767db96d56Sopenharmony_ci
5777db96d56Sopenharmony_ci   Execute command args with messages identified by UID, rather than message
5787db96d56Sopenharmony_ci   number.  Returns response appropriate to command.  At least one argument must be
5797db96d56Sopenharmony_ci   supplied; if none are provided, the server will return an error and an exception
5807db96d56Sopenharmony_ci   will be raised.
5817db96d56Sopenharmony_ci
5827db96d56Sopenharmony_ci
5837db96d56Sopenharmony_ci.. method:: IMAP4.unsubscribe(mailbox)
5847db96d56Sopenharmony_ci
5857db96d56Sopenharmony_ci   Unsubscribe from old mailbox.
5867db96d56Sopenharmony_ci
5877db96d56Sopenharmony_ci.. method:: IMAP4.unselect()
5887db96d56Sopenharmony_ci
5897db96d56Sopenharmony_ci   :meth:`imaplib.IMAP4.unselect` frees server's resources associated with the
5907db96d56Sopenharmony_ci   selected mailbox and returns the server to the authenticated
5917db96d56Sopenharmony_ci   state. This command performs the same actions as :meth:`imaplib.IMAP4.close`, except
5927db96d56Sopenharmony_ci   that no messages are permanently removed from the currently
5937db96d56Sopenharmony_ci   selected mailbox.
5947db96d56Sopenharmony_ci
5957db96d56Sopenharmony_ci   .. versionadded:: 3.9
5967db96d56Sopenharmony_ci
5977db96d56Sopenharmony_ci.. method:: IMAP4.xatom(name[, ...])
5987db96d56Sopenharmony_ci
5997db96d56Sopenharmony_ci   Allow simple extension commands notified by server in ``CAPABILITY`` response.
6007db96d56Sopenharmony_ci
6017db96d56Sopenharmony_ci
6027db96d56Sopenharmony_ciThe following attributes are defined on instances of :class:`IMAP4`:
6037db96d56Sopenharmony_ci
6047db96d56Sopenharmony_ci.. attribute:: IMAP4.PROTOCOL_VERSION
6057db96d56Sopenharmony_ci
6067db96d56Sopenharmony_ci   The most recent supported protocol in the ``CAPABILITY`` response from the
6077db96d56Sopenharmony_ci   server.
6087db96d56Sopenharmony_ci
6097db96d56Sopenharmony_ci
6107db96d56Sopenharmony_ci.. attribute:: IMAP4.debug
6117db96d56Sopenharmony_ci
6127db96d56Sopenharmony_ci   Integer value to control debugging output.  The initialize value is taken from
6137db96d56Sopenharmony_ci   the module variable ``Debug``.  Values greater than three trace each command.
6147db96d56Sopenharmony_ci
6157db96d56Sopenharmony_ci
6167db96d56Sopenharmony_ci.. attribute:: IMAP4.utf8_enabled
6177db96d56Sopenharmony_ci
6187db96d56Sopenharmony_ci   Boolean value that is normally ``False``, but is set to ``True`` if an
6197db96d56Sopenharmony_ci   :meth:`enable` command is successfully issued for the ``UTF8=ACCEPT``
6207db96d56Sopenharmony_ci   capability.
6217db96d56Sopenharmony_ci
6227db96d56Sopenharmony_ci   .. versionadded:: 3.5
6237db96d56Sopenharmony_ci
6247db96d56Sopenharmony_ci
6257db96d56Sopenharmony_ci.. _imap4-example:
6267db96d56Sopenharmony_ci
6277db96d56Sopenharmony_ciIMAP4 Example
6287db96d56Sopenharmony_ci-------------
6297db96d56Sopenharmony_ci
6307db96d56Sopenharmony_ciHere is a minimal example (without error checking) that opens a mailbox and
6317db96d56Sopenharmony_ciretrieves and prints all messages::
6327db96d56Sopenharmony_ci
6337db96d56Sopenharmony_ci   import getpass, imaplib
6347db96d56Sopenharmony_ci
6357db96d56Sopenharmony_ci   M = imaplib.IMAP4()
6367db96d56Sopenharmony_ci   M.login(getpass.getuser(), getpass.getpass())
6377db96d56Sopenharmony_ci   M.select()
6387db96d56Sopenharmony_ci   typ, data = M.search(None, 'ALL')
6397db96d56Sopenharmony_ci   for num in data[0].split():
6407db96d56Sopenharmony_ci       typ, data = M.fetch(num, '(RFC822)')
6417db96d56Sopenharmony_ci       print('Message %s\n%s\n' % (num, data[0][1]))
6427db96d56Sopenharmony_ci   M.close()
6437db96d56Sopenharmony_ci   M.logout()
6447db96d56Sopenharmony_ci
645