R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 1 | :mod:`email.mime`: Creating email and MIME objects from scratch |
| 2 | --------------------------------------------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: email.mime |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 5 | :synopsis: Build MIME messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | |
| 21 | Here are the classes: |
| 22 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 23 | .. currentmodule:: email.mime.base |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
| 25 | .. class:: MIMEBase(_maintype, _subtype, **_params) |
| 26 | |
| 27 | Module: :mod:`email.mime.base` |
| 28 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 38 | key/value dictionary and is passed directly to :meth:`Message.add_header |
| 39 | <email.message.Message.add_header>`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 46 | .. currentmodule:: email.mime.nonmultipart |
| 47 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | .. class:: MIMENonMultipart() |
| 49 | |
| 50 | Module: :mod:`email.mime.nonmultipart` |
| 51 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 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 |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 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` |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 57 | is called, a :exc:`~email.errors.MultipartConversionError` exception is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 60 | .. currentmodule:: email.mime.multipart |
| 61 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 62 | .. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, **_params) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
| 64 | Module: :mod:`email.mime.multipart` |
| 65 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 66 | A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base |
| 67 | class for MIME messages that are :mimetype:`multipart`. Optional *_subtype* |
| 68 | defaults to :mimetype:`mixed`, but can be used to specify the subtype of the |
| 69 | message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype` |
| 70 | will be added to the message object. A :mailheader:`MIME-Version` header will |
| 71 | also be added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
| 73 | Optional *boundary* is the multipart boundary string. When ``None`` (the |
R. David Murray | 101f278 | 2010-01-10 19:18:27 +0000 | [diff] [blame] | 74 | default), the boundary is calculated when needed (for example, when the |
| 75 | message is serialized). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
| 77 | *_subparts* is a sequence of initial subparts for the payload. It must be |
| 78 | possible to convert this sequence to a list. You can always attach new subparts |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 79 | to the message by using the :meth:`Message.attach |
| 80 | <email.message.Message.attach>` method. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
| 82 | Additional parameters for the :mailheader:`Content-Type` header are taken from |
| 83 | the keyword arguments, or passed into the *_params* argument, which is a keyword |
| 84 | dictionary. |
| 85 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 87 | .. currentmodule:: email.mime.application |
| 88 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 89 | .. class:: MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, **_params) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
| 91 | Module: :mod:`email.mime.application` |
| 92 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 93 | A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 94 | :class:`MIMEApplication` class is used to represent MIME message objects of |
| 95 | major type :mimetype:`application`. *_data* is a string containing the raw |
| 96 | byte data. Optional *_subtype* specifies the MIME subtype and defaults to |
| 97 | :mimetype:`octet-stream`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
| 99 | Optional *_encoder* is a callable (i.e. function) which will perform the actual |
| 100 | encoding of the data for transport. This callable takes one argument, which is |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 101 | the :class:`MIMEApplication` instance. It should use |
| 102 | :meth:`~email.message.Message.get_payload` and |
| 103 | :meth:`~email.message.Message.set_payload` to change the payload to encoded |
| 104 | form. It should also add |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | any :mailheader:`Content-Transfer-Encoding` or other headers to the message |
| 106 | object as necessary. The default encoding is base64. See the |
| 107 | :mod:`email.encoders` module for a list of the built-in encoders. |
| 108 | |
| 109 | *_params* are passed straight through to the base class constructor. |
| 110 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 112 | .. currentmodule:: email.mime.audio |
| 113 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 114 | .. class:: MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, **_params) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
| 116 | Module: :mod:`email.mime.audio` |
| 117 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 118 | A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 119 | :class:`MIMEAudio` class is used to create MIME message objects of major type |
| 120 | :mimetype:`audio`. *_audiodata* is a string containing the raw audio data. If |
| 121 | this data can be decoded by the standard Python module :mod:`sndhdr`, then the |
| 122 | subtype will be automatically included in the :mailheader:`Content-Type` header. |
| 123 | Otherwise you can explicitly specify the audio subtype via the *_subtype* |
Ezio Melotti | 93115e0 | 2013-03-20 13:53:32 +0200 | [diff] [blame] | 124 | argument. If the minor type could not be guessed and *_subtype* was not given, |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 125 | then :exc:`TypeError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | Optional *_encoder* is a callable (i.e. function) which will perform the actual |
| 128 | encoding of the audio data for transport. This callable takes one argument, |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 129 | which is the :class:`MIMEAudio` instance. It should use |
| 130 | :meth:`~email.message.Message.get_payload` and |
| 131 | :meth:`~email.message.Message.set_payload` to change the payload to encoded |
| 132 | form. It should also add |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | any :mailheader:`Content-Transfer-Encoding` or other headers to the message |
| 134 | object as necessary. The default encoding is base64. See the |
| 135 | :mod:`email.encoders` module for a list of the built-in encoders. |
| 136 | |
| 137 | *_params* are passed straight through to the base class constructor. |
| 138 | |
| 139 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 140 | .. currentmodule:: email.mime.image |
| 141 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 142 | .. class:: MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, **_params) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | Module: :mod:`email.mime.image` |
| 145 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 146 | A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 147 | :class:`MIMEImage` class is used to create MIME message objects of major type |
| 148 | :mimetype:`image`. *_imagedata* is a string containing the raw image data. If |
| 149 | this data can be decoded by the standard Python module :mod:`imghdr`, then the |
| 150 | subtype will be automatically included in the :mailheader:`Content-Type` header. |
| 151 | Otherwise you can explicitly specify the image subtype via the *_subtype* |
Ezio Melotti | 93115e0 | 2013-03-20 13:53:32 +0200 | [diff] [blame] | 152 | argument. If the minor type could not be guessed and *_subtype* was not given, |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 153 | then :exc:`TypeError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 154 | |
| 155 | Optional *_encoder* is a callable (i.e. function) which will perform the actual |
| 156 | encoding of the image data for transport. This callable takes one argument, |
Serhiy Storchaka | e0f0cf4 | 2013-08-19 09:59:18 +0300 | [diff] [blame] | 157 | which is the :class:`MIMEImage` 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 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 165 | *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase` |
| 166 | constructor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 167 | |
| 168 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 169 | .. currentmodule:: email.mime.message |
| 170 | |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 171 | .. class:: MIMEMessage(_msg, _subtype='rfc822') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | |
| 173 | Module: :mod:`email.mime.message` |
| 174 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 175 | A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 176 | :class:`MIMEMessage` class is used to create MIME objects of main type |
| 177 | :mimetype:`message`. *_msg* is used as the payload, and must be an instance |
| 178 | of class :class:`~email.message.Message` (or a subclass thereof), otherwise |
| 179 | a :exc:`TypeError` is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
| 181 | Optional *_subtype* sets the subtype of the message; it defaults to |
| 182 | :mimetype:`rfc822`. |
| 183 | |
| 184 | |
Benjamin Peterson | 75edad0 | 2009-01-01 15:05:06 +0000 | [diff] [blame] | 185 | .. currentmodule:: email.mime.text |
| 186 | |
R David Murray | 8680bcc | 2012-03-22 22:17:51 -0400 | [diff] [blame] | 187 | .. class:: MIMEText(_text, _subtype='plain', _charset=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 188 | |
| 189 | Module: :mod:`email.mime.text` |
| 190 | |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 191 | A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the |
| 192 | :class:`MIMEText` class is used to create MIME objects of major type |
| 193 | :mimetype:`text`. *_text* is the string for the payload. *_subtype* is the |
| 194 | minor type and defaults to :mimetype:`plain`. *_charset* is the character |
Ezio Melotti | 93115e0 | 2013-03-20 13:53:32 +0200 | [diff] [blame] | 195 | set of the text and is passed as an argument to the |
Georg Brandl | 3638e48 | 2009-04-27 16:46:17 +0000 | [diff] [blame] | 196 | :class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults |
R David Murray | 8680bcc | 2012-03-22 22:17:51 -0400 | [diff] [blame] | 197 | to ``us-ascii`` if the string contains only ``ascii`` codepoints, and |
| 198 | ``utf-8`` otherwise. |
R David Murray | 14b0124 | 2013-03-19 18:18:55 -0400 | [diff] [blame] | 199 | |
Ezio Melotti | 93115e0 | 2013-03-20 13:53:32 +0200 | [diff] [blame] | 200 | Unless the *_charset* argument is explicitly set to ``None``, the |
R David Murray | 14b0124 | 2013-03-19 18:18:55 -0400 | [diff] [blame] | 201 | MIMEText object created will have both a :mailheader:`Content-Type` header |
| 202 | with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding` |
| 203 | header. This means that a subsequent ``set_payload`` call will not result |
| 204 | in an encoded payload, even if a charset is passed in the ``set_payload`` |
| 205 | command. You can "reset" this behavior by deleting the |
| 206 | ``Content-Transfer-Encoding`` header, after which a ``set_payload`` call |
| 207 | will automatically encode the new payload (and add a new |
| 208 | :mailheader:`Content-Transfer-Encoding` header). |