email.message: Representing an email message¶

Source code:Lib/email/message.py

The central class in theemail package is theEmailMessageclass, imported from theemail.message module. It is the base class fortheemail object model.EmailMessage provides the corefunctionality for setting and querying header fields, for accessing messagebodies, and for creating or modifying structured messages.

An email message consists ofheaders and apayload (which is also referredto as thecontent). Headers areRFC 5322 orRFC 6532 style field namesand values, where the field name and value are separated by a colon. The colonis not part of either the field name or the field value. The payload may be asimple text message, or a binary object, or a structured sequence ofsub-messages each with their own set of headers and their own payload. Thelatter type of payload is indicated by the message having a MIME type such asmultipart/* ormessage/rfc822.

The conceptual model provided by anEmailMessage object is that of anordered dictionary of headers coupled with apayload that represents theRFC 5322 body of the message, which might be a list of sub-EmailMessageobjects. In addition to the normal dictionary methods for accessing the headernames and values, there are methods for accessing specialized information fromthe headers (for example the MIME content type), for operating on the payload,for generating a serialized version of the message, and for recursively walkingover the object tree.

TheEmailMessage dictionary-like interface is indexed by the headernames, which must be ASCII values. The values of the dictionary are stringswith some extra methods. Headers are stored and returned in case-preservingform, but field names are matched case-insensitively. The keys are ordered,but unlike a real dict, there can be duplicates. Additional methods areprovided for working with headers that have duplicate keys.

Thepayload is either a string or bytes object, in the case of simple messageobjects, or a list ofEmailMessage objects, for MIME containerdocuments such asmultipart/* andmessage/rfc822message objects.

classemail.message.EmailMessage(policy=default)¶

Ifpolicy is specified use the rules it specifies to update and serializethe representation of the message. Ifpolicy is not set, use thedefault policy, which follows the rules of the emailRFCs except for line endings (instead of the RFC mandated\r\n, it usesthe Python standard\n line endings). For more information see thepolicy documentation.

as_string(unixfrom=False,maxheaderlen=None,policy=None)¶

Return the entire message flattened as a string. When optionalunixfrom is true, the envelope header is included in the returnedstring.unixfrom defaults toFalse. For backward compatibilitywith the baseMessage classmaxheaderlen isaccepted, but defaults toNone, which means that by default the linelength is controlled by themax_line_length of the policy. Thepolicy argument may be used to override the default policy obtainedfrom the message instance. This can be used to control some of theformatting produced by the method, since the specifiedpolicy will bepassed to theGenerator.

Flattening the message may trigger changes to theEmailMessageif defaults need to be filled in to complete the transformation to astring (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not be themost useful way to serialize messages in your application, especially ifyou are dealing with multiple messages. Seeemail.generator.Generator for a more flexible API forserializing messages. Note also that this method is restricted toproducing messages serialized as “7 bit clean” whenutf8 isFalse, which is the default.

Changed in version 3.6:the default behavior whenmaxheaderlenis not specified was changed from defaulting to 0 to defaultingto the value ofmax_line_length from the policy.

__str__()¶

Equivalent toas_string(policy=self.policy.clone(utf8=True)). Allowsstr(msg) to produce a string containing the serialized message in areadable format.

Changed in version 3.4:the method was changed to useutf8=True,thus producing anRFC 6531-like message representation, instead ofbeing a direct alias foras_string().

as_bytes(unixfrom=False,policy=None)¶

Return the entire message flattened as a bytes object. When optionalunixfrom is true, the envelope header is included in the returnedstring.unixfrom defaults toFalse. Thepolicy argument may beused to override the default policy obtained from the message instance.This can be used to control some of the formatting produced by themethod, since the specifiedpolicy will be passed to theBytesGenerator.

Flattening the message may trigger changes to theEmailMessageif defaults need to be filled in to complete the transformation to astring (for example, MIME boundaries may be generated or modified).

Note that this method is provided as a convenience and may not be themost useful way to serialize messages in your application, especially ifyou are dealing with multiple messages. Seeemail.generator.BytesGenerator for a more flexible API forserializing messages.

__bytes__()¶

Equivalent toas_bytes(). Allowsbytes(msg) to produce abytes object containing the serialized message.

is_multipart()¶

ReturnTrue if the message’s payload is a list ofsub-EmailMessage objects, otherwise returnFalse. Whenis_multipart() returnsFalse, the payload should be a stringobject (which might be a CTE encoded binary payload). Note thatis_multipart() returningTrue does not necessarily mean that“msg.get_content_maintype() == ‘multipart’” will return theTrue.For example,is_multipart will returnTrue when theEmailMessage is of typemessage/rfc822.

set_unixfrom(unixfrom)¶

Set the message’s envelope header tounixfrom, which should be astring. (SeemboxMessage for a brief description ofthis header.)

get_unixfrom()¶

Return the message’s envelope header. Defaults toNone if theenvelope header was never set.

The following methods implement the mapping-like interface for accessing themessage’s headers. Note that there are some semantic differencesbetween these methods and a normal mapping (i.e. dictionary) interface. Forexample, in a dictionary there are no duplicate keys, but here there may beduplicate message headers. Also, in dictionaries there is no guaranteedorder to the keys returned bykeys(), but in anEmailMessageobject, headers are always returned in the order they appeared in theoriginal message, or in which they were added to the message later. Anyheader deleted and then re-added is always appended to the end of theheader list.

These semantic differences are intentional and are biased towardconvenience in the most common use cases.

Note that in all cases, any envelope header present in the message is notincluded in the mapping interface.

__len__()¶

Return the total number of headers, including duplicates.

__contains__(name)¶

ReturnTrue if the message object has a field namedname. Matching isdone without regard to case andname does not include the trailingcolon. Used for thein operator. For example:

if'message-id'inmyMessage:print('Message-ID:',myMessage['message-id'])

__getitem__(name)¶

Return the value of the named header field.name does not include thecolon field separator. If the header is missing,None is returned; aKeyError is never raised.

Note that if the named field appears more than once in the message’sheaders, exactly which of those field values will be returned isundefined. Use theget_all() method to get the values of all theextant headers namedname.

Using the standard (non-compat32) policies, the returned value is aninstance of a subclass ofemail.headerregistry.BaseHeader.

__setitem__(name,val)¶

Add a header to the message with field namename and valueval. Thefield is appended to the end of the message’s existing headers.

Note that this doesnot overwrite or delete any existing header with the samename. If you want to ensure that the new header is the only one present in themessage with field namename, delete the field first, e.g.:

delmsg['subject']msg['subject']='Python roolz!'

If thepolicy defines certain headers to be unique (as the standardpolicies do), this method may raise aValueError when an attemptis made to assign a value to such a header when one already exists. Thisbehavior is intentional for consistency’s sake, but do not depend on itas we may choose to make such assignments do an automatic deletion of theexisting header in the future.

__delitem__(name)¶

Delete all occurrences of the field with namename from the message’sheaders. No exception is raised if the named field isn’t present in theheaders.

keys()¶

Return a list of all the message’s header field names.

values()¶

Return a list of all the message’s field values.

items()¶

Return a list of 2-tuples containing all the message’s field headers andvalues.

get(name,failobj=None)¶

Return the value of the named header field. This is identical to__getitem__() except that optionalfailobj is returned if thenamed header is missing (failobj defaults toNone).

Here are some additional useful header related methods:

get_all(name,failobj=None)¶

Return a list of all the values for the field namedname. If there areno such named headers in the message,failobj is returned (defaults toNone).

add_header(_name,_value,**_params)¶

Extended header setting. This method is similar to__setitem__()except that additional header parameters can be provided as keywordarguments._name is the header field to add and_value is theprimary value for the header.

For each item in the keyword argument dictionary_params, the key istaken as the parameter name, with underscores converted to dashes (sincedashes are illegal in Python identifiers). Normally, the parameter willbe added askey="value" unless the value isNone, in which caseonly the key will be added.

If the value contains non-ASCII characters, the charset and language maybe explicitly controlled by specifying the value as a three tuple in theformat(CHARSET,LANGUAGE,VALUE), whereCHARSET is a stringnaming the charset to be used to encode the value,LANGUAGE canusually be set toNone or the empty string (seeRFC 2231 for otherpossibilities), andVALUE is the string value containing non-ASCIIcode points. If a three tuple is not passed and the value containsnon-ASCII characters, it is automatically encoded inRFC 2231 formatusing aCHARSET ofutf-8 and aLANGUAGE ofNone.

Here is an example:

msg.add_header('Content-Disposition','attachment',filename='bud.gif')

This will add a header that looks like

Content-Disposition:attachment;filename="bud.gif"

An example of the extended interface with non-ASCII characters:

msg.add_header('Content-Disposition','attachment',filename=('iso-8859-1','','Fußballer.ppt'))

replace_header(_name,_value)¶

Replace a header. Replace the first header found in the message thatmatches_name, retaining header order and field name case of theoriginal header. If no matching header is found, raise aKeyError.

get_content_type()¶

Return the message’s content type, coerced to lower case of the formmaintype/subtype. If there is noContent-Typeheader in the message return the value returned byget_default_type(). If theContent-Type header isinvalid, returntext/plain.

(According toRFC 2045, messages always have a default type,get_content_type() will always return a value.RFC 2045 definesa message’s default type to betext/plain unless it appearsinside amultipart/digest container, in which case it wouldbemessage/rfc822. If theContent-Type headerhas an invalid type specification,RFC 2045 mandates that the defaulttype betext/plain.)

get_content_maintype()¶

Return the message’s main content type. This is themaintypepart of the string returned byget_content_type().

get_content_subtype()¶

Return the message’s sub-content type. This is thesubtypepart of the string returned byget_content_type().

get_default_type()¶

Return the default content type. Most messages have a default contenttype oftext/plain, except for messages that are subparts ofmultipart/digest containers. Such subparts have a defaultcontent type ofmessage/rfc822.

set_default_type(ctype)¶

Set the default content type.ctype should either betext/plain ormessage/rfc822, although this isnot enforced. The default content type is not stored in theContent-Type header, so it only affects the return value oftheget_content_type methods when noContent-Typeheader is present in the message.

set_param(param,value,header='Content-Type',requote=True,charset=None,language='',replace=False)¶

Set a parameter in theContent-Type header. If theparameter already exists in the header, replace its value withvalue.Whenheader isContent-Type (the default) and the header does notyet exist in the message, add it, set its value totext/plain, and append the new parameter value. Optionalheader specifies an alternative header toContent-Type.

If the value contains non-ASCII characters, the charset and language maybe explicitly specified using the optionalcharset andlanguageparameters. Optionallanguage specifies theRFC 2231 language,defaulting to the empty string. Bothcharset andlanguage should bestrings. The default is to use theutf8charset andNone forthelanguage.

Ifreplace isFalse (the default) the header is moved to theend of the list of headers. Ifreplace isTrue, the headerwill be updated in place.

Use of therequote parameter withEmailMessage objects isdeprecated.

Note that existing parameter values of headers may be accessed throughtheparams attribute of theheader value (for example,msg['Content-Type'].params['charset']).

Changed in version 3.4:replace keyword was added.

del_param(param,header='content-type',requote=True)¶

Remove the given parameter completely from theContent-Typeheader. The header will be re-written in place without the parameter orits value. Optionalheader specifies an alternative toContent-Type.

Use of therequote parameter withEmailMessage objects isdeprecated.

get_filename(failobj=None)¶

Return the value of thefilename parameter of theContent-Disposition header of the message. If the headerdoes not have afilename parameter, this method falls back to lookingfor thename parameter on theContent-Type header. Ifneither is found, or the header is missing, thenfailobj is returned.The returned string will always be unquoted as peremail.utils.unquote().

get_boundary(failobj=None)¶

Return the value of theboundary parameter of theContent-Type header of the message, orfailobj if eitherthe header is missing, or has noboundary parameter. The returnedstring will always be unquoted as peremail.utils.unquote().

set_boundary(boundary)¶

Set theboundary parameter of theContent-Type header toboundary.set_boundary() will always quoteboundary ifnecessary. AHeaderParseError is raised if themessage object has noContent-Type header.

Note that using this method is subtly different from deleting the oldContent-Type header and adding a new one with the newboundary viaadd_header(), becauseset_boundary() preservesthe order of theContent-Type header in the list ofheaders.

get_content_charset(failobj=None)¶

Return thecharset parameter of theContent-Type header,coerced to lower case. If there is noContent-Type header, or ifthat header has nocharset parameter,failobj is returned.

get_charsets(failobj=None)¶

Return a list containing the character set names in the message. If themessage is amultipart, then the list will contain one elementfor each subpart in the payload, otherwise, it will be a list of length 1.

Each item in the list will be a string which is the value of thecharset parameter in theContent-Type header for therepresented subpart. If the subpart has noContent-Typeheader, nocharset parameter, or is not of thetext mainMIME type, then that item in the returned list will befailobj.

is_attachment()¶

ReturnTrue if there is aContent-Disposition headerand its (case insensitive) value isattachment,False otherwise.

Changed in version 3.4.2:is_attachment is now a method instead of a property, for consistencywithis_multipart().

get_content_disposition()¶

Return the lowercased value (without parameters) of the message’sContent-Disposition header if it has one, orNone. Thepossible values for this method areinline,attachment orNoneif the message followsRFC 2183.

Added in version 3.5.

The following methods relate to interrogating and manipulating the content(payload) of the message.

walk()¶

Thewalk() method is an all-purpose generator which can be used toiterate over all the parts and subparts of a message object tree, indepth-first traversal order. You will typically usewalk() as theiterator in afor loop; each iteration returns the next subpart.

Here’s an example that prints the MIME type of every part of a multipartmessage structure:

>>>forpartinmsg.walk():...print(part.get_content_type())multipart/reporttext/plainmessage/delivery-statustext/plaintext/plainmessage/rfc822text/plain

walk iterates over the subparts of any part whereis_multipart() returnsTrue, even thoughmsg.get_content_maintype()=='multipart' may returnFalse. Wecan see this in our example by making use of the_structure debughelper function:

>>>fromemail.iteratorsimport_structure>>>forpartinmsg.walk():...print(part.get_content_maintype()=='multipart',...part.is_multipart())True TrueFalse FalseFalse TrueFalse FalseFalse FalseFalse TrueFalse False>>>_structure(msg)multipart/report    text/plain    message/delivery-status        text/plain        text/plain    message/rfc822        text/plain

Here themessage parts are notmultiparts, but they do containsubparts.is_multipart() returnsTrue andwalk descendsinto the subparts.

get_body(preferencelist=('related','html','plain'))¶

Return the MIME part that is the best candidate to be the “body” of themessage.

preferencelist must be a sequence of strings from the setrelated,html, andplain, and indicates the order of preference for thecontent type of the part returned.

Start looking for candidate matches with the object on which theget_body method is called.

Ifrelated is not included inpreferencelist, consider the rootpart (or subpart of the root part) of any related encountered as acandidate if the (sub-)part matches a preference.

When encountering amultipart/related, check thestart parameterand if a part with a matchingContent-ID is found, consideronly it when looking for candidate matches. Otherwise consider only thefirst (default root) part of themultipart/related.

If a part has aContent-Disposition header, only considerthe part a candidate match if the value of the header isinline.

If none of the candidates matches any of the preferences inpreferencelist, returnNone.

Notes: (1) For most applications the onlypreferencelist combinationsthat really make sense are('plain',),('html','plain'), and thedefault('related','html','plain'). (2) Because matching startswith the object on whichget_body is called, callingget_body onamultipart/related will return the object itself unlesspreferencelist has a non-default value. (3) Messages (or message parts)that do not specify aContent-Type or whoseContent-Type header is invalid will be treated as if theyare of typetext/plain, which may occasionally causeget_body toreturn unexpected results.

iter_attachments()¶

Return an iterator over all of the immediate sub-parts of the messagethat are not candidate “body” parts. That is, skip the first occurrenceof each oftext/plain,text/html,multipart/related, ormultipart/alternative (unless they are explicitly marked asattachments viaContent-Disposition: attachment), andreturn all remaining parts. When applied directly to amultipart/related, return an iterator over the all the related partsexcept the root part (ie: the part pointed to by thestart parameter,or the first part if there is nostart parameter or thestartparameter doesn’t match theContent-ID of any of theparts). When applied directly to amultipart/alternative or anon-multipart, return an empty iterator.

iter_parts()¶

Return an iterator over all of the immediate sub-parts of the message,which will be empty for a non-multipart. (See alsowalk().)

get_content(*args,content_manager=None,**kw)¶

Call theget_content() methodof thecontent_manager, passing self as the message object, and passingalong any other arguments or keywords as additional arguments. Ifcontent_manager is not specified, use thecontent_manager specifiedby the currentpolicy.

set_content(*args,content_manager=None,**kw)¶

Call theset_content() methodof thecontent_manager, passing self as the message object, and passingalong any other arguments or keywords as additional arguments. Ifcontent_manager is not specified, use thecontent_manager specifiedby the currentpolicy.

make_related(boundary=None)¶

Convert a non-multipart message into amultipart/related message,moving any existingContent- headers and payload into a(new) first part of themultipart. Ifboundary is specified, useit as the boundary string in the multipart, otherwise leave the boundaryto be automatically created when it is needed (for example, when themessage is serialized).

make_alternative(boundary=None)¶

Convert a non-multipart or amultipart/related into amultipart/alternative, moving any existingContent-headers and payload into a (new) first part of themultipart. Ifboundary is specified, use it as the boundary string in the multipart,otherwise leave the boundary to be automatically created when it isneeded (for example, when the message is serialized).

make_mixed(boundary=None)¶

Convert a non-multipart, amultipart/related, or amultipart-alternative into amultipart/mixed, moving any existingContent- headers and payload into a (new) first part of themultipart. Ifboundary is specified, use it as the boundary stringin the multipart, otherwise leave the boundary to be automaticallycreated when it is needed (for example, when the message is serialized).

add_related(*args,content_manager=None,**kw)¶

If the message is amultipart/related, create a new messageobject, pass all of the arguments to itsset_content() method,andattach() it to themultipart. Ifthe message is a non-multipart, callmake_related() and thenproceed as above. If the message is any other type ofmultipart,raise aTypeError. Ifcontent_manager is not specified, usethecontent_manager specified by the currentpolicy.If the added part has noContent-Disposition header,add one with the valueinline.

add_alternative(*args,content_manager=None,**kw)¶

If the message is amultipart/alternative, create a new messageobject, pass all of the arguments to itsset_content() method, andattach() it to themultipart. If themessage is a non-multipart ormultipart/related, callmake_alternative() and then proceed as above. If the message isany other type ofmultipart, raise aTypeError. Ifcontent_manager is not specified, use thecontent_manager specifiedby the currentpolicy.

add_attachment(*args,content_manager=None,**kw)¶

If the message is amultipart/mixed, create a new message object,pass all of the arguments to itsset_content() method, andattach() it to themultipart. If themessage is a non-multipart,multipart/related, ormultipart/alternative, callmake_mixed() and then proceed asabove. Ifcontent_manager is not specified, use thecontent_managerspecified by the currentpolicy. If the added parthas noContent-Disposition header, add one with the valueattachment. This method can be used both for explicit attachments(Content-Disposition: attachment) andinline attachments(Content-Disposition: inline), by passing appropriateoptions to thecontent_manager.

clear()¶

Remove the payload and all of the headers.

clear_content()¶

Remove the payload and all of the!Content- headers, leavingall other headers intact and in their original order.

EmailMessage objects have the following instance attributes:

preamble¶

The format of a MIME document allows for some text between the blank linefollowing the headers, and the first multipart boundary string. Normally,this text is never visible in a MIME-aware mail reader because it fallsoutside the standard MIME armor. However, when viewing the raw text ofthe message, or when viewing the message in a non-MIME aware reader, thistext can become visible.

Thepreamble attribute contains this leading extra-armor text for MIMEdocuments. When theParser discovers some textafter the headers but before the first boundary string, it assigns thistext to the message’spreamble attribute. When theGenerator is writing out the plain textrepresentation of a MIME message, and it finds themessage has apreamble attribute, it will write this text in the areabetween the headers and the first boundary. Seeemail.parser andemail.generator for details.

Note that if the message object has no preamble, thepreamble attributewill beNone.

epilogue¶

Theepilogue attribute acts the same way as thepreamble attribute,except that it contains text that appears between the last boundary andthe end of the message. As with thepreamble,if there is no epilog text this attribute will beNone.

defects¶

Thedefects attribute contains a list of all the problems found whenparsing this message. Seeemail.errors for a detailed descriptionof the possible parsing defects.

classemail.message.MIMEPart(policy=default)¶

This class represents a subpart of a MIME message. It is identical toEmailMessage, except that noMIME-Version headers areadded whenset_content() is called, since sub-parts donot need their ownMIME-Version headers.

Footnotes

Originally added in 3.4 as aprovisional module. Docs for legacy message class moved toemail.message.Message: Representing an email message using the compat32 API.