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 string 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, and sources and binaries for servers 167 implementing it, can all be found at the University of Washington's *IMAP 168 Information Center* (https://www.washington.edu/imap/). 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 string, 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 331.. method:: IMAP4.lsub(directory='""', pattern='*') 332 333 List subscribed mailbox names in directory matching pattern. *directory* 334 defaults to the top level directory and *pattern* defaults to match any mailbox. 335 Returned data are tuples of message part envelope and data. 336 337 338.. method:: IMAP4.myrights(mailbox) 339 340 Show my ACLs for a mailbox (i.e. the rights that I have on mailbox). 341 342 343.. method:: IMAP4.namespace() 344 345 Returns IMAP namespaces as defined in :rfc:`2342`. 346 347 348.. method:: IMAP4.noop() 349 350 Send ``NOOP`` to server. 351 352 353.. method:: IMAP4.open(host, port) 354 355 Opens socket to *port* at *host*. This method is implicitly called by 356 the :class:`IMAP4` constructor. The connection objects established by this 357 method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`, 358 :meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override 359 this method. 360 361 362.. method:: IMAP4.partial(message_num, message_part, start, length) 363 364 Fetch truncated part of a message. Returned data is a tuple of message part 365 envelope and data. 366 367 368.. method:: IMAP4.proxyauth(user) 369 370 Assume authentication as *user*. Allows an authorised administrator to proxy 371 into any user's mailbox. 372 373 374.. method:: IMAP4.read(size) 375 376 Reads *size* bytes from the remote server. You may override this method. 377 378 379.. method:: IMAP4.readline() 380 381 Reads one line from the remote server. You may override this method. 382 383 384.. method:: IMAP4.recent() 385 386 Prompt server for an update. Returned data is ``None`` if no new messages, else 387 value of ``RECENT`` response. 388 389 390.. method:: IMAP4.rename(oldmailbox, newmailbox) 391 392 Rename mailbox named *oldmailbox* to *newmailbox*. 393 394 395.. method:: IMAP4.response(code) 396 397 Return data for response *code* if received, or ``None``. Returns the given 398 code, instead of the usual type. 399 400 401.. method:: IMAP4.search(charset, criterion[, ...]) 402 403 Search mailbox for matching messages. *charset* may be ``None``, in which case 404 no ``CHARSET`` will be specified in the request to the server. The IMAP 405 protocol requires that at least one criterion be specified; an exception will be 406 raised when the server returns an error. *charset* must be ``None`` if 407 the ``UTF8=ACCEPT`` capability was enabled using the :meth:`enable` 408 command. 409 410 Example:: 411 412 # M is a connected IMAP4 instance... 413 typ, msgnums = M.search(None, 'FROM', '"LDJ"') 414 415 # or: 416 typ, msgnums = M.search(None, '(FROM "LDJ")') 417 418 419.. method:: IMAP4.select(mailbox='INBOX', readonly=False) 420 421 Select a mailbox. Returned data is the count of messages in *mailbox* 422 (``EXISTS`` response). The default *mailbox* is ``'INBOX'``. If the *readonly* 423 flag is set, modifications to the mailbox are not allowed. 424 425 426.. method:: IMAP4.send(data) 427 428 Sends ``data`` to the remote server. You may override this method. 429 430 431.. method:: IMAP4.setacl(mailbox, who, what) 432 433 Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by 434 the ``Cyrus`` server. 435 436 437.. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...]) 438 439 Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is 440 supported by the ``Cyrus`` server. 441 442 443.. method:: IMAP4.setquota(root, limits) 444 445 Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4 446 QUOTA extension defined in rfc2087. 447 448 449.. method:: IMAP4.shutdown() 450 451 Close connection established in ``open``. This method is implicitly 452 called by :meth:`IMAP4.logout`. You may override this method. 453 454 455.. method:: IMAP4.socket() 456 457 Returns socket instance used to connect to server. 458 459 460.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...]) 461 462 The ``sort`` command is a variant of ``search`` with sorting semantics for the 463 results. Returned data contains a space separated list of matching message 464 numbers. 465 466 Sort has two arguments before the *search_criterion* argument(s); a 467 parenthesized list of *sort_criteria*, and the searching *charset*. Note that 468 unlike ``search``, the searching *charset* argument is mandatory. There is also 469 a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search`` 470 corresponds to ``search``. The ``sort`` command first searches the mailbox for 471 messages that match the given searching criteria using the charset argument for 472 the interpretation of strings in the searching criteria. It then returns the 473 numbers of matching messages. 474 475 This is an ``IMAP4rev1`` extension command. 476 477 478.. method:: IMAP4.starttls(ssl_context=None) 479 480 Send a ``STARTTLS`` command. The *ssl_context* argument is optional 481 and should be a :class:`ssl.SSLContext` object. This will enable 482 encryption on the IMAP connection. Please read :ref:`ssl-security` for 483 best practices. 484 485 .. versionadded:: 3.2 486 487 .. versionchanged:: 3.4 488 The method now supports hostname check with 489 :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see 490 :data:`ssl.HAS_SNI`). 491 492 493.. method:: IMAP4.status(mailbox, names) 494 495 Request named status conditions for *mailbox*. 496 497 498.. method:: IMAP4.store(message_set, command, flag_list) 499 500 Alters flag dispositions for messages in mailbox. *command* is specified by 501 section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS", 502 optionally with a suffix of ".SILENT". 503 504 For example, to set the delete flag on all messages:: 505 506 typ, data = M.search(None, 'ALL') 507 for num in data[0].split(): 508 M.store(num, '+FLAGS', '\\Deleted') 509 M.expunge() 510 511 .. note:: 512 513 Creating flags containing ']' (for example: "[test]") violates 514 :rfc:`3501` (the IMAP protocol). However, imaplib has historically 515 allowed creation of such tags, and popular IMAP servers, such as Gmail, 516 accept and produce such flags. There are non-Python programs which also 517 create such tags. Although it is an RFC violation and IMAP clients and 518 servers are supposed to be strict, imaplib nonetheless continues to allow 519 such tags to be created for backward compatibility reasons, and as of 520 Python 3.6, handles them if they are sent from the server, since this 521 improves real-world compatibility. 522 523.. method:: IMAP4.subscribe(mailbox) 524 525 Subscribe to new mailbox. 526 527 528.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...]) 529 530 The ``thread`` command is a variant of ``search`` with threading semantics for 531 the results. Returned data contains a space separated list of thread members. 532 533 Thread members consist of zero or more messages numbers, delimited by spaces, 534 indicating successive parent and child. 535 536 Thread has two arguments before the *search_criterion* argument(s); a 537 *threading_algorithm*, and the searching *charset*. Note that unlike 538 ``search``, the searching *charset* argument is mandatory. There is also a 539 ``uid thread`` command which corresponds to ``thread`` the way that ``uid 540 search`` corresponds to ``search``. The ``thread`` command first searches the 541 mailbox for messages that match the given searching criteria using the charset 542 argument for the interpretation of strings in the searching criteria. It then 543 returns the matching messages threaded according to the specified threading 544 algorithm. 545 546 This is an ``IMAP4rev1`` extension command. 547 548 549.. method:: IMAP4.uid(command, arg[, ...]) 550 551 Execute command args with messages identified by UID, rather than message 552 number. Returns response appropriate to command. At least one argument must be 553 supplied; if none are provided, the server will return an error and an exception 554 will be raised. 555 556 557.. method:: IMAP4.unsubscribe(mailbox) 558 559 Unsubscribe from old mailbox. 560 561 562.. method:: IMAP4.xatom(name[, ...]) 563 564 Allow simple extension commands notified by server in ``CAPABILITY`` response. 565 566 567The following attributes are defined on instances of :class:`IMAP4`: 568 569.. attribute:: IMAP4.PROTOCOL_VERSION 570 571 The most recent supported protocol in the ``CAPABILITY`` response from the 572 server. 573 574 575.. attribute:: IMAP4.debug 576 577 Integer value to control debugging output. The initialize value is taken from 578 the module variable ``Debug``. Values greater than three trace each command. 579 580 581.. attribute:: IMAP4.utf8_enabled 582 583 Boolean value that is normally ``False``, but is set to ``True`` if an 584 :meth:`enable` command is successfully issued for the ``UTF8=ACCEPT`` 585 capability. 586 587 .. versionadded:: 3.5 588 589 590.. _imap4-example: 591 592IMAP4 Example 593------------- 594 595Here is a minimal example (without error checking) that opens a mailbox and 596retrieves and prints all messages:: 597 598 import getpass, imaplib 599 600 M = imaplib.IMAP4() 601 M.login(getpass.getuser(), getpass.getpass()) 602 M.select() 603 typ, data = M.search(None, 'ALL') 604 for num in data[0].split(): 605 typ, data = M.fetch(num, '(RFC822)') 606 print('Message %s\n%s\n' % (num, data[0][1])) 607 M.close() 608 M.logout() 609 610