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