path: root/devdocs/python~3.12/library%2Fimaplib.html

 <span id="imaplib-imap4-protocol-client"></span><h1>imaplib — IMAP4 protocol client</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/imaplib.py">Lib/imaplib.py</a></p>  <p>This module defines three classes, <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a>, <a class="reference internal" href="#imaplib.IMAP4_SSL" title="imaplib.IMAP4_SSL"><code>IMAP4_SSL</code></a> and <a class="reference internal" href="#imaplib.IMAP4_stream" title="imaplib.IMAP4_stream"><code>IMAP4_stream</code></a>, which encapsulate a connection to an IMAP4 server and implement a large subset of the IMAP4rev1 client protocol as defined in <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2060.html"><strong>RFC 2060</strong></a>. It is backward compatible with IMAP4 (<span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1730.html"><strong>RFC 1730</strong></a>) servers, but note that the <code>STATUS</code> command is not supported in IMAP4.</p> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p> <p>This module does not work or is not available on WebAssembly platforms <code>wasm32-emscripten</code> and <code>wasm32-wasi</code>. See <a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p> </div> <p>Three classes are provided by the <a class="reference internal" href="#module-imaplib" title="imaplib: IMAP4 protocol client (requires sockets)."><code>imaplib</code></a> module, <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> is the base class:</p> <dl class="py class"> <dt class="sig sig-object py" id="imaplib.IMAP4">
<code>class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)</code> </dt> <dd>
<p>This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If <em>host</em> is not specified, <code>''</code> (the local host) is used. If <em>port</em> is omitted, the standard IMAP4 port (143) is used. The optional <em>timeout</em> parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used.</p> <p>The <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> class supports the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement. When used like this, the IMAP4 <code>LOGOUT</code> command is issued automatically when the <code>with</code> statement exits. E.g.:</p> <pre data-language="python">&gt;&gt;&gt; from imaplib import IMAP4
&gt;&gt;&gt; with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
</pre> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Support for the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>The optional <em>timeout</em> parameter was added.</p> </div> </dd>
</dl> <p>Three exceptions are defined as attributes of the <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> class:</p> <dl class="py exception"> <dt class="sig sig-object py" id="imaplib.IMAP4.error">
<code>exception IMAP4.error</code> </dt> <dd>
<p>Exception raised on any errors. The reason for the exception is passed to the constructor as a string.</p> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="imaplib.IMAP4.abort">
<code>exception IMAP4.abort</code> </dt> <dd>
<p>IMAP4 server errors cause this exception to be raised. This is a sub-class of <a class="reference internal" href="#imaplib.IMAP4.error" title="imaplib.IMAP4.error"><code>IMAP4.error</code></a>. Note that closing the instance and instantiating a new one will usually allow recovery from this exception.</p> </dd>
</dl> <dl class="py exception"> <dt class="sig sig-object py" id="imaplib.IMAP4.readonly">
<code>exception IMAP4.readonly</code> </dt> <dd>
<p>This exception is raised when a writable mailbox has its status changed by the server. This is a sub-class of <a class="reference internal" href="#imaplib.IMAP4.error" title="imaplib.IMAP4.error"><code>IMAP4.error</code></a>. Some other client now has write permission, and the mailbox will need to be re-opened to re-obtain write permission.</p> </dd>
</dl> <p>There’s also a subclass for secure connections:</p> <dl class="py class"> <dt class="sig sig-object py" id="imaplib.IMAP4_SSL">
<code>class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)</code> </dt> <dd>
<p>This is a subclass derived from <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> that connects over an SSL encrypted socket (to use this class you need a socket module that was compiled with SSL support). If <em>host</em> is not specified, <code>''</code> (the local host) is used. If <em>port</em> is omitted, the standard IMAP4-over-SSL port (993) is used. <em>ssl_context</em> is a <a class="reference internal" href="ssl#ssl.SSLContext" title="ssl.SSLContext"><code>ssl.SSLContext</code></a> object which allows bundling SSL configuration options, certificates and private keys into a single (potentially long-lived) structure. Please read <a class="reference internal" href="ssl#ssl-security"><span class="std std-ref">Security considerations</span></a> for best practices.</p> <p>The optional <em>timeout</em> parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>ssl_context</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>The class now supports hostname check with <a class="reference internal" href="ssl#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code>ssl.SSLContext.check_hostname</code></a> and <em>Server Name Indication</em> (see <a class="reference internal" href="ssl#ssl.HAS_SNI" title="ssl.HAS_SNI"><code>ssl.HAS_SNI</code></a>).</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>The optional <em>timeout</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>The deprecated <em>keyfile</em> and <em>certfile</em> parameters have been removed.</p> </div> </dd>
</dl> <p>The second subclass allows for connections created by a child process:</p> <dl class="py class"> <dt class="sig sig-object py" id="imaplib.IMAP4_stream">
<code>class imaplib.IMAP4_stream(command)</code> </dt> <dd>
<p>This is a subclass derived from <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> that connects to the <code>stdin/stdout</code> file descriptors created by passing <em>command</em> to <code>subprocess.Popen()</code>.</p> </dd>
</dl> <p>The following utility functions are defined:</p> <dl class="py function"> <dt class="sig sig-object py" id="imaplib.Internaldate2tuple">
<code>imaplib.Internaldate2tuple(datestr)</code> </dt> <dd>
<p>Parse an IMAP4 <code>INTERNALDATE</code> string and return corresponding local time. The return value is a <a class="reference internal" href="time#time.struct_time" title="time.struct_time"><code>time.struct_time</code></a> tuple or <code>None</code> if the string has wrong format.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="imaplib.Int2AP">
<code>imaplib.Int2AP(num)</code> </dt> <dd>
<p>Converts an integer into a bytes representation using characters from the set [<code>A</code> .. <code>P</code>].</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="imaplib.ParseFlags">
<code>imaplib.ParseFlags(flagstr)</code> </dt> <dd>
<p>Converts an IMAP4 <code>FLAGS</code> response to a tuple of individual flags.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="imaplib.Time2Internaldate">
<code>imaplib.Time2Internaldate(date_time)</code> </dt> <dd>
<p>Convert <em>date_time</em> to an IMAP4 <code>INTERNALDATE</code> representation. The return value is a string in the form: <code>"DD-Mmm-YYYY HH:MM:SS
+HHMM"</code> (including double-quotes). The <em>date_time</em> argument can be a number (int or float) representing seconds since epoch (as returned by <a class="reference internal" href="time#time.time" title="time.time"><code>time.time()</code></a>), a 9-tuple representing local time an instance of <a class="reference internal" href="time#time.struct_time" title="time.struct_time"><code>time.struct_time</code></a> (as returned by <a class="reference internal" href="time#time.localtime" title="time.localtime"><code>time.localtime()</code></a>), an aware instance of <a class="reference internal" href="datetime#datetime.datetime" title="datetime.datetime"><code>datetime.datetime</code></a>, or a double-quoted string. In the last case, it is assumed to already be in the correct format.</p> </dd>
</dl> <p>Note that IMAP4 message numbers change as the mailbox changes; in particular, after an <code>EXPUNGE</code> command performs deletions the remaining messages are renumbered. So it is highly advisable to use UIDs instead, with the UID command.</p> <p>At the end of the module, there is a test section that contains a more extensive example of usage.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>Documents describing the protocol, sources for servers implementing it, by the University of Washington’s IMAP Information Center can all be found at (<strong>Source Code</strong>) <a class="reference external" href="https://github.com/uw-imap/imap">https://github.com/uw-imap/imap</a> (<strong>Not Maintained</strong>).</p> </div> <section id="imap4-objects"> <span id="id1"></span><h2>IMAP4 Objects</h2> <p>All IMAP4rev1 commands are represented by methods of the same name, either uppercase or lowercase.</p> <p>All arguments to commands are converted to strings, except for <code>AUTHENTICATE</code>, and the last argument to <code>APPEND</code> which is passed as an IMAP4 literal. If necessary (the string contains IMAP4 protocol-sensitive characters and isn’t enclosed with either parentheses or double quotes) each string is quoted. However, the <em>password</em> argument to the <code>LOGIN</code> command is always quoted. If you want to avoid having an argument string quoted (eg: the <em>flags</em> argument to <code>STORE</code>) then enclose the string in parentheses (eg: <code>r'(\Deleted)'</code>).</p> <p>Each command returns a tuple: <code>(type, [data, ...])</code> where <em>type</em> is usually <code>'OK'</code> or <code>'NO'</code>, and <em>data</em> is either the text from the command response, or mandated results from the command. Each <em>data</em> is either a <code>bytes</code>, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (ie: ‘literal’ value).</p> <p>The <em>message_set</em> options to commands below is a string specifying one or more messages to be acted upon. It may be a simple message number (<code>'1'</code>), a range of message numbers (<code>'2:4'</code>), or a group of non-contiguous ranges separated by commas (<code>'1:3,6:9'</code>). A range can contain an asterisk to indicate an infinite upper bound (<code>'3:*'</code>).</p> <p>An <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> instance has the following methods:</p> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.append">
<code>IMAP4.append(mailbox, flags, date_time, message)</code> </dt> <dd>
<p>Append <em>message</em> to named mailbox.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.authenticate">
<code>IMAP4.authenticate(mechanism, authobject)</code> </dt> <dd>
<p>Authenticate command — requires response processing.</p> <p><em>mechanism</em> specifies which authentication mechanism is to be used - it should appear in the instance variable <code>capabilities</code> in the form <code>AUTH=mechanism</code>.</p> <p><em>authobject</em> must be a callable object:</p> <pre data-language="python">data = authobject(response)
</pre> <p>It will be called to process server continuation responses; the <em>response</em> argument it is passed will be <code>bytes</code>. It should return <code>bytes</code> <em>data</em> that will be base64 encoded and sent to the server. It should return <code>None</code> if the client abort response <code>*</code> should be sent instead.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>string usernames and passwords are now encoded to <code>utf-8</code> instead of being limited to ASCII.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.check">
<code>IMAP4.check()</code> </dt> <dd>
<p>Checkpoint mailbox on server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.close">
<code>IMAP4.close()</code> </dt> <dd>
<p>Close currently selected mailbox. Deleted messages are removed from writable mailbox. This is the recommended command before <code>LOGOUT</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.copy">
<code>IMAP4.copy(message_set, new_mailbox)</code> </dt> <dd>
<p>Copy <em>message_set</em> messages onto end of <em>new_mailbox</em>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.create">
<code>IMAP4.create(mailbox)</code> </dt> <dd>
<p>Create new mailbox named <em>mailbox</em>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.delete">
<code>IMAP4.delete(mailbox)</code> </dt> <dd>
<p>Delete old mailbox named <em>mailbox</em>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.deleteacl">
<code>IMAP4.deleteacl(mailbox, who)</code> </dt> <dd>
<p>Delete the ACLs (remove any rights) set for who on mailbox.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.enable">
<code>IMAP4.enable(capability)</code> </dt> <dd>
<p>Enable <em>capability</em> (see <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5161.html"><strong>RFC 5161</strong></a>). Most capabilities do not need to be enabled. Currently only the <code>UTF8=ACCEPT</code> capability is supported (see <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6855.html"><strong>RFC 6855</strong></a>).</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5: </span>The <a class="reference internal" href="#imaplib.IMAP4.enable" title="imaplib.IMAP4.enable"><code>enable()</code></a> method itself, and <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6855.html"><strong>RFC 6855</strong></a> support.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.expunge">
<code>IMAP4.expunge()</code> </dt> <dd>
<p>Permanently remove deleted items from selected mailbox. Generates an <code>EXPUNGE</code> response for each deleted message. Returned data contains a list of <code>EXPUNGE</code> message numbers in order received.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.fetch">
<code>IMAP4.fetch(message_set, message_parts)</code> </dt> <dd>
<p>Fetch (parts of) messages. <em>message_parts</em> should be a string of message part names enclosed within parentheses, eg: <code>"(UID BODY[TEXT])"</code>. Returned data are tuples of message part envelope and data.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.getacl">
<code>IMAP4.getacl(mailbox)</code> </dt> <dd>
<p>Get the <code>ACL</code>s for <em>mailbox</em>. The method is non-standard, but is supported by the <code>Cyrus</code> server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.getannotation">
<code>IMAP4.getannotation(mailbox, entry, attribute)</code> </dt> <dd>
<p>Retrieve the specified <code>ANNOTATION</code>s for <em>mailbox</em>. The method is non-standard, but is supported by the <code>Cyrus</code> server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.getquota">
<code>IMAP4.getquota(root)</code> </dt> <dd>
<p>Get the <code>quota</code> <em>root</em>’s resource usage and limits. This method is part of the IMAP4 QUOTA extension defined in rfc2087.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.getquotaroot">
<code>IMAP4.getquotaroot(mailbox)</code> </dt> <dd>
<p>Get the list of <code>quota</code> <code>roots</code> for the named <em>mailbox</em>. This method is part of the IMAP4 QUOTA extension defined in rfc2087.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.list">
<code>IMAP4.list([directory[, pattern]])</code> </dt> <dd>
<p>List mailbox names in <em>directory</em> matching <em>pattern</em>. <em>directory</em> defaults to the top-level mail folder, and <em>pattern</em> defaults to match anything. Returned data contains a list of <code>LIST</code> responses.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.login">
<code>IMAP4.login(user, password)</code> </dt> <dd>
<p>Identify the client using a plaintext password. The <em>password</em> will be quoted.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.login_cram_md5">
<code>IMAP4.login_cram_md5(user, password)</code> </dt> <dd>
<p>Force use of <code>CRAM-MD5</code> authentication when identifying the client to protect the password. Will only work if the server <code>CAPABILITY</code> response includes the phrase <code>AUTH=CRAM-MD5</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.logout">
<code>IMAP4.logout()</code> </dt> <dd>
<p>Shutdown connection to server. Returns server <code>BYE</code> response.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>The method no longer ignores silently arbitrary exceptions.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.lsub">
<code>IMAP4.lsub(directory='""', pattern='*')</code> </dt> <dd>
<p>List subscribed mailbox names in directory matching pattern. <em>directory</em> defaults to the top level directory and <em>pattern</em> defaults to match any mailbox. Returned data are tuples of message part envelope and data.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.myrights">
<code>IMAP4.myrights(mailbox)</code> </dt> <dd>
<p>Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.namespace">
<code>IMAP4.namespace()</code> </dt> <dd>
<p>Returns IMAP namespaces as defined in <span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2342.html"><strong>RFC 2342</strong></a>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.noop">
<code>IMAP4.noop()</code> </dt> <dd>
<p>Send <code>NOOP</code> to server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.open">
<code>IMAP4.open(host, port, timeout=None)</code> </dt> <dd>
<p>Opens socket to <em>port</em> at <em>host</em>. The optional <em>timeout</em> parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is None, the global default socket timeout is used. Also note that if the <em>timeout</em> parameter is set to be zero, it will raise a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> to reject creating a non-blocking socket. This method is implicitly called by the <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a> constructor. The connection objects established by this method will be used in the <a class="reference internal" href="#imaplib.IMAP4.read" title="imaplib.IMAP4.read"><code>IMAP4.read()</code></a>, <a class="reference internal" href="#imaplib.IMAP4.readline" title="imaplib.IMAP4.readline"><code>IMAP4.readline()</code></a>, <a class="reference internal" href="#imaplib.IMAP4.send" title="imaplib.IMAP4.send"><code>IMAP4.send()</code></a>, and <a class="reference internal" href="#imaplib.IMAP4.shutdown" title="imaplib.IMAP4.shutdown"><code>IMAP4.shutdown()</code></a> methods. You may override this method.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>imaplib.open</code> with arguments <code>self</code>, <code>host</code>, <code>port</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>The <em>timeout</em> parameter was added.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.partial">
<code>IMAP4.partial(message_num, message_part, start, length)</code> </dt> <dd>
<p>Fetch truncated part of a message. Returned data is a tuple of message part envelope and data.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.proxyauth">
<code>IMAP4.proxyauth(user)</code> </dt> <dd>
<p>Assume authentication as <em>user</em>. Allows an authorised administrator to proxy into any user’s mailbox.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.read">
<code>IMAP4.read(size)</code> </dt> <dd>
<p>Reads <em>size</em> bytes from the remote server. You may override this method.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.readline">
<code>IMAP4.readline()</code> </dt> <dd>
<p>Reads one line from the remote server. You may override this method.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.recent">
<code>IMAP4.recent()</code> </dt> <dd>
<p>Prompt server for an update. Returned data is <code>None</code> if no new messages, else value of <code>RECENT</code> response.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.rename">
<code>IMAP4.rename(oldmailbox, newmailbox)</code> </dt> <dd>
<p>Rename mailbox named <em>oldmailbox</em> to <em>newmailbox</em>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.response">
<code>IMAP4.response(code)</code> </dt> <dd>
<p>Return data for response <em>code</em> if received, or <code>None</code>. Returns the given code, instead of the usual type.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.search">
<code>IMAP4.search(charset, criterion[, ...])</code> </dt> <dd>
<p>Search mailbox for matching messages. <em>charset</em> may be <code>None</code>, in which case no <code>CHARSET</code> will be specified in the request to the server. The IMAP protocol requires that at least one criterion be specified; an exception will be raised when the server returns an error. <em>charset</em> must be <code>None</code> if the <code>UTF8=ACCEPT</code> capability was enabled using the <a class="reference internal" href="#imaplib.IMAP4.enable" title="imaplib.IMAP4.enable"><code>enable()</code></a> command.</p> <p>Example:</p> <pre data-language="python"># M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')
</pre> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.select">
<code>IMAP4.select(mailbox='INBOX', readonly=False)</code> </dt> <dd>
<p>Select a mailbox. Returned data is the count of messages in <em>mailbox</em> (<code>EXISTS</code> response). The default <em>mailbox</em> is <code>'INBOX'</code>. If the <em>readonly</em> flag is set, modifications to the mailbox are not allowed.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.send">
<code>IMAP4.send(data)</code> </dt> <dd>
<p>Sends <code>data</code> to the remote server. You may override this method.</p> <p class="audit-hook">Raises an <a class="reference internal" href="sys#auditing"><span class="std std-ref">auditing event</span></a> <code>imaplib.send</code> with arguments <code>self</code>, <code>data</code>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.setacl">
<code>IMAP4.setacl(mailbox, who, what)</code> </dt> <dd>
<p>Set an <code>ACL</code> for <em>mailbox</em>. The method is non-standard, but is supported by the <code>Cyrus</code> server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.setannotation">
<code>IMAP4.setannotation(mailbox, entry, attribute[, ...])</code> </dt> <dd>
<p>Set <code>ANNOTATION</code>s for <em>mailbox</em>. The method is non-standard, but is supported by the <code>Cyrus</code> server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.setquota">
<code>IMAP4.setquota(root, limits)</code> </dt> <dd>
<p>Set the <code>quota</code> <em>root</em>’s resource <em>limits</em>. This method is part of the IMAP4 QUOTA extension defined in rfc2087.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.shutdown">
<code>IMAP4.shutdown()</code> </dt> <dd>
<p>Close connection established in <code>open</code>. This method is implicitly called by <a class="reference internal" href="#imaplib.IMAP4.logout" title="imaplib.IMAP4.logout"><code>IMAP4.logout()</code></a>. You may override this method.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.socket">
<code>IMAP4.socket()</code> </dt> <dd>
<p>Returns socket instance used to connect to server.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.sort">
<code>IMAP4.sort(sort_criteria, charset, search_criterion[, ...])</code> </dt> <dd>
<p>The <code>sort</code> command is a variant of <code>search</code> with sorting semantics for the results. Returned data contains a space separated list of matching message numbers.</p> <p>Sort has two arguments before the <em>search_criterion</em> argument(s); a parenthesized list of <em>sort_criteria</em>, and the searching <em>charset</em>. Note that unlike <code>search</code>, the searching <em>charset</em> argument is mandatory. There is also a <code>uid sort</code> command which corresponds to <code>sort</code> the way that <code>uid search</code> corresponds to <code>search</code>. The <code>sort</code> command first searches the mailbox for messages that match the given searching criteria using the charset argument for the interpretation of strings in the searching criteria. It then returns the numbers of matching messages.</p> <p>This is an <code>IMAP4rev1</code> extension command.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.starttls">
<code>IMAP4.starttls(ssl_context=None)</code> </dt> <dd>
<p>Send a <code>STARTTLS</code> command. The <em>ssl_context</em> argument is optional and should be a <a class="reference internal" href="ssl#ssl.SSLContext" title="ssl.SSLContext"><code>ssl.SSLContext</code></a> object. This will enable encryption on the IMAP connection. Please read <a class="reference internal" href="ssl#ssl-security"><span class="std std-ref">Security considerations</span></a> for best practices.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>The method now supports hostname check with <a class="reference internal" href="ssl#ssl.SSLContext.check_hostname" title="ssl.SSLContext.check_hostname"><code>ssl.SSLContext.check_hostname</code></a> and <em>Server Name Indication</em> (see <a class="reference internal" href="ssl#ssl.HAS_SNI" title="ssl.HAS_SNI"><code>ssl.HAS_SNI</code></a>).</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.status">
<code>IMAP4.status(mailbox, names)</code> </dt> <dd>
<p>Request named status conditions for <em>mailbox</em>.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.store">
<code>IMAP4.store(message_set, command, flag_list)</code> </dt> <dd>
<p>Alters flag dispositions for messages in mailbox. <em>command</em> is specified by section 6.4.6 of <span class="target" id="index-7"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2060.html"><strong>RFC 2060</strong></a> as being one of “FLAGS”, “+FLAGS”, or “-FLAGS”, optionally with a suffix of “.SILENT”.</p> <p>For example, to set the delete flag on all messages:</p> <pre data-language="python">typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()
</pre> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Creating flags containing ‘]’ (for example: “[test]”) violates <span class="target" id="index-8"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc3501.html"><strong>RFC 3501</strong></a> (the IMAP protocol). However, imaplib has historically allowed creation of such tags, and popular IMAP servers, such as Gmail, accept and produce such flags. There are non-Python programs which also create such tags. Although it is an RFC violation and IMAP clients and servers are supposed to be strict, imaplib nonetheless continues to allow such tags to be created for backward compatibility reasons, and as of Python 3.6, handles them if they are sent from the server, since this improves real-world compatibility.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.subscribe">
<code>IMAP4.subscribe(mailbox)</code> </dt> <dd>
<p>Subscribe to new mailbox.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.thread">
<code>IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])</code> </dt> <dd>
<p>The <code>thread</code> command is a variant of <code>search</code> with threading semantics for the results. Returned data contains a space separated list of thread members.</p> <p>Thread members consist of zero or more messages numbers, delimited by spaces, indicating successive parent and child.</p> <p>Thread has two arguments before the <em>search_criterion</em> argument(s); a <em>threading_algorithm</em>, and the searching <em>charset</em>. Note that unlike <code>search</code>, the searching <em>charset</em> argument is mandatory. There is also a <code>uid thread</code> command which corresponds to <code>thread</code> the way that <code>uid
search</code> corresponds to <code>search</code>. The <code>thread</code> command first searches the mailbox for messages that match the given searching criteria using the <em>charset</em> argument for the interpretation of strings in the searching criteria. It then returns the matching messages threaded according to the specified threading algorithm.</p> <p>This is an <code>IMAP4rev1</code> extension command.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.uid">
<code>IMAP4.uid(command, arg[, ...])</code> </dt> <dd>
<p>Execute command args with messages identified by UID, rather than message number. Returns response appropriate to command. At least one argument must be supplied; if none are provided, the server will return an error and an exception will be raised.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.unsubscribe">
<code>IMAP4.unsubscribe(mailbox)</code> </dt> <dd>
<p>Unsubscribe from old mailbox.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.unselect">
<code>IMAP4.unselect()</code> </dt> <dd>
<p><a class="reference internal" href="#imaplib.IMAP4.unselect" title="imaplib.IMAP4.unselect"><code>imaplib.IMAP4.unselect()</code></a> frees server’s resources associated with the selected mailbox and returns the server to the authenticated state. This command performs the same actions as <a class="reference internal" href="#imaplib.IMAP4.close" title="imaplib.IMAP4.close"><code>imaplib.IMAP4.close()</code></a>, except that no messages are permanently removed from the currently selected mailbox.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.9.</span></p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="imaplib.IMAP4.xatom">
<code>IMAP4.xatom(name[, ...])</code> </dt> <dd>
<p>Allow simple extension commands notified by server in <code>CAPABILITY</code> response.</p> </dd>
</dl> <p>The following attributes are defined on instances of <a class="reference internal" href="#imaplib.IMAP4" title="imaplib.IMAP4"><code>IMAP4</code></a>:</p> <dl class="py attribute"> <dt class="sig sig-object py" id="imaplib.IMAP4.PROTOCOL_VERSION">
<code>IMAP4.PROTOCOL_VERSION</code> </dt> <dd>
<p>The most recent supported protocol in the <code>CAPABILITY</code> response from the server.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="imaplib.IMAP4.debug">
<code>IMAP4.debug</code> </dt> <dd>
<p>Integer value to control debugging output. The initialize value is taken from the module variable <code>Debug</code>. Values greater than three trace each command.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="imaplib.IMAP4.utf8_enabled">
<code>IMAP4.utf8_enabled</code> </dt> <dd>
<p>Boolean value that is normally <code>False</code>, but is set to <code>True</code> if an <a class="reference internal" href="#imaplib.IMAP4.enable" title="imaplib.IMAP4.enable"><code>enable()</code></a> command is successfully issued for the <code>UTF8=ACCEPT</code> capability.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> </dd>
</dl> </section> <section id="imap4-example"> <span id="id2"></span><h2>IMAP4 Example</h2> <p>Here is a minimal example (without error checking) that opens a mailbox and retrieves and prints all messages:</p> <pre data-language="python">import getpass, imaplib

M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()
</pre> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/imaplib.html" class="_attribution-link">https://docs.python.org/3.12/library/imaplib.html</a>
  </p>
</div>