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