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