| :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. |