| 1 |
:mod:`!email.mime`: Creating email and MIME objects from scratch |
| 2 |
---------------------------------------------------------------- |
| 3 |
|
| 4 |
.. module:: email.mime |
| 5 |
:synopsis: Build MIME messages. |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/email/mime/` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
This module is part of the legacy (``Compat32``) email API. Its functionality |
| 12 |
is partially replaced by the :mod:`~email.contentmanager` in the new API, but |
| 13 |
in certain applications these classes may still be useful, even in non-legacy |
| 14 |
code. |
| 15 |
|
| 16 |
Ordinarily, you get a message object structure by passing a file or some text to |
| 17 |
a parser, which parses the text and returns the root message object. However |
| 18 |
you can also build a complete message structure from scratch, or even individual |
| 19 |
:class:`~email.message.Message` objects by hand. In fact, you can also take an |
| 20 |
existing structure and add new :class:`~email.message.Message` objects, move them |
| 21 |
around, etc. This makes a very convenient interface for slicing-and-dicing MIME |
| 22 |
messages. |
| 23 |
|
| 24 |
You can create a new object structure by creating :class:`~email.message.Message` |
| 25 |
instances, adding attachments and all the appropriate headers manually. For MIME |
| 26 |
messages though, the :mod:`email` package provides some convenient subclasses to |
| 27 |
make things easier. |
| 28 |
|
| 29 |
Here are the classes: |
| 30 |
|
| 31 |
.. module:: email.mime.base |
| 32 |
|
| 33 |
.. class:: MIMEBase(_maintype, _subtype, *, policy=compat32, **_params) |
| 34 |
|
| 35 |
Module: :mod:`email.mime.base` |
| 36 |
|
| 37 |
This is the base class for all the MIME-specific subclasses of |
| 38 |
:class:`~email.message.Message`. Ordinarily you won't create instances |
| 39 |
specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase` |
| 40 |
is provided primarily as a convenient base class for more specific |
| 41 |
MIME-aware subclasses. |
| 42 |
|
| 43 |
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text` |
| 44 |
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor |
| 45 |
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter |
| 46 |
key/value dictionary and is passed directly to :meth:`Message.add_header |
| 47 |
<email.message.Message.add_header>`. |
| 48 |
|
| 49 |
If *policy* is specified, (defaults to the |
| 50 |
:class:`compat32 <email.policy.Compat32>` policy) it will be passed to |
| 51 |
:class:`~email.message.Message`. |
| 52 |
|
| 53 |
The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header |
| 54 |
(based on *_maintype*, *_subtype*, and *_params*), and a |
| 55 |
:mailheader:`MIME-Version` header (always set to ``1.0``). |
| 56 |
|
| 57 |
.. versionchanged:: 3.6 |
| 58 |
Added *policy* keyword-only parameter. |
| 59 |
|
| 60 |
|
| 61 |
.. module:: email.mime.nonmultipart |
| 62 |
|
| 63 |
.. class:: MIMENonMultipart() |
| 64 |
|
| 65 |
Module: :mod:`email.mime.nonmultipart` |
| 66 |
|
| 67 |
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base |
| 68 |
class for MIME messages that are not :mimetype:`multipart`. The primary |
| 69 |
purpose of this class is to prevent the use of the |
| 70 |
:meth:`~email.message.Message.attach` method, which only makes sense for |
| 71 |
:mimetype:`multipart` messages. If :meth:`~email.message.Message.attach` |
| 72 |
is called, a :exc:`~email.errors.MultipartConversionError` exception is raised. |
| 73 |
|
| 74 |
|
| 75 |
.. module:: email.mime.multipart |
| 76 |
|
| 77 |
.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, \ |
| 78 |
*, policy=compat32, **_params) |
| 79 |
|
| 80 |
Module: :mod:`email.mime.multipart` |
| 81 |
|
| 82 |
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base |
| 83 |
class for MIME messages that are :mimetype:`multipart`. Optional *_subtype* |
| 84 |
defaults to :mimetype:`mixed`, but can be used to specify the subtype of the |
| 85 |
message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype` |
| 86 |
will be added to the message object. A :mailheader:`MIME-Version` header will |
| 87 |
also be added. |
| 88 |
|
| 89 |
Optional *boundary* is the multipart boundary string. When ``None`` (the |
| 90 |
default), the boundary is calculated when needed (for example, when the |
| 91 |
message is serialized). |
| 92 |
|
| 93 |
*_subparts* is a sequence of initial subparts for the payload. It must be |
| 94 |
possible to convert this sequence to a list. You can always attach new subparts |
| 95 |
to the message by using the :meth:`Message.attach |
| 96 |
<email.message.Message.attach>` method. |
| 97 |
|
| 98 |
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. |
| 99 |
|
| 100 |
Additional parameters for the :mailheader:`Content-Type` header are taken from |
| 101 |
the keyword arguments, or passed into the *_params* argument, which is a keyword |
| 102 |
dictionary. |
| 103 |
|
| 104 |
.. versionchanged:: 3.6 |
| 105 |
Added *policy* keyword-only parameter. |
| 106 |
|
| 107 |
.. module:: email.mime.application |
| 108 |
|
| 109 |
.. class:: MIMEApplication(_data, _subtype='octet-stream', \ |
| 110 |
_encoder=email.encoders.encode_base64, \ |
| 111 |
*, policy=compat32, **_params) |
| 112 |
|
| 113 |
Module: :mod:`email.mime.application` |
| 114 |
|
| 115 |
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 116 |
:class:`MIMEApplication` class is used to represent MIME message objects of |
| 117 |
major type :mimetype:`application`. *_data* contains the bytes for the raw |
| 118 |
application data. Optional *_subtype* specifies the MIME subtype and defaults |
| 119 |
to :mimetype:`octet-stream`. |
| 120 |
|
| 121 |
Optional *_encoder* is a callable (i.e. function) which will perform the actual |
| 122 |
encoding of the data for transport. This callable takes one argument, which is |
| 123 |
the :class:`MIMEApplication` instance. It should use |
| 124 |
:meth:`~email.message.Message.get_payload` and |
| 125 |
:meth:`~email.message.Message.set_payload` to change the payload to encoded |
| 126 |
form. It should also add |
| 127 |
any :mailheader:`Content-Transfer-Encoding` or other headers to the message |
| 128 |
object as necessary. The default encoding is base64. See the |
| 129 |
:mod:`email.encoders` module for a list of the built-in encoders. |
| 130 |
|
| 131 |
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. |
| 132 |
|
| 133 |
*_params* are passed straight through to the base class constructor. |
| 134 |
|
| 135 |
.. versionchanged:: 3.6 |
| 136 |
Added *policy* keyword-only parameter. |
| 137 |
|
| 138 |
.. module:: email.mime.audio |
| 139 |
|
| 140 |
.. class:: MIMEAudio(_audiodata, _subtype=None, \ |
| 141 |
_encoder=email.encoders.encode_base64, \ |
| 142 |
*, policy=compat32, **_params) |
| 143 |
|
| 144 |
Module: :mod:`email.mime.audio` |
| 145 |
|
| 146 |
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 147 |
:class:`MIMEAudio` class is used to create MIME message objects of major type |
| 148 |
:mimetype:`audio`. *_audiodata* contains the bytes for the raw audio data. If |
| 149 |
this data can be decoded as au, wav, aiff, or aifc, then the |
| 150 |
subtype will be automatically included in the :mailheader:`Content-Type` header. |
| 151 |
Otherwise you can explicitly specify the audio subtype via the *_subtype* |
| 152 |
argument. If the minor type could not be guessed and *_subtype* was not given, |
| 153 |
then :exc:`TypeError` is raised. |
| 154 |
|
| 155 |
Optional *_encoder* is a callable (i.e. function) which will perform the actual |
| 156 |
encoding of the audio data for transport. This callable takes one argument, |
| 157 |
which is the :class:`MIMEAudio` instance. It should use |
| 158 |
:meth:`~email.message.Message.get_payload` and |
| 159 |
:meth:`~email.message.Message.set_payload` to change the payload to encoded |
| 160 |
form. It should also add |
| 161 |
any :mailheader:`Content-Transfer-Encoding` or other headers to the message |
| 162 |
object as necessary. The default encoding is base64. See the |
| 163 |
:mod:`email.encoders` module for a list of the built-in encoders. |
| 164 |
|
| 165 |
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. |
| 166 |
|
| 167 |
*_params* are passed straight through to the base class constructor. |
| 168 |
|
| 169 |
.. versionchanged:: 3.6 |
| 170 |
Added *policy* keyword-only parameter. |
| 171 |
|
| 172 |
.. module:: email.mime.image |
| 173 |
|
| 174 |
.. class:: MIMEImage(_imagedata, _subtype=None, \ |
| 175 |
_encoder=email.encoders.encode_base64, \ |
| 176 |
*, policy=compat32, **_params) |
| 177 |
|
| 178 |
Module: :mod:`email.mime.image` |
| 179 |
|
| 180 |
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 181 |
:class:`MIMEImage` class is used to create MIME message objects of major type |
| 182 |
:mimetype:`image`. *_imagedata* contains the bytes for the raw image data. If |
| 183 |
this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, |
| 184 |
rast, xbm, bmp, webp, and exr attempted), then the subtype will be |
| 185 |
automatically included in the :mailheader:`Content-Type` header. Otherwise |
| 186 |
you can explicitly specify the image subtype via the *_subtype* argument. |
| 187 |
If the minor type could not be guessed and *_subtype* was not given, then |
| 188 |
:exc:`TypeError` is raised. |
| 189 |
|
| 190 |
Optional *_encoder* is a callable (i.e. function) which will perform the actual |
| 191 |
encoding of the image data for transport. This callable takes one argument, |
| 192 |
which is the :class:`MIMEImage` instance. It should use |
| 193 |
:meth:`~email.message.Message.get_payload` and |
| 194 |
:meth:`~email.message.Message.set_payload` to change the payload to encoded |
| 195 |
form. It should also add |
| 196 |
any :mailheader:`Content-Transfer-Encoding` or other headers to the message |
| 197 |
object as necessary. The default encoding is base64. See the |
| 198 |
:mod:`email.encoders` module for a list of the built-in encoders. |
| 199 |
|
| 200 |
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. |
| 201 |
|
| 202 |
*_params* are passed straight through to the :class:`~email.mime.base.MIMEBase` |
| 203 |
constructor. |
| 204 |
|
| 205 |
.. versionchanged:: 3.6 |
| 206 |
Added *policy* keyword-only parameter. |
| 207 |
|
| 208 |
.. module:: email.mime.message |
| 209 |
|
| 210 |
.. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32) |
| 211 |
|
| 212 |
Module: :mod:`email.mime.message` |
| 213 |
|
| 214 |
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 215 |
:class:`MIMEMessage` class is used to create MIME objects of main type |
| 216 |
:mimetype:`message`. *_msg* is used as the payload, and must be an instance |
| 217 |
of class :class:`~email.message.Message` (or a subclass thereof), otherwise |
| 218 |
a :exc:`TypeError` is raised. |
| 219 |
|
| 220 |
Optional *_subtype* sets the subtype of the message; it defaults to |
| 221 |
:mimetype:`rfc822`. |
| 222 |
|
| 223 |
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. |
| 224 |
|
| 225 |
.. versionchanged:: 3.6 |
| 226 |
Added *policy* keyword-only parameter. |
| 227 |
|
| 228 |
.. module:: email.mime.text |
| 229 |
|
| 230 |
.. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32) |
| 231 |
|
| 232 |
Module: :mod:`email.mime.text` |
| 233 |
|
| 234 |
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 235 |
:class:`MIMEText` class is used to create MIME objects of major type |
| 236 |
:mimetype:`text`. *_text* is the string for the payload. *_subtype* is the |
| 237 |
minor type and defaults to :mimetype:`plain`. *_charset* is the character |
| 238 |
set of the text and is passed as an argument to the |
| 239 |
:class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults |
| 240 |
to ``us-ascii`` if the string contains only ``ascii`` code points, and |
| 241 |
``utf-8`` otherwise. The *_charset* parameter accepts either a string or a |
| 242 |
:class:`~email.charset.Charset` instance. |
| 243 |
|
| 244 |
Unless the *_charset* argument is explicitly set to ``None``, the |
| 245 |
MIMEText object created will have both a :mailheader:`Content-Type` header |
| 246 |
with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding` |
| 247 |
header. This means that a subsequent ``set_payload`` call will not result |
| 248 |
in an encoded payload, even if a charset is passed in the ``set_payload`` |
| 249 |
command. You can "reset" this behavior by deleting the |
| 250 |
``Content-Transfer-Encoding`` header, after which a ``set_payload`` call |
| 251 |
will automatically encode the new payload (and add a new |
| 252 |
:mailheader:`Content-Transfer-Encoding` header). |
| 253 |
|
| 254 |
Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. |
| 255 |
|
| 256 |
.. versionchanged:: 3.5 |
| 257 |
*_charset* also accepts :class:`~email.charset.Charset` instances. |
| 258 |
|
| 259 |
.. versionchanged:: 3.6 |
| 260 |
Added *policy* keyword-only parameter. |