<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-nntplib.html" />
<link rel=
"prev" href=
"module-poplib.html" />
<link rel=
"parent" href=
"internet.html" />
<link rel=
"next" href=
"imap4-objects.html" />
<meta name='aesop' content='information'
/>
<title>11.10 imaplib -- IMAP4 protocol client
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"11.9.2 POP3 Example"
href=
"pop3-example.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"11. Internet Protocols and"
href=
"internet.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"11.10.1 IMAP4 Objects"
href=
"imap4-objects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"pop3-example.html">11.9.2 POP3 Example
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"internet.html">11. Internet Protocols and
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"imap4-objects.html">11.10.1 IMAP4 Objects
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION00131000000000000000000">
11.10 <tt class=
"module">imaplib
</tt> --
IMAP4 protocol client
</A>
<A NAME=
"module-imaplib"></A>
<a id='l2h-
3392' xml:id='l2h-
3392'
></a><a id='l2h-
3393' xml:id='l2h-
3393'
></a><a id='l2h-
3394' xml:id='l2h-
3394'
></a>
This module defines three classes,
<tt class=
"class">IMAP4
</tt>,
<tt class=
"class">IMAP4_SSL
</tt>
and
<tt class=
"class">IMAP4_stream
</tt>, which encapsulate a
connection to an IMAP4 server and implement a large subset of the
IMAP4rev1 client protocol as defined in
<a class=
"rfc" id='rfcref-
90207' xml:id='rfcref-
90207'
href=
"http://www.faqs.org/rfcs/rfc2060.html">RFC
2060</a>. It is backward
compatible with IMAP4 (
<a class=
"rfc" id='rfcref-
90209' xml:id='rfcref-
90209'
href=
"http://www.faqs.org/rfcs/rfc1730.html">RFC
1730</a>) servers, but note that the
"<tt class="samp
">STATUS</tt>" command is not supported in IMAP4.
Three classes are provided by the
<tt class=
"module">imaplib
</tt> module,
<tt class=
"class">IMAP4
</tt> is the base class:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3395' xml:id='l2h-
3395'
class=
"class">IMAP4
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>host
</var><big>[
</big><var>, port
</var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
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
<var>host
</var> is not specified,
<code>''
</code> (the local host) is used.
If
<var>port
</var> is omitted, the standard IMAP4 port (
143) is used.
Three exceptions are defined as attributes of the
<tt class=
"class">IMAP4
</tt> class:
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
3396' xml:id='l2h-
3396'
class=
"exception">IMAP4.error
</tt></b></dt>
Exception raised on any errors. The reason for the exception is
passed to the constructor as a string.
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
3397' xml:id='l2h-
3397'
class=
"exception">IMAP4.abort
</tt></b></dt>
IMAP4 server errors cause this exception to be raised. This is a
sub-class of
<tt class=
"exception">IMAP4.error
</tt>. Note that closing the instance
and instantiating a new one will usually allow recovery from this
<dl><dt><b><span class=
"typelabel">exception
</span> <tt id='l2h-
3398' xml:id='l2h-
3398'
class=
"exception">IMAP4.readonly
</tt></b></dt>
This exception is raised when a writable mailbox has its status
changed by the server. This is a sub-class of
<tt class=
"exception">IMAP4.error
</tt>. Some other client now has write permission,
and the mailbox will need to be re-opened to re-obtain write
There's also a subclass for secure connections:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3399' xml:id='l2h-
3399'
class=
"class">IMAP4_SSL
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>host
</var><big>[
</big><var>, port
</var><big>[
</big><var>,
keyfile
</var><big>[
</big><var>, certfile
</var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var><big>]
</big><var></var>)
</td></tr></table></dt>
This is a subclass derived from
<tt class=
"class">IMAP4
</tt> that connects over an
SSL encrypted socket (to use this class you need a socket module that
was compiled with SSL support). If
<var>host
</var> is not specified,
<code>''
</code> (the local host) is used. If
<var>port
</var> is omitted, the
standard IMAP4-over-SSL port (
993) is used.
<var>keyfile
</var> and
<var>certfile
</var> are also optional - they can contain a PEM formatted
private key and certificate chain file for the SSL connection.
The second subclass allows for connections created by a child process:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
3400' xml:id='l2h-
3400'
class=
"class">IMAP4_stream
</tt></b>(
</nobr></td>
<td><var>command
</var>)
</td></tr></table></dt>
This is a subclass derived from
<tt class=
"class">IMAP4
</tt> that connects
to the
<code>stdin/stdout
</code> file descriptors created by passing
<var>command
</var> to
<code>os.popen2()
</code>.
<span class=
"versionnote">New in version
2.3.
</span>
The following utility functions are defined:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3401' xml:id='l2h-
3401'
class=
"function">Internaldate2tuple
</tt></b>(
</nobr></td>
<td><var>datestr
</var>)
</td></tr></table></dt>
Converts an IMAP4 INTERNALDATE string to Coordinated Universal
Time. Returns a
<tt class=
"module"><a href=
"module-time.html">time
</a></tt> module tuple.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3402' xml:id='l2h-
3402'
class=
"function">Int2AP
</tt></b>(
</nobr></td>
<td><var>num
</var>)
</td></tr></table></dt>
Converts an integer into a string representation using characters
from the set [
<code>A
</code> ..
<code>P
</code>].
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3403' xml:id='l2h-
3403'
class=
"function">ParseFlags
</tt></b>(
</nobr></td>
<td><var>flagstr
</var>)
</td></tr></table></dt>
Converts an IMAP4
"<tt class="samp
">FLAGS</tt>" response to a tuple of individual
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
3404' xml:id='l2h-
3404'
class=
"function">Time2Internaldate
</tt></b>(
</nobr></td>
<td><var>date_time
</var>)
</td></tr></table></dt>
Converts a
<tt class=
"module"><a href=
"module-time.html">time
</a></tt> module tuple to an IMAP4
"<tt class="samp
">INTERNALDATE</tt>" representation. Returns a string in the form:
<code>"DD-Mmm-YYYY HH:MM:SS +HHMM"</code> (including double-quotes).
Note that IMAP4 message numbers change as the mailbox changes; in
particular, after an
"<tt class="samp
">EXPUNGE</tt>" command performs deletions the
remaining messages are renumbered. So it is highly advisable to use
UIDs instead, with the UID command.
At the end of the module, there is a test section that contains a more
extensive example of usage.
<p class=
"heading">See Also:
</p>
<div class=
"seetext"><p>Documents describing the protocol, and sources and binaries
for servers implementing it, can all be found at the
University of Washington's
<em>IMAP Information Center
</em>
(
<a class=
"url" href=
"http://www.cac.washington.edu/imap/">http://www.cac.washington.edu/imap/
</a>).
</p></div>
<p><br /></p><hr class='online-navigation'
/>
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<LI><A href=
"imap4-objects.html">11.10.1 IMAP4 Objects
</a>
<LI><A href=
"imap4-example.html">11.10.2 IMAP4 Example
</a>
<!--End of Table of Child-Links-->
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"11.9.2 POP3 Example"
href=
"pop3-example.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"11. Internet Protocols and"
href=
"internet.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"11.10.1 IMAP4 Objects"
href=
"imap4-objects.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"pop3-example.html">11.9.2 POP3 Example
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"internet.html">11. Internet Protocols and
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"imap4-objects.html">11.10.1 IMAP4 Objects
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.