email.mime:Creating email and MIME objects from scratch

Source code:Lib/email/mime/

---

This module is part of the legacy (Compat32) email API. Its functionality is partially replaced by thecontentmanagerin the new API, but in certain applications these classes may still be useful, even in non-legacy code.

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 Messageobjects by hand. In fact, you can also take an existing structure and add newMessageobjects, move them around, etc. This makes a very convenient interface for slicing-and-dicing MIME messages.

You can create a new object structure by creatingMessage instances, adding attachments and all the appropriate headers manually. For MIME messages though, theemailpackage provides some convenient subclasses to make things easier.

Here are the classes:

classemail.mime.base.MIMEBase(_maintype,_subtype,*,policy=compat32,**_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.

_maintypeis theContent-Typemajor type (e.g.text orimage), and_subtypeis theContent-Typeminor type (e.g.plainorgif)._paramsis a parameter key/value dictionary and is passed directly toMessage.add_header.

Ifpolicyis specified, (defaults to the compat32policy) it will be passed to Message.

TheMIMEBaseclass always adds aContent-Typeheader (based on_maintype,_subtype,and_params), and a MIME-Versionheader (always set to1.0).

Changed in version 3.6:Addedpolicykeyword-only parameter.

classemail.mime.nonmultipart.MIMENonMultipart

Module:email.mime.nonmultipart

A subclass ofMIMEBase,this is an intermediate base class for MIME messages that are notmultipart.The primary purpose of this class is to prevent the use of the attach()method, which only makes sense for multipartmessages. Ifattach() is called, aMultipartConversionErrorexception is raised.

classemail.mime.multipart.MIMEMultipart(_subtype='mixed',boundary=None,_subparts=None,*,policy=compat32,**_params)

Module:email.mime.multipart

A subclass ofMIMEBase,this is an intermediate base class for MIME messages that aremultipart.Optional_subtype defaults tomixed,but can be used to specify the subtype of the message. AContent-Typeheader ofmultipart/_subtype will be added to the message object. AMIME-Versionheader will also be added.

Optionalboundaryis the multipart boundary string. WhenNone(the default), the boundary is calculated when needed (for example, when the message is serialized).

_subpartsis 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 theMessage.attachmethod.

Optionalpolicyargument defaults tocompat32.

Additional parameters for theContent-Typeheader are taken from the keyword arguments, or passed into the_paramsargument, which is a keyword dictionary.

Changed in version 3.6:Addedpolicykeyword-only parameter.

classemail.mime.application.MIMEApplication(_data,_subtype='octet-stream',_encoder=email.encoders.encode_base64,*,policy=compat32,**_params)

Module:email.mime.application

A subclass ofMIMENonMultipart,the MIMEApplicationclass is used to represent MIME message objects of major typeapplication._datacontains the bytes for the raw application data. Optional_subtypespecifies the MIME subtype and defaults tooctet-stream.

Optional_encoderis a callable (i.e. function) which will perform the actual encoding of the data for transport. This callable takes one argument, which is theMIMEApplicationinstance. It should use get_payload()and set_payload()to change the payload to encoded form. It should also add anyContent-Transfer-Encodingor other headers to the message object as necessary. The default encoding is base64. See the email.encodersmodule for a list of the built-in encoders.

Optionalpolicyargument defaults tocompat32.

_paramsare passed straight through to the base class constructor.

Changed in version 3.6:Addedpolicykeyword-only parameter.

classemail.mime.audio.MIMEAudio(_audiodata,_subtype=None,_encoder=email.encoders.encode_base64,*,policy=compat32,**_params)

Module:email.mime.audio

A subclass ofMIMENonMultipart,the MIMEAudioclass is used to create MIME message objects of major type audio._audiodatacontains the bytes for the raw audio data. If this data can be decoded as au, wav, aiff, or aifc, then the subtype will be automatically included in theContent-Typeheader. Otherwise you can explicitly specify the audio subtype via the_subtype argument. If the minor type could not be guessed and_subtypewas not given, thenTypeErroris raised.

Optional_encoderis a callable (i.e. function) which will perform the actual encoding of the audio data for transport. This callable takes one argument, which is theMIMEAudioinstance. It should use get_payload()and set_payload()to change the payload to encoded form. It should also add anyContent-Transfer-Encodingor other headers to the message object as necessary. The default encoding is base64. See the email.encodersmodule for a list of the built-in encoders.

Optionalpolicyargument defaults tocompat32.

_paramsare passed straight through to the base class constructor.

Changed in version 3.6:Addedpolicykeyword-only parameter.

classemail.mime.image.MIMEImage(_imagedata,_subtype=None,_encoder=email.encoders.encode_base64,*,policy=compat32,**_params)

Module:email.mime.image

A subclass ofMIMENonMultipart,the MIMEImageclass is used to create MIME message objects of major type image._imagedatacontains the bytes for the raw image data. If this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp, and exr attempted), then the subtype will be automatically included in theContent-Typeheader. Otherwise you can explicitly specify the image subtype via the_subtypeargument. If the minor type could not be guessed and_subtypewas not given, then TypeErroris raised.

Optional_encoderis a callable (i.e. function) which will perform the actual encoding of the image data for transport. This callable takes one argument, which is theMIMEImageinstance. It should use get_payload()and set_payload()to change the payload to encoded form. It should also add anyContent-Transfer-Encodingor other headers to the message object as necessary. The default encoding is base64. See the email.encodersmodule for a list of the built-in encoders.

Optionalpolicyargument defaults tocompat32.

_paramsare passed straight through to theMIMEBase constructor.

Changed in version 3.6:Addedpolicykeyword-only parameter.

classemail.mime.message.MIMEMessage(_msg,_subtype='rfc822',*,policy=compat32)

Module:email.mime.message

A subclass ofMIMENonMultipart,the MIMEMessageclass is used to create MIME objects of main type message._msgis used as the payload, and must be an instance of classMessage(or a subclass thereof), otherwise aTypeErroris raised.

Optional_subtypesets the subtype of the message; it defaults to rfc822.

Optionalpolicyargument defaults tocompat32.

Changed in version 3.6:Addedpolicykeyword-only parameter.

classemail.mime.text.MIMEText(_text,_subtype='plain',_charset=None,*,policy=compat32)

Module:email.mime.text

A subclass ofMIMENonMultipart,the MIMETextclass is used to create MIME objects of major type text._textis the string for the payload._subtypeis the minor type and defaults toplain._charsetis the character set of the text and is passed as an argument to the MIMENonMultipartconstructor; it defaults tous-asciiif the string contains onlyasciicode points, and utf-8otherwise. The_charsetparameter accepts either a string or a Charsetinstance.

Unless the_charsetargument is explicitly set toNone,the MIMEText object created will have both aContent-Typeheader with acharsetparameter, and aContent-Transfer-Encoding header. This means that a subsequentset_payloadcall will not result in an encoded payload, even if a charset is passed in theset_payload command. You can “reset” this behavior by deleting the Content-Transfer-Encodingheader, after which aset_payloadcall will automatically encode the new payload (and add a new Content-Transfer-Encodingheader).

Optionalpolicyargument defaults tocompat32.

Changed in version 3.5:_charsetalso acceptsCharsetinstances.

Changed in version 3.6:Addedpolicykeyword-only parameter.