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