19.1.7. email.mime
: Creating email and MIME objects from scratch¶
Source code: Lib/email/mime/
Ordinarily, you get a message object structure by passing a file or some text to
a parser, which parses the text and returns the root message object. However
you can also build a complete message structure from scratch, or even individual
Message
objects by hand. In fact, you can also take an
existing structure and add new Message
objects, move them
around, etc. This makes a very convenient interface for slicing-and-dicing MIME
messages.
You can create a new object structure by creating Message
instances, adding attachments and all the appropriate headers manually. For MIME
messages though, the email
package provides some convenient subclasses to
make things easier.
Here are the classes:
-
class
email.mime.base.
MIMEBase
(_maintype, _subtype, **_params)¶ Module:
email.mime.base
This is the base class for all the MIME-specific subclasses of
Message
. Ordinarily you won’t create instances specifically ofMIMEBase
, although you could.MIMEBase
is provided primarily as a convenient base class for more specific MIME-aware subclasses._maintype is the Content-Type major type (e.g. text or image), and _subtype is the Content-Type minor type (e.g. plain or gif). _params is a parameter key/value dictionary and is passed directly to
Message.add_header
.The
MIMEBase
class always adds a Content-Type header (based on _maintype, _subtype, and _params), and a MIME-Version header (always set to1.0
).
-
class
email.mime.nonmultipart.
MIMENonMultipart
¶ Module:
email.mime.nonmultipart
A subclass of
MIMEBase
, this is an intermediate base class for MIME messages that are not multipart. The primary purpose of this class is to prevent the use of theattach()
method, which only makes sense for multipart messages. Ifattach()
is called, aMultipartConversionError
exception is raised.
-
class
email.mime.multipart.
MIMEMultipart
(_subtype='mixed', boundary=None, _subparts=None, **_params)¶ Module:
email.mime.multipart
A subclass of
MIMEBase
, this is an intermediate base class for MIME messages that are multipart. Optional _subtype defaults to mixed, but can be used to specify the subtype of the message. A Content-Type header of multipart/_subtype will be added to the message object. A MIME-Version header will also be added.Optional boundary is the multipart boundary string. When
None
(the default), the boundary is calculated when needed (for example, when the message is serialized)._subparts is a sequence of initial subparts for the payload. It must be possible to convert this sequence to a list. You can always attach new subparts to the message by using the
Message.attach
method.Additional parameters for the Content-Type header are taken from the keyword arguments, or passed into the _params argument, which is a keyword dictionary.
-
class
email.mime.application.
MIMEApplication
(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, **_params)¶ Module:
email.mime.application
A subclass of
MIMENonMultipart
, theMIMEApplication
class is used to represent MIME message objects of major type application. _data is a string containing the raw byte data. Optional _subtype specifies the MIME subtype and defaults to octet-stream.Optional _encoder is a callable (i.e. function) which will perform the actual encoding of the data for transport. This callable takes one argument, which is the
MIMEApplication
instance. It should useget_payload()
andset_payload()
to change the payload to encoded form. It should also add any Content-Transfer-Encoding or other headers to the message object as necessary. The default encoding is base64. See theemail.encoders
module for a list of the built-in encoders._params are passed straight through to the base class constructor.
-
class
email.mime.audio.
MIMEAudio
(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, **_params)¶ Module:
email.mime.audio
A subclass of
MIMENonMultipart
, theMIMEAudio
class is used to create MIME message objects of major type audio. _audiodata is a string containing the raw audio data. If this data can be decoded by the standard Python modulesndhdr
, then the subtype will be automatically included in the Content-Type header. Otherwise you can explicitly specify the audio subtype via the _subtype argument. If the minor type could not be guessed and _subtype was not given, thenTypeError
is raised.Optional _encoder is a callable (i.e. function) which will perform the actual encoding of the audio data for transport. This callable takes one argument, which is the
MIMEAudio
instance. It should useget_payload()
andset_payload()
to change the payload to encoded form. It should also add any Content-Transfer-Encoding or other headers to the message object as necessary. The default encoding is base64. See theemail.encoders
module for a list of the built-in encoders._params are passed straight through to the base class constructor.
-
class
email.mime.image.
MIMEImage
(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, **_params)¶ Module:
email.mime.image
A subclass of
MIMENonMultipart
, theMIMEImage
class is used to create MIME message objects of major type image. _imagedata is a string containing the raw image data. If this data can be decoded by the standard Python moduleimghdr
, then the subtype will be automatically included in the Content-Type header. Otherwise you can explicitly specify the image subtype via the _subtype argument. If the minor type could not be guessed and _subtype was not given, thenTypeError
is raised.Optional _encoder is a callable (i.e. function) which will perform the actual encoding of the image data for transport. This callable takes one argument, which is the
MIMEImage
instance. It should useget_payload()
andset_payload()
to change the payload to encoded form. It should also add any Content-Transfer-Encoding or other headers to the message object as necessary. The default encoding is base64. See theemail.encoders
module for a list of the built-in encoders._params are passed straight through to the
MIMEBase
constructor.
-
class
email.mime.message.
MIMEMessage
(_msg, _subtype='rfc822')¶ Module:
email.mime.message
A subclass of
MIMENonMultipart
, theMIMEMessage
class is used to create MIME objects of main type message. _msg is used as the payload, and must be an instance of classMessage
(or a subclass thereof), otherwise aTypeError
is raised.Optional _subtype sets the subtype of the message; it defaults to rfc822.
-
class
email.mime.text.
MIMEText
(_text, _subtype='plain', _charset=None)¶ Module:
email.mime.text
A subclass of
MIMENonMultipart
, theMIMEText
class is used to create MIME objects of major type text. _text is the string for the payload. _subtype is the minor type and defaults to plain. _charset is the character set of the text and is passed as an argument to theMIMENonMultipart
constructor; it defaults tous-ascii
if the string contains onlyascii
code points, andutf-8
otherwise. The _charset parameter accepts either a string or aCharset
instance.Unless the _charset argument is explicitly set to
None
, the MIMEText object created will have both a Content-Type header with acharset
parameter, and a Content-Transfer-Encoding header. This means that a subsequentset_payload
call will not result in an encoded payload, even if a charset is passed in theset_payload
command. You can «reset» this behavior by deleting theContent-Transfer-Encoding
header, after which aset_payload
call will automatically encode the new payload (and add a new Content-Transfer-Encoding header).Distinto en la versión 3.5: _charset also accepts
Charset
instances.