<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.gif" />
<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-email.Header.html">
<LINK rel="prev" href="module-email.Generator.html">
<LINK rel="parent" href="module-email.html">
<LINK rel="next" href="module-email.Header.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name='aesop' content='information' />
<META name="description" content="Creating email and MIME objects from scratch">
<META name="keywords" content="lib">
<META name="resource-type" content="document">
<META name="distribution" content="global">
<title>12.2.4 Creating email and MIME objects from scratch</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="12.2.3.1 Deprecated methods"
href="node500.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="12.2 email "
href="module-email.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="12.2.5 Internationalized headers"
href="module-email.Header.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>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node500.html">12.2.3.1 Deprecated methods</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.html">12.2 email </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-email.Header.html">12.2.5 Internationalized headers</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION0014240000000000000000">
12.2.4 Creating email and MIME objects from scratch</A>
</H2>
Ordinarily, you get a message object structure by passing a file or
some text to a parser, which parses the text and returns the root
message object. However you can also build a complete message
structure from scratch, or even individual <tt class="class">Message</tt> objects by
hand. In fact, you can also take an existing structure and add new
<tt class="class">Message</tt> objects, move them around, etc. This makes a very
convenient interface for slicing-and-dicing MIME messages.
<P>
You can create a new object structure by creating <tt class="class">Message</tt>
instances, adding attachments and all the appropriate headers manually.
For MIME messages though, the <tt class="module">email</tt> package provides some
convenient subclasses to make things easier. Each of these classes
should be imported from a module with the same name as the class, from
within the <tt class="module">email</tt> package. E.g.:
<P>
<div class="verbatim"><pre>
import email.MIMEImage.MIMEImage
</pre></div>
<P>
or
<P>
<div class="verbatim"><pre>
from email.MIMEText import MIMEText
</pre></div>
<P>
Here are the classes:
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3599' class="class">MIMEBase</tt></b>(</nobr></td>
<td><var>_maintype, _subtype, **_params</var>)</td></tr></table></dt>
<dd>
This is the base class for all the MIME-specific subclasses of
<tt class="class">Message</tt>. Ordinarily you won't create instances specifically
of <tt class="class">MIMEBase</tt>, although you could. <tt class="class">MIMEBase</tt> is provided
primarily as a convenient base class for more specific MIME-aware
subclasses.
<P>
<var>_maintype</var> is the <span class="mailheader">Content-Type:</span> major type
(e.g. <span class="mimetype">text</span> or <span class="mimetype">image</span>), and <var>_subtype</var> is the
<span class="mailheader">Content-Type:</span> minor type
(e.g. <span class="mimetype">plain</span> or <span class="mimetype">gif</span>). <var>_params</var> is a parameter
key/value dictionary and is passed directly to
<tt class="method">Message.add_header()</tt>.
<P>
The <tt class="class">MIMEBase</tt> class always adds a <span class="mailheader">Content-Type:</span> header
(based on <var>_maintype</var>, <var>_subtype</var>, and <var>_params</var>), and a
<span class="mailheader">MIME-Version:</span> header (always set to <code>1.0</code>).
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3600' class="class">MIMENonMultipart</tt></b>(</nobr></td>
<td>)</td></tr></table></dt>
<dd>
A subclass of <tt class="class">MIMEBase</tt>, this is an intermediate base class for
MIME messages that are not <span class="mimetype">multipart</span>. The primary purpose
of this class is to prevent the use of the <tt class="method">attach()</tt> method,
which only makes sense for <span class="mimetype">multipart</span> messages. If
<tt class="method">attach()</tt> is called, a <tt class="exception">MultipartConversionError</tt>
exception is raised.
<P>
<span class="versionnote">New in version 2.2.2.</span>
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3601' class="class">MIMEMultipart</tt></b>(</nobr></td>
<td><big>[</big><var>subtype</var><big>[</big><var>,
boundary</var><big>[</big><var>, _subparts</var><big>[</big><var>, _params</var><big>]</big><big>]</big><big>]</big><big>]</big>)</td></tr></table></dt>
<dd>
<P>
A subclass of <tt class="class">MIMEBase</tt>, this is an intermediate base class for
MIME messages that are <span class="mimetype">multipart</span>. Optional <var>_subtype</var>
defaults to <span class="mimetype">mixed</span>, but can be used to specify the subtype
of the message. A <span class="mailheader">Content-Type:</span> header of
<span class="mimetype">multipart/</span><var>_subtype</var> will be added to the message
object. A <span class="mailheader">MIME-Version:</span> header will also be added.
<P>
Optional <var>boundary</var> is the multipart boundary string. When
<code>None</code> (the default), the boundary is calculated when needed.
<P>
<var>_subparts</var> is a sequence of initial subparts for the payload. It
must be possible to convert this sequence to a list. You can always
attach new subparts to the message by using the
<tt class="method">Message.attach()</tt> method.
<P>
Additional parameters for the <span class="mailheader">Content-Type:</span> header are
taken from the keyword arguments, or passed into the <var>_params</var>
argument, which is a keyword dictionary.
<P>
<span class="versionnote">New in version 2.2.2.</span>
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3602' class="class">MIMEAudio</tt></b>(</nobr></td>
<td><var>_audiodata</var><big>[</big><var>, _subtype</var><big>[</big><var>,
_encoder</var><big>[</big><var>, **_params</var><big>]</big><big>]</big><big>]</big>)</td></tr></table></dt>
<dd>
<P>
A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEAudio</tt> class
is used to create MIME message objects of major type <span class="mimetype">audio</span>.
<var>_audiodata</var> is a string containing the raw audio data. If this
data can be decoded by the standard Python module <tt class="module"><a href="module-sndhdr.html">sndhdr</a></tt>,
then the subtype will be automatically included in the
<span class="mailheader">Content-Type:</span> header. Otherwise you can explicitly specify the
audio subtype via the <var>_subtype</var> parameter. If the minor type could
not be guessed and <var>_subtype</var> was not given, then <tt class="exception">TypeError</tt>
is raised.
<P>
Optional <var>_encoder</var> is a callable (i.e. function) which will
perform the actual encoding of the audio data for transport. This
callable takes one argument, which is the <tt class="class">MIMEAudio</tt> instance.
It should use <tt class="method">get_payload()</tt> and <tt class="method">set_payload()</tt> to
change the payload to encoded form. It should also add any
<span class="mailheader">Content-Transfer-Encoding:</span> or other headers to the message
object as necessary. The default encoding is base64. See the
<tt class="module"><a href="module-email.Encoders.html">email.Encoders</a></tt> module for a list of the built-in encoders.
<P>
<var>_params</var> are passed straight through to the base class constructor.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3603' class="class">MIMEImage</tt></b>(</nobr></td>
<td><var>_imagedata</var><big>[</big><var>, _subtype</var><big>[</big><var>,
_encoder</var><big>[</big><var>, **_params</var><big>]</big><big>]</big><big>]</big>)</td></tr></table></dt>
<dd>
<P>
A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEImage</tt> class is
used to create MIME message objects of major type <span class="mimetype">image</span>.
<var>_imagedata</var> is a string containing the raw image data. If this
data can be decoded by the standard Python module <tt class="module"><a href="module-imghdr.html">imghdr</a></tt>,
then the subtype will be automatically included in the
<span class="mailheader">Content-Type:</span> header. Otherwise you can explicitly specify the
image subtype via the <var>_subtype</var> parameter. If the minor type could
not be guessed and <var>_subtype</var> was not given, then <tt class="exception">TypeError</tt>
is raised.
<P>
Optional <var>_encoder</var> is a callable (i.e. function) which will
perform the actual encoding of the image data for transport. This
callable takes one argument, which is the <tt class="class">MIMEImage</tt> instance.
It should use <tt class="method">get_payload()</tt> and <tt class="method">set_payload()</tt> to
change the payload to encoded form. It should also add any
<span class="mailheader">Content-Transfer-Encoding:</span> or other headers to the message
object as necessary. The default encoding is base64. See the
<tt class="module"><a href="module-email.Encoders.html">email.Encoders</a></tt> module for a list of the built-in encoders.
<P>
<var>_params</var> are passed straight through to the <tt class="class">MIMEBase</tt>
constructor.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3604' class="class">MIMEMessage</tt></b>(</nobr></td>
<td><var>_msg</var><big>[</big><var>, _subtype</var><big>]</big>)</td></tr></table></dt>
<dd>
A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEMessage</tt> class
is used to create MIME objects of main type <span class="mimetype">message</span>.
<var>_msg</var> is used as the payload, and must be an instance of class
<tt class="class">Message</tt> (or a subclass thereof), otherwise a
<tt class="exception">TypeError</tt> is raised.
<P>
Optional <var>_subtype</var> sets the subtype of the message; it defaults
to <span class="mimetype">rfc822</span>.
</dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3605' class="class">MIMEText</tt></b>(</nobr></td>
<td><var>_text</var><big>[</big><var>, _subtype</var><big>[</big><var>,
_charset</var><big>[</big><var>, _encoder</var><big>]</big><big>]</big><big>]</big>)</td></tr></table></dt>
<dd>
<P>
A subclass of <tt class="class">MIMENonMultipart</tt>, the <tt class="class">MIMEText</tt> class is
used to create MIME objects of major type <span class="mimetype">text</span>.
<var>_text</var> is the string for the payload. <var>_subtype</var> is the
minor type and defaults to <span class="mimetype">plain</span>. <var>_charset</var> is the
character set of the text and is passed as a parameter to the
<tt class="class">MIMENonMultipart</tt> constructor; it defaults to <code>us-ascii</code>. No
guessing or encoding is performed on the text data.
<P>
<div class="versionnote"><b>Deprecated since release 2.2.2.</b>
The <var>_encoding</var> argument has been deprecated.
Encoding now happens implicitly based on the <var>_charset</var> argument.</div>
</dl>
<P>
<DIV CLASS="navigation">
<div class='online-navigation'><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="12.2.3.1 Deprecated methods"
rel="prev" title="12.2.3.1 Deprecated methods"
href="node500.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="12.2 email "
rel="parent" title="12.2 email "
href="module-email.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="12.2.5 Internationalized headers"
rel="next" title="12.2.5 Internationalized headers"
href="module-email.Header.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"
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"
rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="node500.html">12.2.3.1 Deprecated methods</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-email.html">12.2 email </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-email.Header.html">12.2.5 Internationalized headers</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.3.4, documentation updated on May 20, 2004.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
