18.1.4. email.mime: Creating email and MIME objects from scratch — Python 2.7.18 documentation

This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

# 18.1.4. `email.mime`: 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.

Here are the classes:

class `email.mime.base.` `MIMEBase`(_maintype, _subtype, **_params)

  Module: `email.mime.base`

  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 `email.mime.nonmultipart.` `MIMENonMultipart`

  Module: `email.mime.nonmultipart`

  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 `email.mime.multipart.` `MIMEMultipart`([_subtype[, boundary[, _subparts[, _params]]]])

  Module: `email.mime.multipart`

  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 (for example, when the message is serialized).

  _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 `email.mime.application.` `MIMEApplication`(_data[, _subtype[, _encoder[, **_params]]])

  Module: `email.mime.application`

  A subclass of `MIMENonMultipart`, the `MIMEApplication` class is used to represent MIME message objects of major type application. _data is a string containing the raw byte data. Optional _subtype specifies the MIME subtype and defaults to octet-stream.

  Optional _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 `MIMEApplication` 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.

  New in version 2.5.

class `email.mime.audio.` `MIMEAudio`(_audiodata[, _subtype[, _encoder[, **_params]]])

  Module: `email.mime.audio`

  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 `email.mime.image.` `MIMEImage`(_imagedata[, _subtype[, _encoder[, **_params]]])

  Module: `email.mime.image`

  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 `email.mime.message.` `MIMEMessage`(_msg[, _subtype])

  Module: `email.mime.message`

  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 `email.mime.text.` `MIMEText`(_text[, _subtype[, _charset]])

  Module: `email.mime.text`

  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`. If _text is unicode, it is encoded using the output_charset of _charset, otherwise it is used as-is.

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

  Unless the `_charset` parameter is explicitly set to `None`, the MIMEText object created will have both a Content-Type header with a `charset` parameter, and a Content-Transfer-Encoding header. This means that a subsequent `set_payload` call will not result in an encoded payload, even if a charset is passed in the `set_payload` command. You can “reset” this behavior by deleting the `Content-Transfer-Encoding` header, after which a `set_payload` call will automatically encode the new payload (and add a new Content-Transfer-Encoding header).