• 19.1.1.email.message: Representing an email message
• 19.1.2.email.parser: Parsing email messages
  • 19.1.2.1. FeedParser API
  • 19.1.2.2. Parser class API
  • 19.1.2.3. Additional notes
• 19.1.3.email.generator: Generating MIME documents
• 19.1.4.email.policy: Policy Objects
• 19.1.5.email.headerregistry: Custom Header Objects
• 19.1.6.email.contentmanager: Managing MIME Content
  • 19.1.6.1. Content Manager Instances
• 19.1.7.email.mime: Creating email and MIME objects from scratch
• 19.1.8.email.header: Internationalized headers
• 19.1.9.email.charset: Representing character sets
• 19.1.10.email.encoders: Encoders
• 19.1.11.email.errors: Exception and Defect classes
• 19.1.12.email.utils: Miscellaneous utilities
• 19.1.13.email.iterators: Iterators
• 19.1.14.email: Examples
  • 19.1.14.1. Examples using the Provisional API

See also

Modulesmtplib

SMTP protocol client

Modulenntplib

NNTP protocol client

19.1.15. Package History¶

This table describes the release history of the email package, corresponding tothe version of Python that the package was released with. For purposes of thisdocument, when you see a note about change or added versions, these refer to thePython version the change was made in,not the email package version. Thistable also describes the Python compatibility of each version of the package.

After Version 5.1 (Python 3.2), the email package no longer has a version thatis separate from the Python version. (See theWhat’s New in Python documentsfor the respective Python versions for details on changes.)

Here are the major differences betweenemail version 5.1 andversion 5.0:

• It is once again possible to parse messages containing non-ASCII bytes,and to reproduce such messages if the data containing the non-ASCIIbytes is not modified.
• New functionsmessage_from_bytes() andmessage_from_binary_file(),and new classesBytesFeedParser andBytesParser allow binary message data to be parsedinto model objects.
• Given bytes input to the model,get_payload()will by default decode a message body that has aContent-Transfer-Encoding of8bit using the charsetspecified in the MIME headers and return the resulting string.
• Given bytes input to the model,Generator willconvert message bodies that have aContent-Transfer-Encoding of8bit to instead have a 7bit Content-Transfer-Encoding.
• New classBytesGenerator produces bytesas output, preserving any unchanged non-ASCII data that waspresent in the input used to build the model, including message bodieswith aContent-Transfer-Encoding of 8bit.

Here are the major differences betweenemail version 5.0 and version 4:

• All operations are on unicode strings. Text inputs must be strings,text outputs are strings. Outputs are limited to the ASCII characterset and so can be encoded to ASCII for transmission. Inputs are alsolimited to ASCII; this is an acknowledged limitation of email 5.0 andmeans it can only be used to parse email that is 7bit clean.

Here are the major differences betweenemail version 4 and version 3:

• All modules have been renamed according toPEP 8 standards. For example,the version 3 moduleemail.Message was renamed toemail.message inversion 4.

• A new subpackageemail.mime was added and all the version 3email.MIME* modules were renamed and situated into theemail.mimesubpackage. For example, the version 3 moduleemail.MIMEText was renamedtoemail.mime.text.

  Note that the version 3 names will continue to work until Python 2.6.

• Theemail.mime.application module was added, which contains theMIMEApplication class.

• Methods that were deprecated in version 3 have been removed. These includeGenerator.__call__(),Message.get_type(),Message.get_main_type(),Message.get_subtype().

• Fixes have been added forRFC 2231 support which can change some of thereturn types forMessage.get_paramand friends. Under somecircumstances, values which used to return a 3-tuple now return simple strings(specifically, if all extended parameter segments were unencoded, there is nolanguage and charset designation expected, so the return type is now a simplestring). Also, %-decoding used to be done for both encoded and unencodedsegments; this decoding is now done only for encoded segments.

Here are the major differences betweenemail version 3 and version 2:

• TheFeedParser class was introduced, and theParser class was implemented in terms of theFeedParser. All parsing therefore isnon-strict, and parsing will make a best effort never to raise an exception.Problems found while parsing messages are stored in the message’sdefectattribute.
• All aspects of the API which raisedDeprecationWarnings in version 2have been removed. These include the_encoder argument to theMIMEText constructor, theMessage.add_payload() method, theUtils.dump_address_pair()function, and the functionsUtils.decode() andUtils.encode().
• NewDeprecationWarnings have been added to:Generator.__call__(),Message.get_type(),Message.get_main_type(),Message.get_subtype(), and thestrictargument to theParser class. These are expected tobe removed in future versions.
• Support for Pythons earlier than 2.3 has been removed.

Here are the differences betweenemail version 2 and version 1:

• Theemail.Header andemail.Charset modules have been added.

• The pickle format forMessage instances has changed.Since this was never (and still isn’t) formally defined, this isn’tconsidered a backward incompatibility. However if your application picklesand unpicklesMessage instances, be aware that inemail version 2,Message instances now haveprivate variables_charset and_default_type.

• Several methods in theMessage class have beendeprecated, or their signatures changed. Also, many new methods have beenadded. See the documentation for theMessage classfor details. The changes should be completely backward compatible.

• The object structure has changed in the face ofmessage/rfc822content types. Inemail version 1, such a type would be representedby a scalar payload, i.e. the container message’sis_multipart() returned false,get_payload() was not a list object, but asingleMessage instance.

  This structure was inconsistent with the rest of the package, so the objectrepresentation formessage/rfc822 content types was changed. Inemail version 2, the containerdoes returnTrue fromis_multipart(), andget_payload() returns a list containing a singleMessage item.

  Note that this is one place that backward compatibility could not becompletely maintained. However, if you’re already testing the return type ofget_payload(), you should be fine. You just needto make sure your code doesn’t do aset_payload()with aMessage instance on a container with a contenttype ofmessage/rfc822.

• TheParser constructor’sstrict argument was added,and itsparse() andparsestr() methods grew aheadersonly argument.Thestrict flag was also added to functionsemail.message_from_file()andemail.message_from_string().

• Generator.__call__() is deprecated; useGenerator.flatten instead. TheGenerator class has also grown theclone() method.

• TheDecodedGenerator class in theemail.generator module was added.

• The intermediate base classesMIMENonMultipart andMIMEMultipart have been added, and interposedin the class hierarchy for most of the other MIME-related derived classes.

• The_encoder argument to theMIMEText constructorhas been deprecated. Encoding now happens implicitly based on the_charset argument.

• The following functions in theemail.Utils module have been deprecated:dump_address_pairs(),decode(), andencode(). The followingfunctions have been added to the module:make_msgid(),decode_rfc2231(),encode_rfc2231(), anddecode_params().

• The non-public functionemail.Iterators._structure() was added.

19.1.16. Differences frommimelib¶

Theemail package was originally prototyped as a separate library calledmimelib. Changes have been made so that method namesare more consistent, and some methods or modules have either been added orremoved. The semantics of some of the methods have also changed. For the mostpart, any functionality available inmimelib is still available in theemail package, albeit often in a different way. Backward compatibilitybetween themimelib package and theemail package was not apriority.

Here is a brief description of the differences between themimelib andtheemail packages, along with hints on how to port your applications.

Of course, the most visible difference between the two packages is that thepackage name has been changed toemail. In addition, the top-levelpackage has the following differences:

• messageFromString() has been renamed tomessage_from_string().
• messageFromFile() has been renamed tomessage_from_file().

TheMessage class has the following differences:

• The methodasString() was renamed toas_string().
• The methodismultipart() was renamed tois_multipart().
• Theget_payload() method has grown adecodeoptional argument.
• The methodgetall() was renamed toget_all().
• The methodaddheader() was renamed toadd_header().
• The methodgettype() was renamed toget_type().
• The methodgetmaintype() was renamed toget_main_type().
• The methodgetsubtype() was renamed toget_subtype().
• The methodgetparams() was renamed toget_params(). Also, whereasgetparams()returned a list of strings,get_params() returnsa list of 2-tuples, effectively the key/value pairs of the parameters, spliton the'=' sign.
• The methodgetparam() was renamed toget_param().
• The methodgetcharsets() was renamed toget_charsets().
• The methodgetfilename() was renamed toget_filename().
• The methodgetboundary() was renamed toget_boundary().
• The methodsetboundary() was renamed toset_boundary().
• The methodgetdecodedpayload() was removed. To get similarfunctionality, pass the value 1 to thedecode flag of theget_payload() method.
• The methodgetpayloadastext() was removed. Similar functionality issupported by theDecodedGenerator class in theemail.generator module.
• The methodgetbodyastext() was removed. You can get similarfunctionality by creating an iterator withtyped_subpart_iterator() in theemail.iteratorsmodule.

TheParser class has no differences in its publicinterface. It does have some additional smarts to recognizemessage/delivery-status type messages, which it represents as aMessage instance containing separateMessage subparts for each header block in the deliverystatus notification[1].

TheGenerator class has no differences in its publicinterface. There is a new class in theemail.generator module though,calledDecodedGenerator which provides most of thefunctionality previously available in theMessage.getpayloadastext()method.

The following modules and classes have been changed:

• TheMIMEBase class constructor arguments_majorand_minor have changed to_maintype and_subtype respectively.

• TheImage class/module has been renamed toMIMEImage. The_minorargument has been renamed to_subtype.

• TheText class/module has been renamed toMIMEText. The_minorargument has been renamed to_subtype.

• TheMessageRFC822 class/module has been renamed toMIMEMessage. Notethat an earlier version ofmimelib called this class/moduleRFC822,but that clashed with the Python standard library modulerfc822 on somecase-insensitive file systems.

  Also, theMIMEMessage class now represents anykind of MIME messagewith main typemessage. It takes an optional argument_subtypewhich is used to set the MIME subtype._subtype defaults torfc822.

mimelib provided some utility functions in itsaddress anddate modules. All of these functions have been moved to theemail.utils module.

TheMsgReader class/module has been removed. Its functionality is mostclosely supported in thebody_line_iterator() functionin theemail.iterators module.

Footnotes