n | .. % Copyright (C) 2001-2006 Python Software Foundation |
| .. % Author: barry@python.org (Barry Warsaw) |
| |
| |
| :mod:`email` --- An email and MIME handling package |
| =================================================== |
| |
| .. module:: email |
| :synopsis: Package supporting the parsing, manipulating, and generating email messages, |
| including MIME documents. |
| .. moduleauthor:: Barry A. Warsaw <barry@python.org> |
| .. sectionauthor:: Barry A. Warsaw <barry@python.org> |
n | .. Copyright (C) 2001-2007 Python Software Foundation |
| |
| |
| .. versionadded:: 2.2 |
| |
| The :mod:`email` package is a library for managing email messages, including |
| MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the |
| functionality in several older standard modules such as :mod:`rfc822`, |
| :mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as |
| above. |
| |
| Also included are detailed specifications of all the classes and modules that |
| the :mod:`email` package provides, the exception classes you might encounter |
| while using the :mod:`email` package, some auxiliary utilities, and a few |
| examples. For users of the older :mod:`mimelib` package, or previous versions |
| of the :mod:`email` package, a section on differences and porting is provided. |
| |
n | Contents of the :mod:`email` package documentation: |
| |
| .. toctree:: |
| |
| email.message.rst |
| email.parser.rst |
| email.generator.rst |
| email.mime.rst |
| email.header.rst |
| email.charset.rst |
| email.encoders.rst |
| email.errors.rst |
| email.util.rst |
| email.iterators.rst |
| email-examples.rst |
| |
| |
| .. seealso:: |
| |
| Module :mod:`smtplib` |
| SMTP protocol client |
| |
| Module :mod:`nntplib` |
| NNTP protocol client |
n | |
| |
| Representing an email message |
| ----------------------------- |
| |
| |
| .. include:: email.message.rst |
| |
| |
| Parsing email messages |
| ---------------------- |
| |
| |
| .. include:: email.parser.rst |
| |
| |
| Generating MIME documents |
| ------------------------- |
| |
| |
| .. include:: email.generator.rst |
| |
| |
| Creating email and MIME objects from scratch |
| -------------------------------------------- |
| |
| |
| .. include:: email.mime.rst |
| |
| |
| Internationalized headers |
| ------------------------- |
| |
| |
| .. include:: email.header.rst |
| |
| |
| Representing character sets |
| --------------------------- |
| |
| |
| .. include:: email.charset.rst |
| |
| |
| Encoders |
| -------- |
| |
| |
| .. include:: email.encoders.rst |
| |
| |
| Exception and Defect classes |
| ---------------------------- |
| |
| |
| .. include:: email.errors.rst |
| |
| |
| Miscellaneous utilities |
| ----------------------- |
| |
| |
| .. include:: email.util.rst |
| |
| |
| Iterators |
| --------- |
| |
| |
| .. include:: email.iterators.rst |
| |
| |
| .. _email-pkg-history: |
| |
| Package History |
| --------------- |
| |
| This table describes the release history of the email package, corresponding to |
| the version of Python that the package was released with. For purposes of this |
| document, when you see a note about change or added versions, these refer to the |
n | Python version the change was made it, *not* the email package version. This |
n | Python version the change was made in, *not* the email package version. This |
| table also describes the Python compatibility of each version of the package. |
| |
| +---------------+------------------------------+-----------------------+ |
| | email version | distributed with | compatible with | |
| +===============+==============================+=======================+ |
| | :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* | |
| +---------------+------------------------------+-----------------------+ |
| | :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 | |
| :mod:`mimelib` provided some utility functions in its :mod:`address` and |
| :mod:`date` modules. All of these functions have been moved to the |
| :mod:`email.utils` module. |
| |
| The ``MsgReader`` class/module has been removed. Its functionality is most |
| closely supported in the :func:`body_line_iterator` function in the |
| :mod:`email.iterators` module. |
| |
n | |
| Examples |
| -------- |
| |
| Here are a few examples of how to use the :mod:`email` package to read, write, |
| and send simple email messages, as well as more complex MIME messages. |
| |
| First, let's see how to create and send a simple text message: |
| |
| |
| .. include:: ../includes/email-simple.py |
| :literal: |
| |
| Here's an example of how to send a MIME message containing a bunch of family |
| pictures that may be residing in a directory: |
| |
| |
| .. include:: ../includes/email-mime.py |
| :literal: |
| |
| Here's an example of how to send the entire contents of a directory as an email |
| message: [#]_ |
| |
| |
| .. include:: ../includes/email-dir.py |
| :literal: |
| |
| And finally, here's an example of how to unpack a MIME message like the one |
| above, into a directory of files: |
| |
| |
| .. include:: ../includes/email-unpack.py |
| :literal: |
| |
| .. rubric:: Footnotes |
| |
| .. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`. |
t | |
| .. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples. |
| |