## 12.2.4 Creating email and MIME objects from scratch

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 `Message` objects by hand. In fact, you can also take an existing structure 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 structure by creating `Message` instances, adding attachments and all the appropriate headers manually. For MIME messages though, the `email` 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 `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 `MIMENonMultipart`( | )

  A subclass of `MIMEBase`, this is an intermediate base class for MIME messages that are not multipart. The primary purpose of this class is to prevent the use of the `attach()` method, which only makes sense for multipart messages. If `attach()` is called, a `MultipartConversionError` exception is raised.

  New in version 2.2.2.

class `MIMEMultipart`( | [subtype[, boundary[, _subparts[, _params]]]])

  A subclass of `MIMEBase`, this is an intermediate base class for MIME messages that are multipart. Optional _subtype defaults to mixed, but can be used to specify the subtype of the message. A Content-Type: header of multipart/_subtype will be added to the message object. A MIME-Version: header will also be added.

  Optional boundary is the multipart boundary string. When `None` (the default), the boundary is calculated when needed.

  _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 `Message.attach()` method.

  Additional parameters for the Content-Type: header are taken from the keyword arguments, or passed into the _params argument, which is a keyword dictionary.

  New in version 2.2.2.

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

  A subclass of `MIMENonMultipart`, 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 base class constructor.

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

  A subclass of `MIMENonMultipart`, 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 `MIMEMessage`( | _msg[, _subtype])

  A subclass of `MIMENonMultipart`, 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.

class `MIMEText`( | _text[, _subtype[, _charset]])

  A subclass of `MIMENonMultipart`, 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 `MIMENonMultipart` constructor; it defaults to `us-ascii`. No guessing or encoding is performed on the text data.

  Changed in version 2.4: The previously deprecated _encoding argument has been removed. Encoding happens implicitly based on the _charset argument.