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 11This module is part of the legacy (``Compat32``) email API. Its functionality 12is partially replaced by the :mod:`~email.contentmanager` in the new API, but 13in certain applications these classes may still be useful, even in non-legacy 14code. 15 16Ordinarily, you get a message object structure by passing a file or some text to 17a parser, which parses the text and returns the root message object. However 18you 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 20existing structure and add new :class:`~email.message.Message` objects, move them 21around, etc. This makes a very convenient interface for slicing-and-dicing MIME 22messages. 23 24You can create a new object structure by creating :class:`~email.message.Message` 25instances, adding attachments and all the appropriate headers manually. For MIME 26messages though, the :mod:`email` package provides some convenient subclasses to 27make things easier. 28 29Here are the classes: 30 31.. currentmodule:: 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.. currentmodule:: 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.. currentmodule:: 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.. currentmodule:: 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* is a string containing the raw 118 byte data. Optional *_subtype* specifies the MIME subtype and defaults to 119 :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.. currentmodule:: 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* is a string containing the raw audio data. If 149 this data can be decoded by the standard Python module :mod:`sndhdr`, 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.. currentmodule:: 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* is a string containing the raw image data. If 183 this data can be decoded by the standard Python module :mod:`imghdr`, then the 184 subtype will be automatically included in the :mailheader:`Content-Type` header. 185 Otherwise you can explicitly specify the image subtype via the *_subtype* 186 argument. If the minor type could not be guessed and *_subtype* was not given, 187 then :exc:`TypeError` is raised. 188 189 Optional *_encoder* is a callable (i.e. function) which will perform the actual 190 encoding of the image data for transport. This callable takes one argument, 191 which is the :class:`MIMEImage` instance. It should use 192 :meth:`~email.message.Message.get_payload` and 193 :meth:`~email.message.Message.set_payload` to change the payload to encoded 194 form. It should also add 195 any :mailheader:`Content-Transfer-Encoding` or other headers to the message 196 object as necessary. The default encoding is base64. See the 197 :mod:`email.encoders` module for a list of the built-in encoders. 198 199 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. 200 201 *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase` 202 constructor. 203 204 .. versionchanged:: 3.6 205 Added *policy* keyword-only parameter. 206 207.. currentmodule:: email.mime.message 208 209.. class:: MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32) 210 211 Module: :mod:`email.mime.message` 212 213 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the 214 :class:`MIMEMessage` class is used to create MIME objects of main type 215 :mimetype:`message`. *_msg* is used as the payload, and must be an instance 216 of class :class:`~email.message.Message` (or a subclass thereof), otherwise 217 a :exc:`TypeError` is raised. 218 219 Optional *_subtype* sets the subtype of the message; it defaults to 220 :mimetype:`rfc822`. 221 222 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. 223 224 .. versionchanged:: 3.6 225 Added *policy* keyword-only parameter. 226 227.. currentmodule:: email.mime.text 228 229.. class:: MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32) 230 231 Module: :mod:`email.mime.text` 232 233 A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the 234 :class:`MIMEText` class is used to create MIME objects of major type 235 :mimetype:`text`. *_text* is the string for the payload. *_subtype* is the 236 minor type and defaults to :mimetype:`plain`. *_charset* is the character 237 set of the text and is passed as an argument to the 238 :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults 239 to ``us-ascii`` if the string contains only ``ascii`` code points, and 240 ``utf-8`` otherwise. The *_charset* parameter accepts either a string or a 241 :class:`~email.charset.Charset` instance. 242 243 Unless the *_charset* argument is explicitly set to ``None``, the 244 MIMEText object created will have both a :mailheader:`Content-Type` header 245 with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding` 246 header. This means that a subsequent ``set_payload`` call will not result 247 in an encoded payload, even if a charset is passed in the ``set_payload`` 248 command. You can "reset" this behavior by deleting the 249 ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call 250 will automatically encode the new payload (and add a new 251 :mailheader:`Content-Transfer-Encoding` header). 252 253 Optional *policy* argument defaults to :class:`compat32 <email.policy.Compat32>`. 254 255 .. versionchanged:: 3.5 256 *_charset* also accepts :class:`~email.charset.Charset` instances. 257 258 .. versionchanged:: 3.6 259 Added *policy* keyword-only parameter. 260