12.2.4 Creating email and MIME objects from scratch

Ordinarily, you get a message object tree by passing some text to a parser, which parses the text and returns the root of the message object tree. However you can also build a complete object tree from scratch, or even individual Message objects by hand. In fact, you can also take an existing tree and add new Message objects, move them around, etc. This makes a very convenient interface for slicing-and-dicing MIME messages.

You can create a new object tree by creating Message instances, adding payloads and all the appropriate headers manually. For MIME messages though, the email package provides some convenient classes to make things easier. Each of these classes should be imported from a module with the same name as the class, from within the email package. E.g.:

import email.MIMEImage.MIMEImage

from email.MIMEText import MIMEText

Here are the classes:

class MIMEBase(_maintype, _subtype, **_params)

This is the base class for all the MIME-specific subclasses of Message. Ordinarily you won't create instances specifically of MIMEBase, although you could. MIMEBase is provided primarily as a convenient base class for more specific MIME-aware subclasses.

_maintype is the Content-Type: major type (e.g. text or image), and _subtype is the Content-Type: minor type (e.g. plain or gif). _params is a parameter key/value dictionary and is passed directly to Message.add_header().

The MIMEBase class always adds a Content-Type: header (based on _maintype, _subtype, and _params), and a MIME-Version: header (always set to 1.0).

class MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])

A subclass of MIMEBase, the MIMEAudio class is used to create MIME message objects of major type audio. _audiodata is a string containing the raw audio data. If this data can be decoded by the standard Python module sndhdr, then the subtype will be automatically included in the Content-Type: header. Otherwise you can explicitly specify the audio subtype via the _subtype parameter. If the minor type could not be guessed and _subtype was not given, then TypeError is raised.

Optional _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 MIMEAudio instance. It should use get_payload() and set_payload() to change the payload to encoded form. It should also add any Content-Transfer-Encoding: or other headers to the message object as necessary. The default encoding is Base64. See the email.Encoders module for a list of the built-in encoders.

_params are passed straight through to the MIMEBase constructor.

class MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])

A subclass of MIMEBase, the MIMEImage class is used to create MIME message objects of major type image. _imagedata is a string containing the raw image data. If this data can be decoded by the standard Python module imghdr, then the subtype will be automatically included in the Content-Type: header. Otherwise you can explicitly specify the image subtype via the _subtype parameter. If the minor type could not be guessed and _subtype was not given, then TypeError is raised.

Optional _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 MIMEImage instance. It should use get_payload() and set_payload() to change the payload to encoded form. It should also add any Content-Transfer-Encoding: or other headers to the message object as necessary. The default encoding is Base64. See the email.Encoders module for a list of the built-in encoders.

_params are passed straight through to the MIMEBase constructor.

class MIMEText(_text[, _subtype[, _charset[, _encoder]]])

A subclass of MIMEBase, the MIMEText class is used to create MIME objects of major type text. _text is the string for the payload. _subtype is the minor type and defaults to plain. _charset is the character set of the text and is passed as a parameter to the MIMEBase constructor; it defaults to us-ascii. No guessing or encoding is performed on the text data, but a newline is appended to _text if it doesn't already end with a newline.

The _encoding argument is as with the MIMEImage class constructor, except that the default encoding for MIMEText objects is one that doesn't actually modify the payload, but does set the Content-Transfer-Encoding: header to 7bit or 8bit as appropriate.

class MIMEMessage(_msg[, _subtype]): A subclass of MIMEBase, the MIMEMessage class is used to create MIME objects of main type message. _msg is used as the payload, and must be an instance of class Message (or a subclass thereof), otherwise a TypeError is raised.
Optional _subtype sets the subtype of the message; it defaults to rfc822.

See About this document... for information on suggesting changes.