1:mod:`email.mime`: Creating email and MIME objects from scratch
2---------------------------------------------------------------
3
4.. module:: email.mime
5   :synopsis: Build MIME messages.
6
7
8Ordinarily, you get a message object structure by passing a file or some text to
9a parser, which parses the text and returns the root message object.  However
10you 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
12existing structure and add new :class:`~email.message.Message` objects, move them
13around, etc.  This makes a very convenient interface for slicing-and-dicing MIME
14messages.
15
16You can create a new object structure by creating :class:`~email.message.Message`
17instances, adding attachments and all the appropriate headers manually.  For MIME
18messages though, the :mod:`email` package provides some convenient subclasses to
19make things easier.
20
21Here 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