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* 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.. 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* 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.. 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* 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.. currentmodule:: 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.. currentmodule:: 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.
261