cpython/Doc/library/email.mime.rst

:mod:`email.mime`: Creating email and MIME objects from scratch
---------------------------------------------------------------

.. module:: email.mime
   :synopsis: Build MIME messages.

**Source code:** :source:`Lib/email/mime/`

--------------

This module is part of the legacy (``Compat32``) email API.  Its functionality
is partially replaced by the :mod:`~email.contentmanager` in the new API, but
in certain applications these classes may still be useful, even in non-legacy
code.

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:`~email.message.Message` objects by hand.  In fact, you can also take an
existing structure and add new :class:`~email.message.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:`~email.message.Message`
instances, adding attachments and all the appropriate headers manually.  For MIME
messages though, the :mod:`email` package provides some convenient subclasses to
make things easier.

Here are the classes:

.. currentmodule:: email.mime.base

.. class:: MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

   Module: :mod:`email.mime.base`

   This is the base class for all the MIME-specific subclasses of
   :class:`~email.message.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.

   *_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
   or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
   type  (e.g. :mimetype:`plain` or :mimetype:`gif`).  *_params* is a parameter
   key/value dictionary and is passed directly to :meth:`Message.add_header
   <email.message.Message.add_header>`.

   If *policy* is specified, (defaults to the
   :class:`compat32 <email.policy.Compat32>` policy) it will be passed to
   :class:`~email.message.Message`.

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

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.


.. currentmodule:: email.mime.nonmultipart

.. class:: MIMENonMultipart()

   Module: :mod:`email.mime.nonmultipart`

   A subclass of :class:`~email.mime.base.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
   :meth:`~email.message.Message.attach` method, which only makes sense for
   :mimetype:`multipart` messages.  If :meth:`~email.message.Message.attach`
   is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.


.. currentmodule:: email.mime.multipart

.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, \
                         *, policy=compat32, **_params)

   Module: :mod:`email.mime.multipart`

   A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
   class for MIME messages that are :mimetype:`multipart`.  Optional *_subtype*
   defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
   message.  A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
   will be added to the message object.  A :mailheader:`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 :meth:`Message.attach
   <email.message.Message.attach>` method.

   Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.

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

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.

.. currentmodule:: email.mime.application

.. class:: MIMEApplication(_data, _subtype='octet-stream', \
                           _encoder=email.encoders.encode_base64, \
                           *, policy=compat32, **_params)

   Module: :mod:`email.mime.application`

   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
   :class:`MIMEApplication` class is used to represent MIME message objects of
   major type :mimetype:`application`.  *_data* is a string containing the raw
   byte data.  Optional *_subtype* specifies the MIME subtype and defaults to
   :mimetype:`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 :class:`MIMEApplication` instance. It should use
   :meth:`~email.message.Message.get_payload` and
   :meth:`~email.message.Message.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
   :mod:`email.encoders` module for a list of the built-in encoders.

   Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.

   *_params* are passed straight through to the base class constructor.

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.

.. currentmodule:: email.mime.audio

.. class:: MIMEAudio(_audiodata, _subtype=None, \
                     _encoder=email.encoders.encode_base64, \
                     *, policy=compat32, **_params)

   Module: :mod:`email.mime.audio`

   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
   :class:`MIMEAudio` class is used to create MIME message objects of major type
   :mimetype:`audio`. *_audiodata* is a string containing the raw audio data.  If
   this data can be decoded by the standard Python module :mod:`sndhdr`, then the
   subtype will be automatically included in the :mailheader:`Content-Type` header.
   Otherwise you can explicitly specify the audio subtype via the *_subtype*
   argument.  If the minor type could not be guessed and *_subtype* was not given,
   then :exc:`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 :class:`MIMEAudio` instance. It should use
   :meth:`~email.message.Message.get_payload` and
   :meth:`~email.message.Message.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
   :mod:`email.encoders` module for a list of the built-in encoders.

   Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.

   *_params* are passed straight through to the base class constructor.

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.

.. currentmodule:: email.mime.image

.. class:: MIMEImage(_imagedata, _subtype=None, \
                     _encoder=email.encoders.encode_base64, \
                    *, policy=compat32, **_params)

   Module: :mod:`email.mime.image`

   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
   :class:`MIMEImage` class is used to create MIME message objects of major type
   :mimetype:`image`. *_imagedata* is a string containing the raw image data.  If
   this data can be decoded by the standard Python module :mod:`imghdr`, then the
   subtype will be automatically included in the :mailheader:`Content-Type` header.
   Otherwise you can explicitly specify the image subtype via the *_subtype*
   argument.  If the minor type could not be guessed and *_subtype* was not given,
   then :exc:`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 :class:`MIMEImage` instance. It should use
   :meth:`~email.message.Message.get_payload` and
   :meth:`~email.message.Message.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
   :mod:`email.encoders` module for a list of the built-in encoders.

   Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.

   *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
   constructor.

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.

.. currentmodule:: email.mime.message

.. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

   Module: :mod:`email.mime.message`

   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
   :class:`MIMEMessage` class is used to create MIME objects of main type
   :mimetype:`message`. *_msg* is used as the payload, and must be an instance
   of class :class:`~email.message.Message` (or a subclass thereof), otherwise
   a :exc:`TypeError` is raised.

   Optional *_subtype* sets the subtype of the message; it defaults to
   :mimetype:`rfc822`.

   Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.

.. currentmodule:: email.mime.text

.. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

   Module: :mod:`email.mime.text`

   A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
   :class:`MIMEText` class is used to create MIME objects of major type
   :mimetype:`text`. *_text* is the string for the payload.  *_subtype* is the
   minor type and defaults to :mimetype:`plain`.  *_charset* is the character
   set of the text and is passed as an argument to the
   :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
   to ``us-ascii`` if the string contains only ``ascii`` code points, and
   ``utf-8`` otherwise.  The *_charset* parameter accepts either a string or a
   :class:`~email.charset.Charset` instance.

   Unless the *_charset* argument is explicitly set to ``None``, the
   MIMEText object created will have both a :mailheader:`Content-Type` header
   with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding`
   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
   :mailheader:`Content-Transfer-Encoding` header).

   Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`.

   .. versionchanged:: 3.5
      *_charset* also accepts :class:`~email.charset.Charset` instances.

   .. versionchanged:: 3.6
      Added *policy* keyword-only parameter.