1 :mod:`imaplib` --- IMAP4 protocol client

     2 ========================================

     3 

     4 .. module:: imaplib

     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>,

    11    November 2002

    12 

    13 

    14 .. index::

    15    pair: IMAP4; protocol

    16    pair: IMAP4_SSL; protocol

    17    pair: IMAP4_stream; protocol

    18 

    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.

    24 

    25 Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the

    26 base class:

    27 

    28 

    29 .. class:: IMAP4([host[, port]])

    30 

    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.

    35 

    36 Three exceptions are defined as attributes of the :class:`IMAP4` class:

    37 

    38 

    39 .. exception:: IMAP4.error

    40 

    41    Exception raised on any errors.  The reason for the exception is passed to the

    42    constructor as a string.

    43 

    44 

    45 .. exception:: IMAP4.abort

    46 

    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.

    50 

    51 

    52 .. exception:: IMAP4.readonly

    53 

    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

    57    permission.

    58 

    59 There's also a subclass for secure connections:

    60 

    61 

    62 .. class:: IMAP4_SSL([host[, port[, keyfile[, certfile]]]])

    63 

    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.

    70 

    71 The second subclass allows for connections created by a child process:

    72 

    73 

    74 .. class:: IMAP4_stream(command)

    75 

    76    This is a subclass derived from :class:`IMAP4` that connects to the

    77    ``stdin/stdout`` file descriptors created by passing *command* to

    78    ``os.popen2()``.

    79 

    80    .. versionadded:: 2.3

    81 

    82 The following utility functions are defined:

    83 

    84 

    85 .. function:: Internaldate2tuple(datestr)

    86 

    87    Converts an IMAP4 INTERNALDATE string to Coordinated Universal Time. Returns a

    88    :mod:`time` module tuple.

    89 

    90 

    91 .. function:: Int2AP(num)

    92 

    93    Converts an integer into a string representation using characters from the set

    94    [``A`` .. ``P``].

    95 

    96 

    97 .. function:: ParseFlags(flagstr)

    98 

    99    Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.

   100 

   101 

   102 .. function:: Time2Internaldate(date_time)

   103 

   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

   106    double-quotes).

   107 

   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.

   111 

   112 At the end of the module, there is a test section that contains a more extensive

   113 example of usage.

   114 

   115 

   116 .. seealso::

   117 

   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/).

   121 

   122 

   123 .. _imap4-objects:

   124 

   125 IMAP4 Objects

   126 -------------

   127 

   128 All IMAP4rev1 commands are represented by methods of the same name, either

   129 upper-case or lower-case.

   130 

   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)'``).

   138 

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

   144 

   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:*'``).

   150 

   151 An :class:`IMAP4` instance has the following methods:

   152 

   153 

   154 .. method:: IMAP4.append(mailbox, flags, date_time, message)

   155 

   156    Append *message* to named mailbox.

   157 

   158 

   159 .. method:: IMAP4.authenticate(mechanism, authobject)

   160 

   161    Authenticate command --- requires response processing.

   162 

   163    *mechanism* specifies which authentication mechanism is to be used - it should

   164    appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.

   165 

   166    *authobject* must be a callable object::

   167 

   168       data = authobject(response)

   169 

   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.

   173 

   174 

   175 .. method:: IMAP4.check()

   176 

   177    Checkpoint mailbox on server.

   178 

   179 

   180 .. method:: IMAP4.close()

   181 

   182    Close currently selected mailbox. Deleted messages are removed from writable

   183    mailbox. This is the recommended command before ``LOGOUT``.

   184 

   185 

   186 .. method:: IMAP4.copy(message_set, new_mailbox)

   187 

   188    Copy *message_set* messages onto end of *new_mailbox*.

   189 

   190 

   191 .. method:: IMAP4.create(mailbox)

   192 

   193    Create new mailbox named *mailbox*.

   194 

   195 

   196 .. method:: IMAP4.delete(mailbox)

   197 

   198    Delete old mailbox named *mailbox*.

   199 

   200 

   201 .. method:: IMAP4.deleteacl(mailbox, who)

   202 

   203    Delete the ACLs (remove any rights) set for who on mailbox.

   204 

   205    .. versionadded:: 2.4

   206 

   207 

   208 .. method:: IMAP4.expunge()

   209 

   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.

   213 

   214 

   215 .. method:: IMAP4.fetch(message_set, message_parts)

   216 

   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.

   220 

   221 

   222 .. method:: IMAP4.getacl(mailbox)

   223 

   224    Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported

   225    by the ``Cyrus`` server.

   226 

   227 

   228 .. method:: IMAP4.getannotation(mailbox, entry, attribute)

   229 

   230    Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is

   231    non-standard, but is supported by the ``Cyrus`` server.

   232 

   233    .. versionadded:: 2.5

   234 

   235 

   236 .. method:: IMAP4.getquota(root)

   237 

   238    Get the ``quota`` *root*'s resource usage and limits. This method is part of the

   239    IMAP4 QUOTA extension defined in rfc2087.

   240 

   241    .. versionadded:: 2.3

   242 

   243 

   244 .. method:: IMAP4.getquotaroot(mailbox)

   245 

   246    Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part

   247    of the IMAP4 QUOTA extension defined in rfc2087.

   248 

   249    .. versionadded:: 2.3

   250 

   251 

   252 .. method:: IMAP4.list([directory[, pattern]])

   253 

   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.

   257 

   258 

   259 .. method:: IMAP4.login(user, password)

   260 

   261    Identify the client using a plaintext password. The *password* will be quoted.

   262 

   263 

   264 .. method:: IMAP4.login_cram_md5(user, password)

   265 

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

   269 

   270    .. versionadded:: 2.3

   271 

   272 

   273 .. method:: IMAP4.logout()

   274 

   275    Shutdown connection to server. Returns server ``BYE`` response.

   276 

   277 

   278 .. method:: IMAP4.lsub([directory[, pattern]])

   279 

   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.

   283 

   284 

   285 .. method:: IMAP4.myrights(mailbox)

   286 

   287    Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).

   288 

   289    .. versionadded:: 2.4

   290 

   291 

   292 .. method:: IMAP4.namespace()

   293 

   294    Returns IMAP namespaces as defined in RFC2342.

   295 

   296    .. versionadded:: 2.3

   297 

   298 

   299 .. method:: IMAP4.noop()

   300 

   301    Send ``NOOP`` to server.

   302 

   303 

   304 .. method:: IMAP4.open(host, port)

   305 

   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.

   309 

   310 

   311 .. method:: IMAP4.partial(message_num, message_part, start, length)

   312 

   313    Fetch truncated part of a message. Returned data is a tuple of message part

   314    envelope and data.

   315 

   316 

   317 .. method:: IMAP4.proxyauth(user)

   318 

   319    Assume authentication as *user*. Allows an authorised administrator to proxy

   320    into any user's mailbox.

   321 

   322    .. versionadded:: 2.3

   323 

   324 

   325 .. method:: IMAP4.read(size)

   326 

   327    Reads *size* bytes from the remote server. You may override this method.

   328 

   329 

   330 .. method:: IMAP4.readline()

   331 

   332    Reads one line from the remote server. You may override this method.

   333 

   334 

   335 .. method:: IMAP4.recent()

   336 

   337    Prompt server for an update. Returned data is ``None`` if no new messages, else

   338    value of ``RECENT`` response.

   339 

   340 

   341 .. method:: IMAP4.rename(oldmailbox, newmailbox)

   342 

   343    Rename mailbox named *oldmailbox* to *newmailbox*.

   344 

   345 

   346 .. method:: IMAP4.response(code)

   347 

   348    Return data for response *code* if received, or ``None``. Returns the given

   349    code, instead of the usual type.

   350 

   351 

   352 .. method:: IMAP4.search(charset, criterion[, ...])

   353 

   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.

   358 

   359    Example::

   360 

   361       # M is a connected IMAP4 instance...

   362       typ, msgnums = M.search(None, 'FROM', '"LDJ"')

   363 

   364       # or:

   365       typ, msgnums = M.search(None, '(FROM "LDJ")')

   366 

   367 

   368 .. method:: IMAP4.select([mailbox[, readonly]])

   369 

   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.

   373 

   374 

   375 .. method:: IMAP4.send(data)

   376 

   377    Sends ``data`` to the remote server. You may override this method.

   378 

   379 

   380 .. method:: IMAP4.setacl(mailbox, who, what)

   381 

   382    Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by

   383    the ``Cyrus`` server.

   384 

   385 

   386 .. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])

   387 

   388    Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is

   389    supported by the ``Cyrus`` server.

   390 

   391    .. versionadded:: 2.5

   392 

   393 

   394 .. method:: IMAP4.setquota(root, limits)

   395 

   396    Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4

   397    QUOTA extension defined in rfc2087.

   398 

   399    .. versionadded:: 2.3

   400 

   401 

   402 .. method:: IMAP4.shutdown()

   403 

   404    Close connection established in ``open``. You may override this method.

   405 

   406 

   407 .. method:: IMAP4.socket()

   408 

   409    Returns socket instance used to connect to server.

   410 

   411 

   412 .. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

   413 

   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

   416    numbers.

   417 

   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.

   426 

   427    This is an ``IMAP4rev1`` extension command.

   428 

   429 

   430 .. method:: IMAP4.status(mailbox, names)

   431 

   432    Request named status conditions for *mailbox*.

   433 

   434 

   435 .. method:: IMAP4.store(message_set, command, flag_list)

   436 

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

   440 

   441    For example, to set the delete flag on all messages::

   442 

   443       typ, data = M.search(None, 'ALL')

   444       for num in data[0].split():

   445          M.store(num, '+FLAGS', '\\Deleted')

   446       M.expunge()

   447 

   448 

   449 .. method:: IMAP4.subscribe(mailbox)

   450 

   451    Subscribe to new mailbox.

   452 

   453 

   454 .. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

   455 

   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.

   458 

   459    Thread members consist of zero or more messages numbers, delimited by spaces,

   460    indicating successive parent and child.

   461 

   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

   470    algorithm.

   471 

   472    This is an ``IMAP4rev1`` extension command.

   473 

   474    .. versionadded:: 2.4

   475 

   476 

   477 .. method:: IMAP4.uid(command, arg[, ...])

   478 

   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

   482    will be raised.

   483 

   484 

   485 .. method:: IMAP4.unsubscribe(mailbox)

   486 

   487    Unsubscribe from old mailbox.

   488 

   489 

   490 .. method:: IMAP4.xatom(name[, arg[, ...]])

   491 

   492    Allow simple extension commands notified by server in ``CAPABILITY`` response.

   493 

   494 Instances of :class:`IMAP4_SSL` have just one additional method:

   495 

   496 

   497 .. method:: IMAP4_SSL.ssl()

   498 

   499    Returns SSLObject instance used for the secure connection with the server.

   500 

   501 The following attributes are defined on instances of :class:`IMAP4`:

   502 

   503 

   504 .. attribute:: IMAP4.PROTOCOL_VERSION

   505 

   506    The most recent supported protocol in the ``CAPABILITY`` response from the

   507    server.

   508 

   509 

   510 .. attribute:: IMAP4.debug

   511 

   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.

   514 

   515 

   516 .. _imap4-example:

   517 

   518 IMAP4 Example

   519 -------------

   520 

   521 Here is a minimal example (without error checking) that opens a mailbox and

   522 retrieves and prints all messages::

   523 

   524    import getpass, imaplib

   525 

   526    M = imaplib.IMAP4()

   527    M.login(getpass.getuser(), getpass.getpass())

   528    M.select()

   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])

   533    M.close()

   534    M.logout()

   535