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