## 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

or

      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.