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