<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>11.7.1 IMAP4 Objects</TITLE>
<META NAME="description" CONTENT="11.7.1 IMAP4 Objects">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="lib.css">
<LINK REL="next" HREF="imap4-example.html">
<LINK REL="previous" HREF="module-imaplib.html">
<LINK REL="up" HREF="module-imaplib.html">
<LINK REL="next" HREF="imap4-example.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="imap4-example.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-imaplib.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="module-imaplib.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="imap4-example.html">11.7.2 IMAP4 Example</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-imaplib.html">11.7 imaplib  </A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="module-imaplib.html">11.7 imaplib  </A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0013710000000000000000"></A>
<BR>
11.7.1 IMAP4 Objects
</H2>

<P>
All IMAP4rev1 commands are represented by methods of the same name,
either upper-case or lower-case.

<P>
Each command returns a tuple: <tt>(<var>type</var>, [<var>data</var>,
...])</tt> where <var>type</var> is usually <tt>'OK'</tt> or <tt>'NO'</tt>,
and <var>data</var> is either the text from the command response, or
mandated results from the command.

<P>
An <tt class=class>IMAP4</tt> instance has the following methods:

<P>
<dl><dt><b><a name="l2h-1704"><tt class=method>append</tt></a></b> (<var>mailbox, flags, date_time, message</var>)
<dd>
  Append message to named mailbox. 
</dl>

<P>
<dl><dt><b><a name="l2h-1705"><tt class=method>authenticate</tt></a></b> (<var>func</var>)
<dd>
  Authenticate command -- requires response processing. This is
  currently unimplemented, and raises an exception. 
</dl>

<P>
<dl><dt><b><a name="l2h-1706"><tt class=method>check</tt></a></b> ()
<dd>
  Checkpoint mailbox on server. 
</dl>

<P>
<dl><dt><b><a name="l2h-1707"><tt class=method>close</tt></a></b> ()
<dd>
  Close currently selected mailbox. Deleted messages are removed from
  writable mailbox. This is the recommended command before
  "<tt class=samp>LOGOUT</tt>".
</dl>

<P>
<dl><dt><b><a name="l2h-1708"><tt class=method>copy</tt></a></b> (<var>message_set, new_mailbox</var>)
<dd>
  Copy <var>message_set</var> messages onto end of <var>new_mailbox</var>. 
</dl>

<P>
<dl><dt><b><a name="l2h-1709"><tt class=method>create</tt></a></b> (<var>mailbox</var>)
<dd>
  Create new mailbox named <var>mailbox</var>.
</dl>

<P>
<dl><dt><b><a name="l2h-1710"><tt class=method>delete</tt></a></b> (<var>mailbox</var>)
<dd>
  Delete old mailbox named <var>mailbox</var>.
</dl>

<P>
<dl><dt><b><a name="l2h-1711"><tt class=method>expunge</tt></a></b> ()
<dd>
  Permanently remove deleted items from selected mailbox. Generates an
  "<tt class=samp>EXPUNGE</tt>" response for each deleted message. Returned data
  contains a list of "<tt class=samp>EXPUNGE</tt>" message numbers in order
  received.
</dl>

<P>
<dl><dt><b><a name="l2h-1712"><tt class=method>fetch</tt></a></b> (<var>message_set, message_parts</var>)
<dd>
  Fetch (parts of) messages. Returned data are tuples of message part
  envelope and data.
</dl>

<P>
<dl><dt><b><a name="l2h-1713"><tt class=method>list</tt></a></b> (<big>[</big><var>directory</var><big>[</big><var>, pattern</var><big>]</big><big>]</big>)
<dd>
  List mailbox names in <var>directory</var> matching
  <var>pattern</var>.  <var>directory</var> defaults to the top-level mail
  folder, and <var>pattern</var> defaults to match anything.  Returned data
  contains a list of "<tt class=samp>LIST</tt>" responses.
</dl>

<P>
<dl><dt><b><a name="l2h-1714"><tt class=method>login</tt></a></b> (<var>user, password</var>)
<dd>
  Identify the client using a plaintext password.
</dl>

<P>
<dl><dt><b><a name="l2h-1715"><tt class=method>logout</tt></a></b> ()
<dd>
  Shutdown connection to server. Returns server "<tt class=samp>BYE</tt>" response.
</dl>

<P>
<dl><dt><b><a name="l2h-1716"><tt class=method>lsub</tt></a></b> (<big>[</big><var>directory</var><big>[</big><var>, pattern</var><big>]</big><big>]</big>)
<dd>
  List subscribed mailbox names in directory matching pattern.
  <var>directory</var> defaults to the top level directory and
  <var>pattern</var> defaults to match any mailbox.
  Returned data are tuples of message part envelope and data.
</dl>

<P>
<dl><dt><b><a name="l2h-1717"><tt class=method>recent</tt></a></b> ()
<dd>
  Prompt server for an update. Returned data is <tt>None</tt> if no new
  messages, else value of "<tt class=samp>RECENT</tt>" response.
</dl>

<P>
<dl><dt><b><a name="l2h-1718"><tt class=method>rename</tt></a></b> (<var>oldmailbox, newmailbox</var>)
<dd>
  Rename mailbox named <var>oldmailbox</var> to <var>newmailbox</var>.
</dl>

<P>
<dl><dt><b><a name="l2h-1719"><tt class=method>response</tt></a></b> (<var>code</var>)
<dd>
  Return data for response <var>code</var> if received, or
  <tt>None</tt>. Returns the given code, instead of the usual type.
</dl>

<P>
<dl><dt><b><a name="l2h-1720"><tt class=method>search</tt></a></b> (<var>charset, criteria</var>)
<dd>
  Search mailbox for matching messages. Returned data contains a space
  separated list of matching message numbers.
</dl>

<P>
<dl><dt><b><a name="l2h-1721"><tt class=method>select</tt></a></b> (<big>[</big><var>mailbox</var><big>[</big><var>, readonly</var><big>]</big><big>]</big>)
<dd>
  Select a mailbox. Returned data is the count of messages in
  <var>mailbox</var> ("<tt class=samp>EXISTS</tt>" response).  The default <var>mailbox</var>
  is <tt>'INBOX'</tt>.  If the <var>readonly</var> flag is set, modifications
  to the mailbox are not allowed.
</dl>

<P>
<dl><dt><b><a name="l2h-1722"><tt class=method>status</tt></a></b> (<var>mailbox, names</var>)
<dd>
  Request named status conditions for <var>mailbox</var>. 
</dl>

<P>
<dl><dt><b><a name="l2h-1723"><tt class=method>store</tt></a></b> (<var>message_set, command, flag_list</var>)
<dd>
  Alters flag dispositions for messages in mailbox.
</dl>

<P>
<dl><dt><b><a name="l2h-1724"><tt class=method>subscribe</tt></a></b> (<var>mailbox</var>)
<dd>
  Subscribe to new mailbox.
</dl>

<P>
<dl><dt><b><a name="l2h-1725"><tt class=method>uid</tt></a></b> (<var>command, args</var>)
<dd>
  Execute command args with messages identified by UID, rather than
  message number. Returns response appropriate to command.
</dl>

<P>
<dl><dt><b><a name="l2h-1726"><tt class=method>unsubscribe</tt></a></b> (<var>mailbox</var>)
<dd>
  Unsubscribe from old mailbox.
</dl>

<P>
<dl><dt><b><a name="l2h-1727"><tt class=method>xatom</tt></a></b> (<var>name</var><big>[</big><var>, arg1</var><big>[</big><var>, arg2</var><big>]</big><big>]</big>)
<dd>
  Allow simple extension commands notified by server in
  "<tt class=samp>CAPABILITY</tt>" response.
</dl>

<P>
The following attributes are defined on instances of <tt class=class>IMAP4</tt>:

<P>
<dl><dt><b><a name="l2h-1728"><tt class=member>PROTOCOL_VERSION</tt></a></b>
<dd>
The most recent supported protocol in the
"<tt class=samp>CAPABILITY</tt>" response from the server.
</dl>

<P>
<dl><dt><b><a name="l2h-1729"><tt class=member>debug</tt></a></b>
<dd>
Integer value to control debugging output.  The initialize value is
taken from the module variable <tt>Debug</tt>.  Values greater than
three trace each command.
</dl>

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="imap4-example.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="module-imaplib.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="module-imaplib.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Python Library Reference</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><a
 href="modindex.html"><img width=32 height=32 align=bottom border=0 alt="modules"
 src="../icons/modules.gif"></a></td>
<td><A HREF="genindex.html"><img width=32 height=32 align=bottom border=0 alt="index"
 src="../icons/index.gif"></A></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="imap4-example.html">11.7.2 IMAP4 Example</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="module-imaplib.html">11.7 imaplib  </A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="module-imaplib.html">11.7 imaplib  </A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
