\declaremodule{standard}{email.mime}\declaremodule{standard}{email.mime.base}\declaremodule{standard}{email.mime.nonmultipart}\declaremodule{standard}{email.mime.multipart}\declaremodule{standard}{email.mime.audio}\declaremodule{standard}{email.mime.image}\declaremodule{standard}{email.mime.message}\declaremodule{standard}{email.mime.text}Ordinarily, you get a message object structure by passing a file orsome text to a parser, which parses the text and returns the rootmessage object. However you can also build a complete messagestructure from scratch, or even individual \class{Message} objects byhand. In fact, you can also take an existing structure and add new\class{Message} objects, move them around, etc. This makes a veryconvenient interface for slicing-and-dicing MIME messages. You can create a new object structure by creating \class{Message} instances,adding attachments and all the appropriate headers manually. For MIMEmessages though, the \module{email} package provides some convenientsubclasses to make things easier. Here are the classes: \begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}Module: \module{email.mime.base} This is the base class for all the MIME-specific subclasses of\class{Message}. Ordinarily you won't create instances specificallyof \class{MIMEBase}, although you could. \class{MIMEBase} is providedprimarily as a convenient base class for more specific MIME-awaresubclasses. \var{_maintype} is the \mailheader{Content-Type} major type(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the\mailheader{Content-Type} minor type (e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameterkey/value dictionary and is passed directly to\method{Message.add_header()}. The \class{MIMEBase} class always adds a \mailheader{Content-Type} header(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a\mailheader{MIME-Version} header (always set to \code{1.0}).\end{classdesc} \begin{classdesc}{MIMENonMultipart}{}Module: \module{email.mime.nonmultipart} A subclass of \class{MIMEBase}, this is an intermediate base class forMIME messages that are not \mimetype{multipart}. The primary purposeof this class is to prevent the use of the \method{attach()} method,which only makes sense for \mimetype{multipart} messages. If\method{attach()} is called, a \exception{MultipartConversionError}exception is raised. \versionadded{2.2.2}\end{classdesc} \begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{, boundary\optional{, _subparts\optional{, _params}}}}}Module: \module{email.mime.multipart} A subclass of \class{MIMEBase}, this is an intermediate base class forMIME messages that are \mimetype{multipart}. Optional \var{_subtype}defaults to \mimetype{mixed}, but can be used to specify the subtypeof the message. A \mailheader{Content-Type} header of\mimetype{multipart/}\var{_subtype} will be added to the messageobject. A \mailheader{MIME-Version} header will also be added. Optional \var{boundary} is the multipart boundary string. When\code{None} (the default), the boundary is calculated when needed. \var{_subparts} is a sequence of initial subparts for the payload. Itmust be possible to convert this sequence to a list. You can alwaysattach new subparts to the message by using the\method{Message.attach()} method. Additional parameters for the \mailheader{Content-Type} header aretaken from the keyword arguments, or passed into the \var{_params}argument, which is a keyword dictionary. \versionadded{2.2.2}\end{classdesc} \begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{, _encoder\optional{, **_params}}}}Module: \module{email.mime.application} A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class isused to represent MIME message objects of major type \mimetype{application}.\var{_data} is a string containing the raw byte data. Optional \var{_subtype}specifies the MIME subtype and defaults to \mimetype{octet-stream}. Optional \var{_encoder} is a callable (i.e. function) which willperform the actual encoding of the data for transport. Thiscallable takes one argument, which is the \class{MIMEApplication} instance.It should use \method{get_payload()} and \method{set_payload()} tochange the payload to encoded form. It should also add any\mailheader{Content-Transfer-Encoding} or other headers to the messageobject as necessary. The default encoding is base64. See the\refmodule{email.encoders} module for a list of the built-in encoders. \var{_params} are passed straight through to the base class constructor.\versionadded{2.5}\end{classdesc} \begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{, _encoder\optional{, **_params}}}}Module: \module{email.mime.audio} A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} classis used to create MIME message objects of major type \mimetype{audio}.\var{_audiodata} is a string containing the raw audio data. If thisdata can be decoded by the standard Python module \refmodule{sndhdr},then the subtype will be automatically included in the\mailheader{Content-Type} header. Otherwise you can explicitly specify theaudio subtype via the \var{_subtype} parameter. If the minor type couldnot be guessed and \var{_subtype} was not given, then \exception{TypeError}is raised. Optional \var{_encoder} is a callable (i.e. function) which willperform the actual encoding of the audio data for transport. Thiscallable takes one argument, which is the \class{MIMEAudio} instance.It should use \method{get_payload()} and \method{set_payload()} tochange the payload to encoded form. It should also add any\mailheader{Content-Transfer-Encoding} or other headers to the messageobject as necessary. The default encoding is base64. See the\refmodule{email.encoders} module for a list of the built-in encoders. \var{_params} are passed straight through to the base class constructor.\end{classdesc} \begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{, _encoder\optional{, **_params}}}}Module: \module{email.mime.image} A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class isused to create MIME message objects of major type \mimetype{image}.\var{_imagedata} is a string containing the raw image data. If thisdata can be decoded by the standard Python module \refmodule{imghdr},then the subtype will be automatically included in the\mailheader{Content-Type} header. Otherwise you can explicitly specify theimage subtype via the \var{_subtype} parameter. If the minor type couldnot be guessed and \var{_subtype} was not given, then \exception{TypeError}is raised. Optional \var{_encoder} is a callable (i.e. function) which willperform the actual encoding of the image data for transport. Thiscallable takes one argument, which is the \class{MIMEImage} instance.It should use \method{get_payload()} and \method{set_payload()} tochange the payload to encoded form. It should also add any\mailheader{Content-Transfer-Encoding} or other headers to the messageobject as necessary. The default encoding is base64. See the\refmodule{email.encoders} module for a list of the built-in encoders. \var{_params} are passed straight through to the \class{MIMEBase}constructor.\end{classdesc} \begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}Module: \module{email.mime.message} A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} classis used to create MIME objects of main type \mimetype{message}.\var{_msg} is used as the payload, and must be an instance of class\class{Message} (or a subclass thereof), otherwise a\exception{TypeError} is raised. Optional \var{_subtype} sets the subtype of the message; it defaultsto \mimetype{rfc822}.\end{classdesc} \begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}}Module: \module{email.mime.text} A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class isused to create MIME objects of major type \mimetype{text}.\var{_text} is the string for the payload. \var{_subtype} is theminor type and defaults to \mimetype{plain}. \var{_charset} is thecharacter set of the text and is passed as a parameter to the\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. Noguessing or encoding is performed on the text data. \versionchanged[The previously deprecated \var{_encoding} argument hasbeen removed. Encoding happens implicitly based on the \var{_charset}argument]{2.4}\end{classdesc}
\declaremodule{standard}{email.mime}
\declaremodule{standard}{email.mime.base}
\declaremodule{standard}{email.mime.nonmultipart}
\declaremodule{standard}{email.mime.multipart}
\declaremodule{standard}{email.mime.audio}
\declaremodule{standard}{email.mime.image}
\declaremodule{standard}{email.mime.message}
\declaremodule{standard}{email.mime.text}
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 \class{Message} objects by
hand. In fact, you can also take an existing structure and add new
\class{Message} objects, move them around, etc. This makes a very
convenient interface for slicing-and-dicing MIME messages.
You can create a new object structure by creating \class{Message} instances,
adding attachments and all the appropriate headers manually. For MIME
messages though, the \module{email} package provides some convenient
subclasses to make things easier.
Here are the classes:
\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params}
Module: \module{email.mime.base}
This is the base class for all the MIME-specific subclasses of
\class{Message}. Ordinarily you won't create instances specifically
of \class{MIMEBase}, although you could. \class{MIMEBase} is provided
primarily as a convenient base class for more specific MIME-aware
subclasses.
\var{_maintype} is the \mailheader{Content-Type} major type
(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the
\mailheader{Content-Type} minor type
(e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter
key/value dictionary and is passed directly to
\method{Message.add_header()}.
The \class{MIMEBase} class always adds a \mailheader{Content-Type} header
(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a
\mailheader{MIME-Version} header (always set to \code{1.0}).
\end{classdesc}
\begin{classdesc}{MIMENonMultipart}{}
Module: \module{email.mime.nonmultipart}
A subclass of \class{MIMEBase}, this is an intermediate base class for
MIME messages that are not \mimetype{multipart}. The primary purpose
of this class is to prevent the use of the \method{attach()} method,
which only makes sense for \mimetype{multipart} messages. If
\method{attach()} is called, a \exception{MultipartConversionError}
exception is raised.
\versionadded{2.2.2}
\end{classdesc}
\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{,
boundary\optional{, _subparts\optional{, _params}}}}}
Module: \module{email.mime.multipart}
A subclass of \class{MIMEBase}, this is an intermediate base class for
MIME messages that are \mimetype{multipart}. Optional \var{_subtype}
defaults to \mimetype{mixed}, but can be used to specify the subtype
of the message. A \mailheader{Content-Type} header of
\mimetype{multipart/}\var{_subtype} will be added to the message
object. A \mailheader{MIME-Version} header will also be added.
Optional \var{boundary} is the multipart boundary string. When
\code{None} (the default), the boundary is calculated when needed.
\var{_subparts} 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
\method{Message.attach()} method.
Additional parameters for the \mailheader{Content-Type} header are
taken from the keyword arguments, or passed into the \var{_params}
argument, which is a keyword dictionary.
\versionadded{2.2.2}
\end{classdesc}
\begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{,
_encoder\optional{, **_params}}}}
Module: \module{email.mime.application}
A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class is
used to represent MIME message objects of major type \mimetype{application}.
\var{_data} is a string containing the raw byte data. Optional \var{_subtype}
specifies the MIME subtype and defaults to \mimetype{octet-stream}.
Optional \var{_encoder} is a callable (i.e. function) which will
perform the actual encoding of the data for transport. This
callable takes one argument, which is the \class{MIMEApplication} instance.
It should use \method{get_payload()} and \method{set_payload()} to
change the payload to encoded form. It should also add any
\mailheader{Content-Transfer-Encoding} or other headers to the message
object as necessary. The default encoding is base64. See the
\refmodule{email.encoders} module for a list of the built-in encoders.
\var{_params} are passed straight through to the base class constructor.
\versionadded{2.5}
\end{classdesc}
\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{,
_encoder\optional{, **_params}}}}
Module: \module{email.mime.audio}
A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class
is used to create MIME message objects of major type \mimetype{audio}.
\var{_audiodata} is a string containing the raw audio data. If this
data can be decoded by the standard Python module \refmodule{sndhdr},
then the subtype will be automatically included in the
\mailheader{Content-Type} header. Otherwise you can explicitly specify the
audio subtype via the \var{_subtype} parameter. If the minor type could
not be guessed and \var{_subtype} was not given, then \exception{TypeError}
is raised.
Optional \var{_encoder} 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 \class{MIMEAudio} instance.
It should use \method{get_payload()} and \method{set_payload()} to
change the payload to encoded form. It should also add any
\mailheader{Content-Transfer-Encoding} or other headers to the message
object as necessary. The default encoding is base64. See the
\refmodule{email.encoders} module for a list of the built-in encoders.
\var{_params} are passed straight through to the base class constructor.
\end{classdesc}
\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{,
_encoder\optional{, **_params}}}}
Module: \module{email.mime.image}
A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is
used to create MIME message objects of major type \mimetype{image}.
\var{_imagedata} is a string containing the raw image data. If this
data can be decoded by the standard Python module \refmodule{imghdr},
then the subtype will be automatically included in the
\mailheader{Content-Type} header. Otherwise you can explicitly specify the
image subtype via the \var{_subtype} parameter. If the minor type could
not be guessed and \var{_subtype} was not given, then \exception{TypeError}
is raised.
Optional \var{_encoder} 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 \class{MIMEImage} instance.
It should use \method{get_payload()} and \method{set_payload()} to
change the payload to encoded form. It should also add any
\mailheader{Content-Transfer-Encoding} or other headers to the message
object as necessary. The default encoding is base64. See the
\refmodule{email.encoders} module for a list of the built-in encoders.
\var{_params} are passed straight through to the \class{MIMEBase}
constructor.
\end{classdesc}
\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}}
Module: \module{email.mime.message}
A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class
is used to create MIME objects of main type \mimetype{message}.
\var{_msg} is used as the payload, and must be an instance of class
\class{Message} (or a subclass thereof), otherwise a
\exception{TypeError} is raised.
Optional \var{_subtype} sets the subtype of the message; it defaults
to \mimetype{rfc822}.
\end{classdesc}
\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}}
Module: \module{email.mime.text}
A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is
used to create MIME objects of major type \mimetype{text}.
\var{_text} is the string for the payload. \var{_subtype} is the
minor type and defaults to \mimetype{plain}. \var{_charset} is the
character set of the text and is passed as a parameter to the
\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No
guessing or encoding is performed on the text data.
\versionchanged[The previously deprecated \var{_encoding} argument has
been removed. Encoding happens implicitly based on the \var{_charset}
argument]{2.4}
\end{classdesc}