blob: 9cd94d8926f9d2d861deb891600ac11c8c25574c [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001:mod:`email`: Creating email and MIME objects from scratch
2----------------------------------------------------------
3
4.. module:: email.mime
Georg Brandl48310cd2009-01-03 21:18:54 +00005 :synopsis: Build MIME messages.
Georg Brandl116aa622007-08-15 14:28:22 +00006
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
Georg Brandl3638e482009-04-27 16:46:17 +000011: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.
Georg Brandl116aa622007-08-15 14:28:22 +000015
Georg Brandl3638e482009-04-27 16:46:17 +000016You 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.
Georg Brandl116aa622007-08-15 14:28:22 +000020
21Here are the classes:
22
Benjamin Peterson75edad02009-01-01 15:05:06 +000023.. currentmodule:: email.mime.base
Georg Brandl116aa622007-08-15 14:28:22 +000024
25.. class:: MIMEBase(_maintype, _subtype, **_params)
26
27 Module: :mod:`email.mime.base`
28
Georg Brandl3638e482009-04-27 16:46:17 +000029 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 Brandl116aa622007-08-15 14:28:22 +000034
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 Peterson75edad02009-01-01 15:05:06 +000045.. currentmodule:: email.mime.nonmultipart
46
Georg Brandl116aa622007-08-15 14:28:22 +000047.. class:: MIMENonMultipart()
48
49 Module: :mod:`email.mime.nonmultipart`
50
Georg Brandl3638e482009-04-27 16:46:17 +000051 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 Brandl116aa622007-08-15 14:28:22 +000056
Georg Brandl116aa622007-08-15 14:28:22 +000057
Benjamin Peterson75edad02009-01-01 15:05:06 +000058.. currentmodule:: email.mime.multipart
59
Georg Brandl3f076d82009-05-17 11:28:33 +000060.. class:: MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, **_params)
Georg Brandl116aa622007-08-15 14:28:22 +000061
62 Module: :mod:`email.mime.multipart`
63
Georg Brandl3638e482009-04-27 16:46:17 +000064 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 Brandl116aa622007-08-15 14:28:22 +000070
71 Optional *boundary* is the multipart boundary string. When ``None`` (the
R. David Murray101f2782010-01-10 19:18:27 +000072 default), the boundary is calculated when needed (for example, when the
73 message is serialized).
Georg Brandl116aa622007-08-15 14:28:22 +000074
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 Brandl116aa622007-08-15 14:28:22 +000083
Benjamin Peterson75edad02009-01-01 15:05:06 +000084.. currentmodule:: email.mime.application
85
Georg Brandl3f076d82009-05-17 11:28:33 +000086.. class:: MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, **_params)
Georg Brandl116aa622007-08-15 14:28:22 +000087
88 Module: :mod:`email.mime.application`
89
Georg Brandl3638e482009-04-27 16:46:17 +000090 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 Brandl116aa622007-08-15 14:28:22 +000095
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 Brandl116aa622007-08-15 14:28:22 +0000106
Benjamin Peterson75edad02009-01-01 15:05:06 +0000107.. currentmodule:: email.mime.audio
108
Georg Brandl3f076d82009-05-17 11:28:33 +0000109.. class:: MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, **_params)
Georg Brandl116aa622007-08-15 14:28:22 +0000110
111 Module: :mod:`email.mime.audio`
112
Georg Brandl3638e482009-04-27 16:46:17 +0000113 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 Brandl116aa622007-08-15 14:28:22 +0000121
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 Peterson75edad02009-01-01 15:05:06 +0000133.. currentmodule:: email.mime.image
134
Georg Brandl3f076d82009-05-17 11:28:33 +0000135.. class:: MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, **_params)
Georg Brandl116aa622007-08-15 14:28:22 +0000136
137 Module: :mod:`email.mime.image`
138
Georg Brandl3638e482009-04-27 16:46:17 +0000139 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 Brandl116aa622007-08-15 14:28:22 +0000147
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 Brandl3638e482009-04-27 16:46:17 +0000156 *_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
157 constructor.
Georg Brandl116aa622007-08-15 14:28:22 +0000158
159
Benjamin Peterson75edad02009-01-01 15:05:06 +0000160.. currentmodule:: email.mime.message
161
Georg Brandl3f076d82009-05-17 11:28:33 +0000162.. class:: MIMEMessage(_msg, _subtype='rfc822')
Georg Brandl116aa622007-08-15 14:28:22 +0000163
164 Module: :mod:`email.mime.message`
165
Georg Brandl3638e482009-04-27 16:46:17 +0000166 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 Brandl116aa622007-08-15 14:28:22 +0000171
172 Optional *_subtype* sets the subtype of the message; it defaults to
173 :mimetype:`rfc822`.
174
175
Benjamin Peterson75edad02009-01-01 15:05:06 +0000176.. currentmodule:: email.mime.text
177
Georg Brandl3f076d82009-05-17 11:28:33 +0000178.. class:: MIMEText(_text, _subtype='plain', _charset='us-ascii')
Georg Brandl116aa622007-08-15 14:28:22 +0000179
180 Module: :mod:`email.mime.text`
181
Georg Brandl3638e482009-04-27 16:46:17 +0000182 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
188 to ``us-ascii``. No guessing or encoding is performed on the text data.
Georg Brandl116aa622007-08-15 14:28:22 +0000189