17db96d56Sopenharmony_ci:mod:`email.message`: Representing an email message
27db96d56Sopenharmony_ci---------------------------------------------------
37db96d56Sopenharmony_ci
47db96d56Sopenharmony_ci.. module:: email.message
57db96d56Sopenharmony_ci   :synopsis: The base class representing email messages.
67db96d56Sopenharmony_ci.. moduleauthor:: R. David Murray <rdmurray@bitdance.com>
77db96d56Sopenharmony_ci.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>,
87db96d56Sopenharmony_ci                   Barry A. Warsaw <barry@python.org>
97db96d56Sopenharmony_ci
107db96d56Sopenharmony_ci**Source code:** :source:`Lib/email/message.py`
117db96d56Sopenharmony_ci
127db96d56Sopenharmony_ci--------------
137db96d56Sopenharmony_ci
147db96d56Sopenharmony_ci.. versionadded:: 3.6 [1]_
157db96d56Sopenharmony_ci
167db96d56Sopenharmony_ciThe central class in the :mod:`email` package is the :class:`EmailMessage`
177db96d56Sopenharmony_ciclass, imported from the :mod:`email.message` module.  It is the base class for
187db96d56Sopenharmony_cithe :mod:`email` object model.  :class:`EmailMessage` provides the core
197db96d56Sopenharmony_cifunctionality for setting and querying header fields, for accessing message
207db96d56Sopenharmony_cibodies, and for creating or modifying structured messages.
217db96d56Sopenharmony_ci
227db96d56Sopenharmony_ciAn email message consists of *headers* and a *payload* (which is also referred
237db96d56Sopenharmony_cito as the *content*).  Headers are :rfc:`5322` or :rfc:`6532` style field names
247db96d56Sopenharmony_ciand values, where the field name and value are separated by a colon.  The colon
257db96d56Sopenharmony_ciis not part of either the field name or the field value.  The payload may be a
267db96d56Sopenharmony_cisimple text message, or a binary object, or a structured sequence of
277db96d56Sopenharmony_cisub-messages each with their own set of headers and their own payload.  The
287db96d56Sopenharmony_cilatter type of payload is indicated by the message having a MIME type such as
297db96d56Sopenharmony_ci:mimetype:`multipart/\*` or :mimetype:`message/rfc822`.
307db96d56Sopenharmony_ci
317db96d56Sopenharmony_ciThe conceptual model provided by an :class:`EmailMessage` object is that of an
327db96d56Sopenharmony_ciordered dictionary of headers coupled with a *payload* that represents the
337db96d56Sopenharmony_ci:rfc:`5322` body of the message, which might be a list of sub-``EmailMessage``
347db96d56Sopenharmony_ciobjects.  In addition to the normal dictionary methods for accessing the header
357db96d56Sopenharmony_cinames and values, there are methods for accessing specialized information from
367db96d56Sopenharmony_cithe headers (for example the MIME content type), for operating on the payload,
377db96d56Sopenharmony_cifor generating a serialized version of the message, and for recursively walking
387db96d56Sopenharmony_ciover the object tree.
397db96d56Sopenharmony_ci
407db96d56Sopenharmony_ciThe :class:`EmailMessage` dictionary-like interface is indexed by the header
417db96d56Sopenharmony_cinames, which must be ASCII values.  The values of the dictionary are strings
427db96d56Sopenharmony_ciwith some extra methods.  Headers are stored and returned in case-preserving
437db96d56Sopenharmony_ciform, but field names are matched case-insensitively.  Unlike a real dict,
447db96d56Sopenharmony_cithere is an ordering to the keys, and there can be duplicate keys.  Additional
457db96d56Sopenharmony_cimethods are provided for working with headers that have duplicate keys.
467db96d56Sopenharmony_ci
477db96d56Sopenharmony_ciThe *payload* is either a string or bytes object, in the case of simple message
487db96d56Sopenharmony_ciobjects, or a list of :class:`EmailMessage` objects, for MIME container
497db96d56Sopenharmony_cidocuments such as :mimetype:`multipart/\*` and :mimetype:`message/rfc822`
507db96d56Sopenharmony_cimessage objects.
517db96d56Sopenharmony_ci
527db96d56Sopenharmony_ci
537db96d56Sopenharmony_ci.. class:: EmailMessage(policy=default)
547db96d56Sopenharmony_ci
557db96d56Sopenharmony_ci   If *policy* is specified use the rules it specifies to update and serialize
567db96d56Sopenharmony_ci   the representation of the message.  If *policy* is not set, use the
577db96d56Sopenharmony_ci   :class:`~email.policy.default` policy, which follows the rules of the email
587db96d56Sopenharmony_ci   RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses
597db96d56Sopenharmony_ci   the Python standard ``\n`` line endings).  For more information see the
607db96d56Sopenharmony_ci   :mod:`~email.policy` documentation.
617db96d56Sopenharmony_ci
627db96d56Sopenharmony_ci   .. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None)
637db96d56Sopenharmony_ci
647db96d56Sopenharmony_ci      Return the entire message flattened as a string.  When optional
657db96d56Sopenharmony_ci      *unixfrom* is true, the envelope header is included in the returned
667db96d56Sopenharmony_ci      string.  *unixfrom* defaults to ``False``.  For backward compatibility
677db96d56Sopenharmony_ci      with the base :class:`~email.message.Message` class *maxheaderlen* is
687db96d56Sopenharmony_ci      accepted, but defaults to ``None``, which means that by default the line
697db96d56Sopenharmony_ci      length is controlled by the
707db96d56Sopenharmony_ci      :attr:`~email.policy.EmailPolicy.max_line_length` of the policy.  The
717db96d56Sopenharmony_ci      *policy* argument may be used to override the default policy obtained
727db96d56Sopenharmony_ci      from the message instance.  This can be used to control some of the
737db96d56Sopenharmony_ci      formatting produced by the method, since the specified *policy* will be
747db96d56Sopenharmony_ci      passed to the :class:`~email.generator.Generator`.
757db96d56Sopenharmony_ci
767db96d56Sopenharmony_ci      Flattening the message may trigger changes to the :class:`EmailMessage`
777db96d56Sopenharmony_ci      if defaults need to be filled in to complete the transformation to a
787db96d56Sopenharmony_ci      string (for example, MIME boundaries may be generated or modified).
797db96d56Sopenharmony_ci
807db96d56Sopenharmony_ci      Note that this method is provided as a convenience and may not be the
817db96d56Sopenharmony_ci      most useful way to serialize messages in your application, especially if
827db96d56Sopenharmony_ci      you are dealing with multiple messages.  See
837db96d56Sopenharmony_ci      :class:`email.generator.Generator` for a more flexible API for
847db96d56Sopenharmony_ci      serializing messages.  Note also that this method is restricted to
857db96d56Sopenharmony_ci      producing messages serialized as "7 bit clean" when
867db96d56Sopenharmony_ci      :attr:`~email.policy.EmailPolicy.utf8` is ``False``, which is the default.
877db96d56Sopenharmony_ci
887db96d56Sopenharmony_ci      .. versionchanged:: 3.6 the default behavior when *maxheaderlen*
897db96d56Sopenharmony_ci         is not specified was changed from defaulting to 0 to defaulting
907db96d56Sopenharmony_ci         to the value of *max_line_length* from the policy.
917db96d56Sopenharmony_ci
927db96d56Sopenharmony_ci
937db96d56Sopenharmony_ci   .. method:: __str__()
947db96d56Sopenharmony_ci
957db96d56Sopenharmony_ci      Equivalent to ``as_string(policy=self.policy.clone(utf8=True))``.  Allows
967db96d56Sopenharmony_ci      ``str(msg)`` to produce a string containing the serialized message in a
977db96d56Sopenharmony_ci      readable format.
987db96d56Sopenharmony_ci
997db96d56Sopenharmony_ci      .. versionchanged:: 3.4 the method was changed to use ``utf8=True``,
1007db96d56Sopenharmony_ci         thus producing an :rfc:`6531`-like message representation, instead of
1017db96d56Sopenharmony_ci         being a direct alias for :meth:`as_string`.
1027db96d56Sopenharmony_ci
1037db96d56Sopenharmony_ci
1047db96d56Sopenharmony_ci   .. method:: as_bytes(unixfrom=False, policy=None)
1057db96d56Sopenharmony_ci
1067db96d56Sopenharmony_ci      Return the entire message flattened as a bytes object.  When optional
1077db96d56Sopenharmony_ci      *unixfrom* is true, the envelope header is included in the returned
1087db96d56Sopenharmony_ci      string.  *unixfrom* defaults to ``False``.  The *policy* argument may be
1097db96d56Sopenharmony_ci      used to override the default policy obtained from the message instance.
1107db96d56Sopenharmony_ci      This can be used to control some of the formatting produced by the
1117db96d56Sopenharmony_ci      method, since the specified *policy* will be passed to the
1127db96d56Sopenharmony_ci      :class:`~email.generator.BytesGenerator`.
1137db96d56Sopenharmony_ci
1147db96d56Sopenharmony_ci      Flattening the message may trigger changes to the :class:`EmailMessage`
1157db96d56Sopenharmony_ci      if defaults need to be filled in to complete the transformation to a
1167db96d56Sopenharmony_ci      string (for example, MIME boundaries may be generated or modified).
1177db96d56Sopenharmony_ci
1187db96d56Sopenharmony_ci      Note that this method is provided as a convenience and may not be the
1197db96d56Sopenharmony_ci      most useful way to serialize messages in your application, especially if
1207db96d56Sopenharmony_ci      you are dealing with multiple messages.  See
1217db96d56Sopenharmony_ci      :class:`email.generator.BytesGenerator` for a more flexible API for
1227db96d56Sopenharmony_ci      serializing messages.
1237db96d56Sopenharmony_ci
1247db96d56Sopenharmony_ci
1257db96d56Sopenharmony_ci   .. method:: __bytes__()
1267db96d56Sopenharmony_ci
1277db96d56Sopenharmony_ci      Equivalent to :meth:`.as_bytes()`.  Allows ``bytes(msg)`` to produce a
1287db96d56Sopenharmony_ci      bytes object containing the serialized message.
1297db96d56Sopenharmony_ci
1307db96d56Sopenharmony_ci
1317db96d56Sopenharmony_ci   .. method:: is_multipart()
1327db96d56Sopenharmony_ci
1337db96d56Sopenharmony_ci      Return ``True`` if the message's payload is a list of
1347db96d56Sopenharmony_ci      sub-\ :class:`EmailMessage` objects, otherwise return ``False``.  When
1357db96d56Sopenharmony_ci      :meth:`is_multipart` returns ``False``, the payload should be a string
1367db96d56Sopenharmony_ci      object (which might be a CTE encoded binary payload).  Note that
1377db96d56Sopenharmony_ci      :meth:`is_multipart` returning ``True`` does not necessarily mean that
1387db96d56Sopenharmony_ci      "msg.get_content_maintype() == 'multipart'" will return the ``True``.
1397db96d56Sopenharmony_ci      For example, ``is_multipart`` will return ``True`` when the
1407db96d56Sopenharmony_ci      :class:`EmailMessage` is of type ``message/rfc822``.
1417db96d56Sopenharmony_ci
1427db96d56Sopenharmony_ci
1437db96d56Sopenharmony_ci   .. method:: set_unixfrom(unixfrom)
1447db96d56Sopenharmony_ci
1457db96d56Sopenharmony_ci      Set the message's envelope header to *unixfrom*, which should be a
1467db96d56Sopenharmony_ci      string.  (See :class:`~mailbox.mboxMessage` for a brief description of
1477db96d56Sopenharmony_ci      this header.)
1487db96d56Sopenharmony_ci
1497db96d56Sopenharmony_ci
1507db96d56Sopenharmony_ci   .. method:: get_unixfrom()
1517db96d56Sopenharmony_ci
1527db96d56Sopenharmony_ci      Return the message's envelope header.  Defaults to ``None`` if the
1537db96d56Sopenharmony_ci      envelope header was never set.
1547db96d56Sopenharmony_ci
1557db96d56Sopenharmony_ci
1567db96d56Sopenharmony_ci   The following methods implement the mapping-like interface for accessing the
1577db96d56Sopenharmony_ci   message's headers.  Note that there are some semantic differences
1587db96d56Sopenharmony_ci   between these methods and a normal mapping (i.e. dictionary) interface.  For
1597db96d56Sopenharmony_ci   example, in a dictionary there are no duplicate keys, but here there may be
1607db96d56Sopenharmony_ci   duplicate message headers.  Also, in dictionaries there is no guaranteed
1617db96d56Sopenharmony_ci   order to the keys returned by :meth:`keys`, but in an :class:`EmailMessage`
1627db96d56Sopenharmony_ci   object, headers are always returned in the order they appeared in the
1637db96d56Sopenharmony_ci   original message, or in which they were added to the message later.  Any
1647db96d56Sopenharmony_ci   header deleted and then re-added is always appended to the end of the
1657db96d56Sopenharmony_ci   header list.
1667db96d56Sopenharmony_ci
1677db96d56Sopenharmony_ci   These semantic differences are intentional and are biased toward
1687db96d56Sopenharmony_ci   convenience in the most common use cases.
1697db96d56Sopenharmony_ci
1707db96d56Sopenharmony_ci   Note that in all cases, any envelope header present in the message is not
1717db96d56Sopenharmony_ci   included in the mapping interface.
1727db96d56Sopenharmony_ci
1737db96d56Sopenharmony_ci
1747db96d56Sopenharmony_ci   .. method:: __len__()
1757db96d56Sopenharmony_ci
1767db96d56Sopenharmony_ci      Return the total number of headers, including duplicates.
1777db96d56Sopenharmony_ci
1787db96d56Sopenharmony_ci
1797db96d56Sopenharmony_ci   .. method:: __contains__(name)
1807db96d56Sopenharmony_ci
1817db96d56Sopenharmony_ci      Return ``True`` if the message object has a field named *name*. Matching is
1827db96d56Sopenharmony_ci      done without regard to case and *name* does not include the trailing
1837db96d56Sopenharmony_ci      colon.  Used for the ``in`` operator.  For example::
1847db96d56Sopenharmony_ci
1857db96d56Sopenharmony_ci           if 'message-id' in myMessage:
1867db96d56Sopenharmony_ci              print('Message-ID:', myMessage['message-id'])
1877db96d56Sopenharmony_ci
1887db96d56Sopenharmony_ci
1897db96d56Sopenharmony_ci   .. method:: __getitem__(name)
1907db96d56Sopenharmony_ci
1917db96d56Sopenharmony_ci      Return the value of the named header field.  *name* does not include the
1927db96d56Sopenharmony_ci      colon field separator.  If the header is missing, ``None`` is returned; a
1937db96d56Sopenharmony_ci      :exc:`KeyError` is never raised.
1947db96d56Sopenharmony_ci
1957db96d56Sopenharmony_ci      Note that if the named field appears more than once in the message's
1967db96d56Sopenharmony_ci      headers, exactly which of those field values will be returned is
1977db96d56Sopenharmony_ci      undefined.  Use the :meth:`get_all` method to get the values of all the
1987db96d56Sopenharmony_ci      extant headers named *name*.
1997db96d56Sopenharmony_ci
2007db96d56Sopenharmony_ci      Using the standard (non-``compat32``) policies, the returned value is an
2017db96d56Sopenharmony_ci      instance of a subclass of :class:`email.headerregistry.BaseHeader`.
2027db96d56Sopenharmony_ci
2037db96d56Sopenharmony_ci
2047db96d56Sopenharmony_ci   .. method:: __setitem__(name, val)
2057db96d56Sopenharmony_ci
2067db96d56Sopenharmony_ci      Add a header to the message with field name *name* and value *val*.  The
2077db96d56Sopenharmony_ci      field is appended to the end of the message's existing headers.
2087db96d56Sopenharmony_ci
2097db96d56Sopenharmony_ci      Note that this does *not* overwrite or delete any existing header with the same
2107db96d56Sopenharmony_ci      name.  If you want to ensure that the new header is the only one present in the
2117db96d56Sopenharmony_ci      message with field name *name*, delete the field first, e.g.::
2127db96d56Sopenharmony_ci
2137db96d56Sopenharmony_ci         del msg['subject']
2147db96d56Sopenharmony_ci         msg['subject'] = 'Python roolz!'
2157db96d56Sopenharmony_ci
2167db96d56Sopenharmony_ci      If the :mod:`policy` defines certain headers to be unique (as the standard
2177db96d56Sopenharmony_ci      policies do), this method may raise a :exc:`ValueError` when an attempt
2187db96d56Sopenharmony_ci      is made to assign a value to such a header when one already exists.  This
2197db96d56Sopenharmony_ci      behavior is intentional for consistency's sake, but do not depend on it
2207db96d56Sopenharmony_ci      as we may choose to make such assignments do an automatic deletion of the
2217db96d56Sopenharmony_ci      existing header in the future.
2227db96d56Sopenharmony_ci
2237db96d56Sopenharmony_ci
2247db96d56Sopenharmony_ci   .. method:: __delitem__(name)
2257db96d56Sopenharmony_ci
2267db96d56Sopenharmony_ci      Delete all occurrences of the field with name *name* from the message's
2277db96d56Sopenharmony_ci      headers.  No exception is raised if the named field isn't present in the
2287db96d56Sopenharmony_ci      headers.
2297db96d56Sopenharmony_ci
2307db96d56Sopenharmony_ci
2317db96d56Sopenharmony_ci   .. method:: keys()
2327db96d56Sopenharmony_ci
2337db96d56Sopenharmony_ci      Return a list of all the message's header field names.
2347db96d56Sopenharmony_ci
2357db96d56Sopenharmony_ci
2367db96d56Sopenharmony_ci   .. method:: values()
2377db96d56Sopenharmony_ci
2387db96d56Sopenharmony_ci      Return a list of all the message's field values.
2397db96d56Sopenharmony_ci
2407db96d56Sopenharmony_ci
2417db96d56Sopenharmony_ci   .. method:: items()
2427db96d56Sopenharmony_ci
2437db96d56Sopenharmony_ci      Return a list of 2-tuples containing all the message's field headers and
2447db96d56Sopenharmony_ci      values.
2457db96d56Sopenharmony_ci
2467db96d56Sopenharmony_ci
2477db96d56Sopenharmony_ci   .. method:: get(name, failobj=None)
2487db96d56Sopenharmony_ci
2497db96d56Sopenharmony_ci      Return the value of the named header field.  This is identical to
2507db96d56Sopenharmony_ci      :meth:`__getitem__` except that optional *failobj* is returned if the
2517db96d56Sopenharmony_ci      named header is missing (*failobj* defaults to ``None``).
2527db96d56Sopenharmony_ci
2537db96d56Sopenharmony_ci
2547db96d56Sopenharmony_ci   Here are some additional useful header related methods:
2557db96d56Sopenharmony_ci
2567db96d56Sopenharmony_ci
2577db96d56Sopenharmony_ci   .. method:: get_all(name, failobj=None)
2587db96d56Sopenharmony_ci
2597db96d56Sopenharmony_ci      Return a list of all the values for the field named *name*. If there are
2607db96d56Sopenharmony_ci      no such named headers in the message, *failobj* is returned (defaults to
2617db96d56Sopenharmony_ci      ``None``).
2627db96d56Sopenharmony_ci
2637db96d56Sopenharmony_ci
2647db96d56Sopenharmony_ci   .. method:: add_header(_name, _value, **_params)
2657db96d56Sopenharmony_ci
2667db96d56Sopenharmony_ci      Extended header setting.  This method is similar to :meth:`__setitem__`
2677db96d56Sopenharmony_ci      except that additional header parameters can be provided as keyword
2687db96d56Sopenharmony_ci      arguments.  *_name* is the header field to add and *_value* is the
2697db96d56Sopenharmony_ci      *primary* value for the header.
2707db96d56Sopenharmony_ci
2717db96d56Sopenharmony_ci      For each item in the keyword argument dictionary *_params*, the key is
2727db96d56Sopenharmony_ci      taken as the parameter name, with underscores converted to dashes (since
2737db96d56Sopenharmony_ci      dashes are illegal in Python identifiers).  Normally, the parameter will
2747db96d56Sopenharmony_ci      be added as ``key="value"`` unless the value is ``None``, in which case
2757db96d56Sopenharmony_ci      only the key will be added.
2767db96d56Sopenharmony_ci
2777db96d56Sopenharmony_ci      If the value contains non-ASCII characters, the charset and language may
2787db96d56Sopenharmony_ci      be explicitly controlled by specifying the value as a three tuple in the
2797db96d56Sopenharmony_ci      format ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string
2807db96d56Sopenharmony_ci      naming the charset to be used to encode the value, ``LANGUAGE`` can
2817db96d56Sopenharmony_ci      usually be set to ``None`` or the empty string (see :rfc:`2231` for other
2827db96d56Sopenharmony_ci      possibilities), and ``VALUE`` is the string value containing non-ASCII
2837db96d56Sopenharmony_ci      code points.  If a three tuple is not passed and the value contains
2847db96d56Sopenharmony_ci      non-ASCII characters, it is automatically encoded in :rfc:`2231` format
2857db96d56Sopenharmony_ci      using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of ``None``.
2867db96d56Sopenharmony_ci
2877db96d56Sopenharmony_ci      Here is an example::
2887db96d56Sopenharmony_ci
2897db96d56Sopenharmony_ci         msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
2907db96d56Sopenharmony_ci
2917db96d56Sopenharmony_ci      This will add a header that looks like ::
2927db96d56Sopenharmony_ci
2937db96d56Sopenharmony_ci         Content-Disposition: attachment; filename="bud.gif"
2947db96d56Sopenharmony_ci
2957db96d56Sopenharmony_ci      An example of the extended interface with non-ASCII characters::
2967db96d56Sopenharmony_ci
2977db96d56Sopenharmony_ci         msg.add_header('Content-Disposition', 'attachment',
2987db96d56Sopenharmony_ci                        filename=('iso-8859-1', '', 'Fußballer.ppt'))
2997db96d56Sopenharmony_ci
3007db96d56Sopenharmony_ci
3017db96d56Sopenharmony_ci   .. method:: replace_header(_name, _value)
3027db96d56Sopenharmony_ci
3037db96d56Sopenharmony_ci      Replace a header.  Replace the first header found in the message that
3047db96d56Sopenharmony_ci      matches *_name*, retaining header order and field name case of the
3057db96d56Sopenharmony_ci      original header.  If no matching header is found, raise a
3067db96d56Sopenharmony_ci      :exc:`KeyError`.
3077db96d56Sopenharmony_ci
3087db96d56Sopenharmony_ci
3097db96d56Sopenharmony_ci   .. method:: get_content_type()
3107db96d56Sopenharmony_ci
3117db96d56Sopenharmony_ci      Return the message's content type, coerced to lower case of the form
3127db96d56Sopenharmony_ci      :mimetype:`maintype/subtype`.  If there is no :mailheader:`Content-Type`
3137db96d56Sopenharmony_ci      header in the message return the value returned by
3147db96d56Sopenharmony_ci      :meth:`get_default_type`.  If the :mailheader:`Content-Type` header is
3157db96d56Sopenharmony_ci      invalid, return ``text/plain``.
3167db96d56Sopenharmony_ci
3177db96d56Sopenharmony_ci      (According to :rfc:`2045`, messages always have a default type,
3187db96d56Sopenharmony_ci      :meth:`get_content_type` will always return a value.  :rfc:`2045` defines
3197db96d56Sopenharmony_ci      a message's default type to be :mimetype:`text/plain` unless it appears
3207db96d56Sopenharmony_ci      inside a :mimetype:`multipart/digest` container, in which case it would
3217db96d56Sopenharmony_ci      be :mimetype:`message/rfc822`.  If the :mailheader:`Content-Type` header
3227db96d56Sopenharmony_ci      has an invalid type specification, :rfc:`2045` mandates that the default
3237db96d56Sopenharmony_ci      type be :mimetype:`text/plain`.)
3247db96d56Sopenharmony_ci
3257db96d56Sopenharmony_ci
3267db96d56Sopenharmony_ci   .. method:: get_content_maintype()
3277db96d56Sopenharmony_ci
3287db96d56Sopenharmony_ci      Return the message's main content type.  This is the :mimetype:`maintype`
3297db96d56Sopenharmony_ci      part of the string returned by :meth:`get_content_type`.
3307db96d56Sopenharmony_ci
3317db96d56Sopenharmony_ci
3327db96d56Sopenharmony_ci   .. method:: get_content_subtype()
3337db96d56Sopenharmony_ci
3347db96d56Sopenharmony_ci      Return the message's sub-content type.  This is the :mimetype:`subtype`
3357db96d56Sopenharmony_ci      part of the string returned by :meth:`get_content_type`.
3367db96d56Sopenharmony_ci
3377db96d56Sopenharmony_ci
3387db96d56Sopenharmony_ci   .. method:: get_default_type()
3397db96d56Sopenharmony_ci
3407db96d56Sopenharmony_ci      Return the default content type.  Most messages have a default content
3417db96d56Sopenharmony_ci      type of :mimetype:`text/plain`, except for messages that are subparts of
3427db96d56Sopenharmony_ci      :mimetype:`multipart/digest` containers.  Such subparts have a default
3437db96d56Sopenharmony_ci      content type of :mimetype:`message/rfc822`.
3447db96d56Sopenharmony_ci
3457db96d56Sopenharmony_ci
3467db96d56Sopenharmony_ci   .. method:: set_default_type(ctype)
3477db96d56Sopenharmony_ci
3487db96d56Sopenharmony_ci      Set the default content type.  *ctype* should either be
3497db96d56Sopenharmony_ci      :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is
3507db96d56Sopenharmony_ci      not enforced.  The default content type is not stored in the
3517db96d56Sopenharmony_ci      :mailheader:`Content-Type` header, so it only affects the return value of
3527db96d56Sopenharmony_ci      the ``get_content_type`` methods when no :mailheader:`Content-Type`
3537db96d56Sopenharmony_ci      header is present in the message.
3547db96d56Sopenharmony_ci
3557db96d56Sopenharmony_ci
3567db96d56Sopenharmony_ci   .. method:: set_param(param, value, header='Content-Type', requote=True, \
3577db96d56Sopenharmony_ci                         charset=None, language='', replace=False)
3587db96d56Sopenharmony_ci
3597db96d56Sopenharmony_ci      Set a parameter in the :mailheader:`Content-Type` header.  If the
3607db96d56Sopenharmony_ci      parameter already exists in the header, replace its value with *value*.
3617db96d56Sopenharmony_ci      When *header* is ``Content-Type`` (the default) and the header does not
3627db96d56Sopenharmony_ci      yet exist in the message, add it, set its value to
3637db96d56Sopenharmony_ci      :mimetype:`text/plain`, and append the new parameter value.  Optional
3647db96d56Sopenharmony_ci      *header* specifies an alternative header to :mailheader:`Content-Type`.
3657db96d56Sopenharmony_ci
3667db96d56Sopenharmony_ci      If the value contains non-ASCII characters, the charset and language may
3677db96d56Sopenharmony_ci      be explicitly specified using the optional *charset* and *language*
3687db96d56Sopenharmony_ci      parameters.  Optional *language* specifies the :rfc:`2231` language,
3697db96d56Sopenharmony_ci      defaulting to the empty string.  Both *charset* and *language* should be
3707db96d56Sopenharmony_ci      strings.  The default is to use the ``utf8`` *charset* and ``None`` for
3717db96d56Sopenharmony_ci      the *language*.
3727db96d56Sopenharmony_ci
3737db96d56Sopenharmony_ci      If *replace* is ``False`` (the default) the header is moved to the
3747db96d56Sopenharmony_ci      end of the list of headers.  If *replace* is ``True``, the header
3757db96d56Sopenharmony_ci      will be updated in place.
3767db96d56Sopenharmony_ci
3777db96d56Sopenharmony_ci      Use of the *requote* parameter with :class:`EmailMessage` objects is
3787db96d56Sopenharmony_ci      deprecated.
3797db96d56Sopenharmony_ci
3807db96d56Sopenharmony_ci      Note that existing parameter values of headers may be accessed through
3817db96d56Sopenharmony_ci      the :attr:`~email.headerregistry.BaseHeader.params` attribute of the
3827db96d56Sopenharmony_ci      header value (for example, ``msg['Content-Type'].params['charset']``).
3837db96d56Sopenharmony_ci
3847db96d56Sopenharmony_ci      .. versionchanged:: 3.4 ``replace`` keyword was added.
3857db96d56Sopenharmony_ci
3867db96d56Sopenharmony_ci
3877db96d56Sopenharmony_ci   .. method:: del_param(param, header='content-type', requote=True)
3887db96d56Sopenharmony_ci
3897db96d56Sopenharmony_ci      Remove the given parameter completely from the :mailheader:`Content-Type`
3907db96d56Sopenharmony_ci      header.  The header will be re-written in place without the parameter or
3917db96d56Sopenharmony_ci      its value.  Optional *header* specifies an alternative to
3927db96d56Sopenharmony_ci      :mailheader:`Content-Type`.
3937db96d56Sopenharmony_ci
3947db96d56Sopenharmony_ci      Use of the *requote* parameter with :class:`EmailMessage` objects is
3957db96d56Sopenharmony_ci      deprecated.
3967db96d56Sopenharmony_ci
3977db96d56Sopenharmony_ci
3987db96d56Sopenharmony_ci   .. method:: get_filename(failobj=None)
3997db96d56Sopenharmony_ci
4007db96d56Sopenharmony_ci      Return the value of the ``filename`` parameter of the
4017db96d56Sopenharmony_ci      :mailheader:`Content-Disposition` header of the message.  If the header
4027db96d56Sopenharmony_ci      does not have a ``filename`` parameter, this method falls back to looking
4037db96d56Sopenharmony_ci      for the ``name`` parameter on the :mailheader:`Content-Type` header.  If
4047db96d56Sopenharmony_ci      neither is found, or the header is missing, then *failobj* is returned.
4057db96d56Sopenharmony_ci      The returned string will always be unquoted as per
4067db96d56Sopenharmony_ci      :func:`email.utils.unquote`.
4077db96d56Sopenharmony_ci
4087db96d56Sopenharmony_ci
4097db96d56Sopenharmony_ci   .. method:: get_boundary(failobj=None)
4107db96d56Sopenharmony_ci
4117db96d56Sopenharmony_ci      Return the value of the ``boundary`` parameter of the
4127db96d56Sopenharmony_ci      :mailheader:`Content-Type` header of the message, or *failobj* if either
4137db96d56Sopenharmony_ci      the header is missing, or has no ``boundary`` parameter.  The returned
4147db96d56Sopenharmony_ci      string will always be unquoted as per :func:`email.utils.unquote`.
4157db96d56Sopenharmony_ci
4167db96d56Sopenharmony_ci
4177db96d56Sopenharmony_ci   .. method:: set_boundary(boundary)
4187db96d56Sopenharmony_ci
4197db96d56Sopenharmony_ci      Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
4207db96d56Sopenharmony_ci      *boundary*.  :meth:`set_boundary` will always quote *boundary* if
4217db96d56Sopenharmony_ci      necessary.  A :exc:`~email.errors.HeaderParseError` is raised if the
4227db96d56Sopenharmony_ci      message object has no :mailheader:`Content-Type` header.
4237db96d56Sopenharmony_ci
4247db96d56Sopenharmony_ci      Note that using this method is subtly different from deleting the old
4257db96d56Sopenharmony_ci      :mailheader:`Content-Type` header and adding a new one with the new
4267db96d56Sopenharmony_ci      boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
4277db96d56Sopenharmony_ci      the order of the :mailheader:`Content-Type` header in the list of
4287db96d56Sopenharmony_ci      headers.
4297db96d56Sopenharmony_ci
4307db96d56Sopenharmony_ci
4317db96d56Sopenharmony_ci   .. method:: get_content_charset(failobj=None)
4327db96d56Sopenharmony_ci
4337db96d56Sopenharmony_ci      Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
4347db96d56Sopenharmony_ci      coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
4357db96d56Sopenharmony_ci      that header has no ``charset`` parameter, *failobj* is returned.
4367db96d56Sopenharmony_ci
4377db96d56Sopenharmony_ci
4387db96d56Sopenharmony_ci   .. method:: get_charsets(failobj=None)
4397db96d56Sopenharmony_ci
4407db96d56Sopenharmony_ci      Return a list containing the character set names in the message.  If the
4417db96d56Sopenharmony_ci      message is a :mimetype:`multipart`, then the list will contain one element
4427db96d56Sopenharmony_ci      for each subpart in the payload, otherwise, it will be a list of length 1.
4437db96d56Sopenharmony_ci
4447db96d56Sopenharmony_ci      Each item in the list will be a string which is the value of the
4457db96d56Sopenharmony_ci      ``charset`` parameter in the :mailheader:`Content-Type` header for the
4467db96d56Sopenharmony_ci      represented subpart.  If the subpart has no :mailheader:`Content-Type`
4477db96d56Sopenharmony_ci      header, no ``charset`` parameter, or is not of the :mimetype:`text` main
4487db96d56Sopenharmony_ci      MIME type, then that item in the returned list will be *failobj*.
4497db96d56Sopenharmony_ci
4507db96d56Sopenharmony_ci
4517db96d56Sopenharmony_ci   .. method:: is_attachment
4527db96d56Sopenharmony_ci
4537db96d56Sopenharmony_ci      Return ``True`` if there is a :mailheader:`Content-Disposition` header
4547db96d56Sopenharmony_ci      and its (case insensitive) value is ``attachment``, ``False`` otherwise.
4557db96d56Sopenharmony_ci
4567db96d56Sopenharmony_ci      .. versionchanged:: 3.4.2
4577db96d56Sopenharmony_ci         is_attachment is now a method instead of a property, for consistency
4587db96d56Sopenharmony_ci         with :meth:`~email.message.Message.is_multipart`.
4597db96d56Sopenharmony_ci
4607db96d56Sopenharmony_ci
4617db96d56Sopenharmony_ci   .. method:: get_content_disposition()
4627db96d56Sopenharmony_ci
4637db96d56Sopenharmony_ci      Return the lowercased value (without parameters) of the message's
4647db96d56Sopenharmony_ci      :mailheader:`Content-Disposition` header if it has one, or ``None``.  The
4657db96d56Sopenharmony_ci      possible values for this method are *inline*, *attachment* or ``None``
4667db96d56Sopenharmony_ci      if the message follows :rfc:`2183`.
4677db96d56Sopenharmony_ci
4687db96d56Sopenharmony_ci      .. versionadded:: 3.5
4697db96d56Sopenharmony_ci
4707db96d56Sopenharmony_ci
4717db96d56Sopenharmony_ci   The following methods relate to interrogating and manipulating the content
4727db96d56Sopenharmony_ci   (payload) of the message.
4737db96d56Sopenharmony_ci
4747db96d56Sopenharmony_ci
4757db96d56Sopenharmony_ci   .. method:: walk()
4767db96d56Sopenharmony_ci
4777db96d56Sopenharmony_ci      The :meth:`walk` method is an all-purpose generator which can be used to
4787db96d56Sopenharmony_ci      iterate over all the parts and subparts of a message object tree, in
4797db96d56Sopenharmony_ci      depth-first traversal order.  You will typically use :meth:`walk` as the
4807db96d56Sopenharmony_ci      iterator in a ``for`` loop; each iteration returns the next subpart.
4817db96d56Sopenharmony_ci
4827db96d56Sopenharmony_ci      Here's an example that prints the MIME type of every part of a multipart
4837db96d56Sopenharmony_ci      message structure:
4847db96d56Sopenharmony_ci
4857db96d56Sopenharmony_ci      .. testsetup::
4867db96d56Sopenharmony_ci
4877db96d56Sopenharmony_ci         from email import message_from_binary_file
4887db96d56Sopenharmony_ci         with open('../Lib/test/test_email/data/msg_16.txt', 'rb') as f:
4897db96d56Sopenharmony_ci             msg = message_from_binary_file(f)
4907db96d56Sopenharmony_ci
4917db96d56Sopenharmony_ci      .. doctest::
4927db96d56Sopenharmony_ci
4937db96d56Sopenharmony_ci         >>> for part in msg.walk():
4947db96d56Sopenharmony_ci         ...     print(part.get_content_type())
4957db96d56Sopenharmony_ci         multipart/report
4967db96d56Sopenharmony_ci         text/plain
4977db96d56Sopenharmony_ci         message/delivery-status
4987db96d56Sopenharmony_ci         text/plain
4997db96d56Sopenharmony_ci         text/plain
5007db96d56Sopenharmony_ci         message/rfc822
5017db96d56Sopenharmony_ci         text/plain
5027db96d56Sopenharmony_ci
5037db96d56Sopenharmony_ci      ``walk`` iterates over the subparts of any part where
5047db96d56Sopenharmony_ci      :meth:`is_multipart` returns ``True``, even though
5057db96d56Sopenharmony_ci      ``msg.get_content_maintype() == 'multipart'`` may return ``False``.  We
5067db96d56Sopenharmony_ci      can see this in our example by making use of the ``_structure`` debug
5077db96d56Sopenharmony_ci      helper function:
5087db96d56Sopenharmony_ci
5097db96d56Sopenharmony_ci      .. doctest::
5107db96d56Sopenharmony_ci
5117db96d56Sopenharmony_ci         >>> from email.iterators import _structure
5127db96d56Sopenharmony_ci         >>> for part in msg.walk():
5137db96d56Sopenharmony_ci         ...     print(part.get_content_maintype() == 'multipart',
5147db96d56Sopenharmony_ci         ...           part.is_multipart())
5157db96d56Sopenharmony_ci         True True
5167db96d56Sopenharmony_ci         False False
5177db96d56Sopenharmony_ci         False True
5187db96d56Sopenharmony_ci         False False
5197db96d56Sopenharmony_ci         False False
5207db96d56Sopenharmony_ci         False True
5217db96d56Sopenharmony_ci         False False
5227db96d56Sopenharmony_ci         >>> _structure(msg)
5237db96d56Sopenharmony_ci         multipart/report
5247db96d56Sopenharmony_ci             text/plain
5257db96d56Sopenharmony_ci             message/delivery-status
5267db96d56Sopenharmony_ci                 text/plain
5277db96d56Sopenharmony_ci                 text/plain
5287db96d56Sopenharmony_ci             message/rfc822
5297db96d56Sopenharmony_ci                 text/plain
5307db96d56Sopenharmony_ci
5317db96d56Sopenharmony_ci      Here the ``message`` parts are not ``multiparts``, but they do contain
5327db96d56Sopenharmony_ci      subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends
5337db96d56Sopenharmony_ci      into the subparts.
5347db96d56Sopenharmony_ci
5357db96d56Sopenharmony_ci
5367db96d56Sopenharmony_ci   .. method:: get_body(preferencelist=('related', 'html', 'plain'))
5377db96d56Sopenharmony_ci
5387db96d56Sopenharmony_ci      Return the MIME part that is the best candidate to be the "body" of the
5397db96d56Sopenharmony_ci      message.
5407db96d56Sopenharmony_ci
5417db96d56Sopenharmony_ci      *preferencelist* must be a sequence of strings from the set ``related``,
5427db96d56Sopenharmony_ci      ``html``, and ``plain``, and indicates the order of preference for the
5437db96d56Sopenharmony_ci      content type of the part returned.
5447db96d56Sopenharmony_ci
5457db96d56Sopenharmony_ci      Start looking for candidate matches with the object on which the
5467db96d56Sopenharmony_ci      ``get_body`` method is called.
5477db96d56Sopenharmony_ci
5487db96d56Sopenharmony_ci      If ``related`` is not included in *preferencelist*, consider the root
5497db96d56Sopenharmony_ci      part (or subpart of the root part) of any related encountered as a
5507db96d56Sopenharmony_ci      candidate if the (sub-)part matches a preference.
5517db96d56Sopenharmony_ci
5527db96d56Sopenharmony_ci      When encountering a ``multipart/related``, check the ``start`` parameter
5537db96d56Sopenharmony_ci      and if a part with a matching :mailheader:`Content-ID` is found, consider
5547db96d56Sopenharmony_ci      only it when looking for candidate matches.  Otherwise consider only the
5557db96d56Sopenharmony_ci      first (default root) part of the ``multipart/related``.
5567db96d56Sopenharmony_ci
5577db96d56Sopenharmony_ci      If a part has a :mailheader:`Content-Disposition` header, only consider
5587db96d56Sopenharmony_ci      the part a candidate match if the value of the header is ``inline``.
5597db96d56Sopenharmony_ci
5607db96d56Sopenharmony_ci      If none of the candidates matches any of the preferences in
5617db96d56Sopenharmony_ci      *preferencelist*, return ``None``.
5627db96d56Sopenharmony_ci
5637db96d56Sopenharmony_ci      Notes: (1) For most applications the only *preferencelist* combinations
5647db96d56Sopenharmony_ci      that really make sense are ``('plain',)``, ``('html', 'plain')``, and the
5657db96d56Sopenharmony_ci      default ``('related', 'html', 'plain')``.  (2) Because matching starts
5667db96d56Sopenharmony_ci      with the object on which ``get_body`` is called, calling ``get_body`` on
5677db96d56Sopenharmony_ci      a ``multipart/related`` will return the object itself unless
5687db96d56Sopenharmony_ci      *preferencelist* has a non-default value. (3) Messages (or message parts)
5697db96d56Sopenharmony_ci      that do not specify a :mailheader:`Content-Type` or whose
5707db96d56Sopenharmony_ci      :mailheader:`Content-Type` header is invalid will be treated as if they
5717db96d56Sopenharmony_ci      are of type ``text/plain``, which may occasionally cause ``get_body`` to
5727db96d56Sopenharmony_ci      return unexpected results.
5737db96d56Sopenharmony_ci
5747db96d56Sopenharmony_ci
5757db96d56Sopenharmony_ci   .. method:: iter_attachments()
5767db96d56Sopenharmony_ci
5777db96d56Sopenharmony_ci      Return an iterator over all of the immediate sub-parts of the message
5787db96d56Sopenharmony_ci      that are not candidate "body" parts.  That is, skip the first occurrence
5797db96d56Sopenharmony_ci      of each of ``text/plain``, ``text/html``, ``multipart/related``, or
5807db96d56Sopenharmony_ci      ``multipart/alternative`` (unless they are explicitly marked as
5817db96d56Sopenharmony_ci      attachments via :mailheader:`Content-Disposition: attachment`), and
5827db96d56Sopenharmony_ci      return all remaining parts.  When applied directly to a
5837db96d56Sopenharmony_ci      ``multipart/related``, return an iterator over the all the related parts
5847db96d56Sopenharmony_ci      except the root part (ie: the part pointed to by the ``start`` parameter,
5857db96d56Sopenharmony_ci      or the first part if there is no ``start`` parameter or the ``start``
5867db96d56Sopenharmony_ci      parameter doesn't match the :mailheader:`Content-ID` of any of the
5877db96d56Sopenharmony_ci      parts).  When applied directly to a ``multipart/alternative`` or a
5887db96d56Sopenharmony_ci      non-``multipart``, return an empty iterator.
5897db96d56Sopenharmony_ci
5907db96d56Sopenharmony_ci
5917db96d56Sopenharmony_ci   .. method:: iter_parts()
5927db96d56Sopenharmony_ci
5937db96d56Sopenharmony_ci      Return an iterator over all of the immediate sub-parts of the message,
5947db96d56Sopenharmony_ci      which will be empty for a non-``multipart``.  (See also
5957db96d56Sopenharmony_ci      :meth:`~email.message.EmailMessage.walk`.)
5967db96d56Sopenharmony_ci
5977db96d56Sopenharmony_ci
5987db96d56Sopenharmony_ci   .. method:: get_content(*args, content_manager=None, **kw)
5997db96d56Sopenharmony_ci
6007db96d56Sopenharmony_ci      Call the :meth:`~email.contentmanager.ContentManager.get_content` method
6017db96d56Sopenharmony_ci      of the *content_manager*, passing self as the message object, and passing
6027db96d56Sopenharmony_ci      along any other arguments or keywords as additional arguments.  If
6037db96d56Sopenharmony_ci      *content_manager* is not specified, use the ``content_manager`` specified
6047db96d56Sopenharmony_ci      by the current :mod:`~email.policy`.
6057db96d56Sopenharmony_ci
6067db96d56Sopenharmony_ci
6077db96d56Sopenharmony_ci   .. method:: set_content(*args, content_manager=None, **kw)
6087db96d56Sopenharmony_ci
6097db96d56Sopenharmony_ci      Call the :meth:`~email.contentmanager.ContentManager.set_content` method
6107db96d56Sopenharmony_ci      of the *content_manager*, passing self as the message object, and passing
6117db96d56Sopenharmony_ci      along any other arguments or keywords as additional arguments.  If
6127db96d56Sopenharmony_ci      *content_manager* is not specified, use the ``content_manager`` specified
6137db96d56Sopenharmony_ci      by the current :mod:`~email.policy`.
6147db96d56Sopenharmony_ci
6157db96d56Sopenharmony_ci
6167db96d56Sopenharmony_ci   .. method:: make_related(boundary=None)
6177db96d56Sopenharmony_ci
6187db96d56Sopenharmony_ci      Convert a non-``multipart`` message into a ``multipart/related`` message,
6197db96d56Sopenharmony_ci      moving any existing :mailheader:`Content-` headers and payload into a
6207db96d56Sopenharmony_ci      (new) first part of the ``multipart``.  If *boundary* is specified, use
6217db96d56Sopenharmony_ci      it as the boundary string in the multipart, otherwise leave the boundary
6227db96d56Sopenharmony_ci      to be automatically created when it is needed (for example, when the
6237db96d56Sopenharmony_ci      message is serialized).
6247db96d56Sopenharmony_ci
6257db96d56Sopenharmony_ci
6267db96d56Sopenharmony_ci   .. method:: make_alternative(boundary=None)
6277db96d56Sopenharmony_ci
6287db96d56Sopenharmony_ci      Convert a non-``multipart`` or a ``multipart/related`` into a
6297db96d56Sopenharmony_ci      ``multipart/alternative``, moving any existing :mailheader:`Content-`
6307db96d56Sopenharmony_ci      headers and payload into a (new) first part of the ``multipart``.  If
6317db96d56Sopenharmony_ci      *boundary* is specified, use it as the boundary string in the multipart,
6327db96d56Sopenharmony_ci      otherwise leave the boundary to be automatically created when it is
6337db96d56Sopenharmony_ci      needed (for example, when the message is serialized).
6347db96d56Sopenharmony_ci
6357db96d56Sopenharmony_ci
6367db96d56Sopenharmony_ci   .. method:: make_mixed(boundary=None)
6377db96d56Sopenharmony_ci
6387db96d56Sopenharmony_ci      Convert a non-``multipart``, a ``multipart/related``, or a
6397db96d56Sopenharmony_ci      ``multipart-alternative`` into a ``multipart/mixed``, moving any existing
6407db96d56Sopenharmony_ci      :mailheader:`Content-` headers and payload into a (new) first part of the
6417db96d56Sopenharmony_ci      ``multipart``.  If *boundary* is specified, use it as the boundary string
6427db96d56Sopenharmony_ci      in the multipart, otherwise leave the boundary to be automatically
6437db96d56Sopenharmony_ci      created when it is needed (for example, when the message is serialized).
6447db96d56Sopenharmony_ci
6457db96d56Sopenharmony_ci
6467db96d56Sopenharmony_ci   .. method:: add_related(*args, content_manager=None, **kw)
6477db96d56Sopenharmony_ci
6487db96d56Sopenharmony_ci      If the message is a ``multipart/related``, create a new message
6497db96d56Sopenharmony_ci      object, pass all of the arguments to its :meth:`set_content` method,
6507db96d56Sopenharmony_ci      and :meth:`~email.message.Message.attach` it to the ``multipart``.  If
6517db96d56Sopenharmony_ci      the message is a non-``multipart``, call :meth:`make_related` and then
6527db96d56Sopenharmony_ci      proceed as above.  If the message is any other type of ``multipart``,
6537db96d56Sopenharmony_ci      raise a :exc:`TypeError`. If *content_manager* is not specified, use
6547db96d56Sopenharmony_ci      the ``content_manager`` specified by the current :mod:`~email.policy`.
6557db96d56Sopenharmony_ci      If the added part has no :mailheader:`Content-Disposition` header,
6567db96d56Sopenharmony_ci      add one with the value ``inline``.
6577db96d56Sopenharmony_ci
6587db96d56Sopenharmony_ci
6597db96d56Sopenharmony_ci   .. method:: add_alternative(*args, content_manager=None, **kw)
6607db96d56Sopenharmony_ci
6617db96d56Sopenharmony_ci      If the message is a ``multipart/alternative``, create a new message
6627db96d56Sopenharmony_ci      object, pass all of the arguments to its :meth:`set_content` method, and
6637db96d56Sopenharmony_ci      :meth:`~email.message.Message.attach` it to the ``multipart``.  If the
6647db96d56Sopenharmony_ci      message is a non-``multipart`` or ``multipart/related``, call
6657db96d56Sopenharmony_ci      :meth:`make_alternative` and then proceed as above.  If the message is
6667db96d56Sopenharmony_ci      any other type of ``multipart``, raise a :exc:`TypeError`. If
6677db96d56Sopenharmony_ci      *content_manager* is not specified, use the ``content_manager`` specified
6687db96d56Sopenharmony_ci      by the current :mod:`~email.policy`.
6697db96d56Sopenharmony_ci
6707db96d56Sopenharmony_ci
6717db96d56Sopenharmony_ci   .. method:: add_attachment(*args, content_manager=None, **kw)
6727db96d56Sopenharmony_ci
6737db96d56Sopenharmony_ci      If the message is a ``multipart/mixed``, create a new message object,
6747db96d56Sopenharmony_ci      pass all of the arguments to its :meth:`set_content` method, and
6757db96d56Sopenharmony_ci      :meth:`~email.message.Message.attach` it to the ``multipart``.  If the
6767db96d56Sopenharmony_ci      message is a non-``multipart``, ``multipart/related``, or
6777db96d56Sopenharmony_ci      ``multipart/alternative``, call :meth:`make_mixed` and then proceed as
6787db96d56Sopenharmony_ci      above. If *content_manager* is not specified, use the ``content_manager``
6797db96d56Sopenharmony_ci      specified by the current :mod:`~email.policy`.  If the added part
6807db96d56Sopenharmony_ci      has no :mailheader:`Content-Disposition` header, add one with the value
6817db96d56Sopenharmony_ci      ``attachment``.  This method can be used both for explicit attachments
6827db96d56Sopenharmony_ci      (:mailheader:`Content-Disposition: attachment`) and ``inline`` attachments
6837db96d56Sopenharmony_ci      (:mailheader:`Content-Disposition: inline`), by passing appropriate
6847db96d56Sopenharmony_ci      options to the ``content_manager``.
6857db96d56Sopenharmony_ci
6867db96d56Sopenharmony_ci
6877db96d56Sopenharmony_ci   .. method:: clear()
6887db96d56Sopenharmony_ci
6897db96d56Sopenharmony_ci      Remove the payload and all of the headers.
6907db96d56Sopenharmony_ci
6917db96d56Sopenharmony_ci
6927db96d56Sopenharmony_ci   .. method:: clear_content()
6937db96d56Sopenharmony_ci
6947db96d56Sopenharmony_ci      Remove the payload and all of the :exc:`Content-` headers, leaving
6957db96d56Sopenharmony_ci      all other headers intact and in their original order.
6967db96d56Sopenharmony_ci
6977db96d56Sopenharmony_ci
6987db96d56Sopenharmony_ci   :class:`EmailMessage` objects have the following instance attributes:
6997db96d56Sopenharmony_ci
7007db96d56Sopenharmony_ci
7017db96d56Sopenharmony_ci   .. attribute:: preamble
7027db96d56Sopenharmony_ci
7037db96d56Sopenharmony_ci      The format of a MIME document allows for some text between the blank line
7047db96d56Sopenharmony_ci      following the headers, and the first multipart boundary string. Normally,
7057db96d56Sopenharmony_ci      this text is never visible in a MIME-aware mail reader because it falls
7067db96d56Sopenharmony_ci      outside the standard MIME armor.  However, when viewing the raw text of
7077db96d56Sopenharmony_ci      the message, or when viewing the message in a non-MIME aware reader, this
7087db96d56Sopenharmony_ci      text can become visible.
7097db96d56Sopenharmony_ci
7107db96d56Sopenharmony_ci      The *preamble* attribute contains this leading extra-armor text for MIME
7117db96d56Sopenharmony_ci      documents.  When the :class:`~email.parser.Parser` discovers some text
7127db96d56Sopenharmony_ci      after the headers but before the first boundary string, it assigns this
7137db96d56Sopenharmony_ci      text to the message's *preamble* attribute.  When the
7147db96d56Sopenharmony_ci      :class:`~email.generator.Generator` is writing out the plain text
7157db96d56Sopenharmony_ci      representation of a MIME message, and it finds the
7167db96d56Sopenharmony_ci      message has a *preamble* attribute, it will write this text in the area
7177db96d56Sopenharmony_ci      between the headers and the first boundary.  See :mod:`email.parser` and
7187db96d56Sopenharmony_ci      :mod:`email.generator` for details.
7197db96d56Sopenharmony_ci
7207db96d56Sopenharmony_ci      Note that if the message object has no preamble, the *preamble* attribute
7217db96d56Sopenharmony_ci      will be ``None``.
7227db96d56Sopenharmony_ci
7237db96d56Sopenharmony_ci
7247db96d56Sopenharmony_ci   .. attribute:: epilogue
7257db96d56Sopenharmony_ci
7267db96d56Sopenharmony_ci      The *epilogue* attribute acts the same way as the *preamble* attribute,
7277db96d56Sopenharmony_ci      except that it contains text that appears between the last boundary and
7287db96d56Sopenharmony_ci      the end of the message.  As with the :attr:`~EmailMessage.preamble`,
7297db96d56Sopenharmony_ci      if there is no epilog text this attribute will be ``None``.
7307db96d56Sopenharmony_ci
7317db96d56Sopenharmony_ci
7327db96d56Sopenharmony_ci   .. attribute:: defects
7337db96d56Sopenharmony_ci
7347db96d56Sopenharmony_ci      The *defects* attribute contains a list of all the problems found when
7357db96d56Sopenharmony_ci      parsing this message.  See :mod:`email.errors` for a detailed description
7367db96d56Sopenharmony_ci      of the possible parsing defects.
7377db96d56Sopenharmony_ci
7387db96d56Sopenharmony_ci
7397db96d56Sopenharmony_ci.. class:: MIMEPart(policy=default)
7407db96d56Sopenharmony_ci
7417db96d56Sopenharmony_ci    This class represents a subpart of a MIME message.  It is identical to
7427db96d56Sopenharmony_ci    :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are
7437db96d56Sopenharmony_ci    added when :meth:`~EmailMessage.set_content` is called, since sub-parts do
7447db96d56Sopenharmony_ci    not need their own :mailheader:`MIME-Version` headers.
7457db96d56Sopenharmony_ci
7467db96d56Sopenharmony_ci
7477db96d56Sopenharmony_ci.. rubric:: Footnotes
7487db96d56Sopenharmony_ci
7497db96d56Sopenharmony_ci.. [1] Originally added in 3.4 as a :term:`provisional module <provisional
7507db96d56Sopenharmony_ci       package>`.  Docs for legacy message class moved to
7517db96d56Sopenharmony_ci       :ref:`compat32_message`.
752