1:mod:`email.message`: Representing an email message 2--------------------------------------------------- 3 4.. module:: email.message 5 :synopsis: The base class representing email messages. 6.. moduleauthor:: R. David Murray <rdmurray@bitdance.com> 7.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>, 8 Barry A. Warsaw <barry@python.org> 9 10**Source code:** :source:`Lib/email/message.py` 11 12-------------- 13 14.. versionadded:: 3.6 [1]_ 15 16The central class in the :mod:`email` package is the :class:`EmailMessage` 17class, imported from the :mod:`email.message` module. It is the base class for 18the :mod:`email` object model. :class:`EmailMessage` provides the core 19functionality for setting and querying header fields, for accessing message 20bodies, and for creating or modifying structured messages. 21 22An email message consists of *headers* and a *payload* (which is also referred 23to as the *content*). Headers are :rfc:`5322` or :rfc:`6532` style field names 24and values, where the field name and value are separated by a colon. The colon 25is not part of either the field name or the field value. The payload may be a 26simple text message, or a binary object, or a structured sequence of 27sub-messages each with their own set of headers and their own payload. The 28latter type of payload is indicated by the message having a MIME type such as 29:mimetype:`multipart/\*` or :mimetype:`message/rfc822`. 30 31The conceptual model provided by an :class:`EmailMessage` object is that of an 32ordered dictionary of headers coupled with a *payload* that represents the 33:rfc:`5322` body of the message, which might be a list of sub-``EmailMessage`` 34objects. In addition to the normal dictionary methods for accessing the header 35names and values, there are methods for accessing specialized information from 36the headers (for example the MIME content type), for operating on the payload, 37for generating a serialized version of the message, and for recursively walking 38over the object tree. 39 40The :class:`EmailMessage` dictionary-like interface is indexed by the header 41names, which must be ASCII values. The values of the dictionary are strings 42with some extra methods. Headers are stored and returned in case-preserving 43form, but field names are matched case-insensitively. Unlike a real dict, 44there is an ordering to the keys, and there can be duplicate keys. Additional 45methods are provided for working with headers that have duplicate keys. 46 47The *payload* is either a string or bytes object, in the case of simple message 48objects, or a list of :class:`EmailMessage` objects, for MIME container 49documents such as :mimetype:`multipart/\*` and :mimetype:`message/rfc822` 50message objects. 51 52 53.. class:: EmailMessage(policy=default) 54 55 If *policy* is specified use the rules it specifies to update and serialize 56 the representation of the message. If *policy* is not set, use the 57 :class:`~email.policy.default` policy, which follows the rules of the email 58 RFCs except for line endings (instead of the RFC mandated ``\r\n``, it uses 59 the Python standard ``\n`` line endings). For more information see the 60 :mod:`~email.policy` documentation. 61 62 .. method:: as_string(unixfrom=False, maxheaderlen=None, policy=None) 63 64 Return the entire message flattened as a string. When optional 65 *unixfrom* is true, the envelope header is included in the returned 66 string. *unixfrom* defaults to ``False``. For backward compatibility 67 with the base :class:`~email.message.Message` class *maxheaderlen* is 68 accepted, but defaults to ``None``, which means that by default the line 69 length is controlled by the 70 :attr:`~email.policy.EmailPolicy.max_line_length` of the policy. The 71 *policy* argument may be used to override the default policy obtained 72 from the message instance. This can be used to control some of the 73 formatting produced by the method, since the specified *policy* will be 74 passed to the :class:`~email.generator.Generator`. 75 76 Flattening the message may trigger changes to the :class:`EmailMessage` 77 if defaults need to be filled in to complete the transformation to a 78 string (for example, MIME boundaries may be generated or modified). 79 80 Note that this method is provided as a convenience and may not be the 81 most useful way to serialize messages in your application, especially if 82 you are dealing with multiple messages. See 83 :class:`email.generator.Generator` for a more flexible API for 84 serializing messages. Note also that this method is restricted to 85 producing messages serialized as "7 bit clean" when 86 :attr:`~email.policy.EmailPolicy.utf8` is ``False``, which is the default. 87 88 .. versionchanged:: 3.6 the default behavior when *maxheaderlen* 89 is not specified was changed from defaulting to 0 to defaulting 90 to the value of *max_line_length* from the policy. 91 92 93 .. method:: __str__() 94 95 Equivalent to ``as_string(policy=self.policy.clone(utf8=True))``. Allows 96 ``str(msg)`` to produce a string containing the serialized message in a 97 readable format. 98 99 .. versionchanged:: 3.4 the method was changed to use ``utf8=True``, 100 thus producing an :rfc:`6531`-like message representation, instead of 101 being a direct alias for :meth:`as_string`. 102 103 104 .. method:: as_bytes(unixfrom=False, policy=None) 105 106 Return the entire message flattened as a bytes object. When optional 107 *unixfrom* is true, the envelope header is included in the returned 108 string. *unixfrom* defaults to ``False``. The *policy* argument may be 109 used to override the default policy obtained from the message instance. 110 This can be used to control some of the formatting produced by the 111 method, since the specified *policy* will be passed to the 112 :class:`~email.generator.BytesGenerator`. 113 114 Flattening the message may trigger changes to the :class:`EmailMessage` 115 if defaults need to be filled in to complete the transformation to a 116 string (for example, MIME boundaries may be generated or modified). 117 118 Note that this method is provided as a convenience and may not be the 119 most useful way to serialize messages in your application, especially if 120 you are dealing with multiple messages. See 121 :class:`email.generator.BytesGenerator` for a more flexible API for 122 serializing messages. 123 124 125 .. method:: __bytes__() 126 127 Equivalent to :meth:`.as_bytes()`. Allows ``bytes(msg)`` to produce a 128 bytes object containing the serialized message. 129 130 131 .. method:: is_multipart() 132 133 Return ``True`` if the message's payload is a list of 134 sub-\ :class:`EmailMessage` objects, otherwise return ``False``. When 135 :meth:`is_multipart` returns ``False``, the payload should be a string 136 object (which might be a CTE encoded binary payload). Note that 137 :meth:`is_multipart` returning ``True`` does not necessarily mean that 138 "msg.get_content_maintype() == 'multipart'" will return the ``True``. 139 For example, ``is_multipart`` will return ``True`` when the 140 :class:`EmailMessage` is of type ``message/rfc822``. 141 142 143 .. method:: set_unixfrom(unixfrom) 144 145 Set the message's envelope header to *unixfrom*, which should be a 146 string. (See :class:`~mailbox.mboxMessage` for a brief description of 147 this header.) 148 149 150 .. method:: get_unixfrom() 151 152 Return the message's envelope header. Defaults to ``None`` if the 153 envelope header was never set. 154 155 156 The following methods implement the mapping-like interface for accessing the 157 message's headers. Note that there are some semantic differences 158 between these methods and a normal mapping (i.e. dictionary) interface. For 159 example, in a dictionary there are no duplicate keys, but here there may be 160 duplicate message headers. Also, in dictionaries there is no guaranteed 161 order to the keys returned by :meth:`keys`, but in an :class:`EmailMessage` 162 object, headers are always returned in the order they appeared in the 163 original message, or in which they were added to the message later. Any 164 header deleted and then re-added is always appended to the end of the 165 header list. 166 167 These semantic differences are intentional and are biased toward 168 convenience in the most common use cases. 169 170 Note that in all cases, any envelope header present in the message is not 171 included in the mapping interface. 172 173 174 .. method:: __len__() 175 176 Return the total number of headers, including duplicates. 177 178 179 .. method:: __contains__(name) 180 181 Return ``True`` if the message object has a field named *name*. Matching is 182 done without regard to case and *name* does not include the trailing 183 colon. Used for the ``in`` operator. For example:: 184 185 if 'message-id' in myMessage: 186 print('Message-ID:', myMessage['message-id']) 187 188 189 .. method:: __getitem__(name) 190 191 Return the value of the named header field. *name* does not include the 192 colon field separator. If the header is missing, ``None`` is returned; a 193 :exc:`KeyError` is never raised. 194 195 Note that if the named field appears more than once in the message's 196 headers, exactly which of those field values will be returned is 197 undefined. Use the :meth:`get_all` method to get the values of all the 198 extant headers named *name*. 199 200 Using the standard (non-``compat32``) policies, the returned value is an 201 instance of a subclass of :class:`email.headerregistry.BaseHeader`. 202 203 204 .. method:: __setitem__(name, val) 205 206 Add a header to the message with field name *name* and value *val*. The 207 field is appended to the end of the message's existing headers. 208 209 Note that this does *not* overwrite or delete any existing header with the same 210 name. If you want to ensure that the new header is the only one present in the 211 message with field name *name*, delete the field first, e.g.:: 212 213 del msg['subject'] 214 msg['subject'] = 'Python roolz!' 215 216 If the :mod:`policy` defines certain headers to be unique (as the standard 217 policies do), this method may raise a :exc:`ValueError` when an attempt 218 is made to assign a value to such a header when one already exists. This 219 behavior is intentional for consistency's sake, but do not depend on it 220 as we may choose to make such assignments do an automatic deletion of the 221 existing header in the future. 222 223 224 .. method:: __delitem__(name) 225 226 Delete all occurrences of the field with name *name* from the message's 227 headers. No exception is raised if the named field isn't present in the 228 headers. 229 230 231 .. method:: keys() 232 233 Return a list of all the message's header field names. 234 235 236 .. method:: values() 237 238 Return a list of all the message's field values. 239 240 241 .. method:: items() 242 243 Return a list of 2-tuples containing all the message's field headers and 244 values. 245 246 247 .. method:: get(name, failobj=None) 248 249 Return the value of the named header field. This is identical to 250 :meth:`__getitem__` except that optional *failobj* is returned if the 251 named header is missing (*failobj* defaults to ``None``). 252 253 254 Here are some additional useful header related methods: 255 256 257 .. method:: get_all(name, failobj=None) 258 259 Return a list of all the values for the field named *name*. If there are 260 no such named headers in the message, *failobj* is returned (defaults to 261 ``None``). 262 263 264 .. method:: add_header(_name, _value, **_params) 265 266 Extended header setting. This method is similar to :meth:`__setitem__` 267 except that additional header parameters can be provided as keyword 268 arguments. *_name* is the header field to add and *_value* is the 269 *primary* value for the header. 270 271 For each item in the keyword argument dictionary *_params*, the key is 272 taken as the parameter name, with underscores converted to dashes (since 273 dashes are illegal in Python identifiers). Normally, the parameter will 274 be added as ``key="value"`` unless the value is ``None``, in which case 275 only the key will be added. 276 277 If the value contains non-ASCII characters, the charset and language may 278 be explicitly controlled by specifying the value as a three tuple in the 279 format ``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string 280 naming the charset to be used to encode the value, ``LANGUAGE`` can 281 usually be set to ``None`` or the empty string (see :rfc:`2231` for other 282 possibilities), and ``VALUE`` is the string value containing non-ASCII 283 code points. If a three tuple is not passed and the value contains 284 non-ASCII characters, it is automatically encoded in :rfc:`2231` format 285 using a ``CHARSET`` of ``utf-8`` and a ``LANGUAGE`` of ``None``. 286 287 Here is an example:: 288 289 msg.add_header('Content-Disposition', 'attachment', filename='bud.gif') 290 291 This will add a header that looks like :: 292 293 Content-Disposition: attachment; filename="bud.gif" 294 295 An example of the extended interface with non-ASCII characters:: 296 297 msg.add_header('Content-Disposition', 'attachment', 298 filename=('iso-8859-1', '', 'Fußballer.ppt')) 299 300 301 .. method:: replace_header(_name, _value) 302 303 Replace a header. Replace the first header found in the message that 304 matches *_name*, retaining header order and field name case of the 305 original header. If no matching header is found, raise a 306 :exc:`KeyError`. 307 308 309 .. method:: get_content_type() 310 311 Return the message's content type, coerced to lower case of the form 312 :mimetype:`maintype/subtype`. If there is no :mailheader:`Content-Type` 313 header in the message return the value returned by 314 :meth:`get_default_type`. If the :mailheader:`Content-Type` header is 315 invalid, return ``text/plain``. 316 317 (According to :rfc:`2045`, messages always have a default type, 318 :meth:`get_content_type` will always return a value. :rfc:`2045` defines 319 a message's default type to be :mimetype:`text/plain` unless it appears 320 inside a :mimetype:`multipart/digest` container, in which case it would 321 be :mimetype:`message/rfc822`. If the :mailheader:`Content-Type` header 322 has an invalid type specification, :rfc:`2045` mandates that the default 323 type be :mimetype:`text/plain`.) 324 325 326 .. method:: get_content_maintype() 327 328 Return the message's main content type. This is the :mimetype:`maintype` 329 part of the string returned by :meth:`get_content_type`. 330 331 332 .. method:: get_content_subtype() 333 334 Return the message's sub-content type. This is the :mimetype:`subtype` 335 part of the string returned by :meth:`get_content_type`. 336 337 338 .. method:: get_default_type() 339 340 Return the default content type. Most messages have a default content 341 type of :mimetype:`text/plain`, except for messages that are subparts of 342 :mimetype:`multipart/digest` containers. Such subparts have a default 343 content type of :mimetype:`message/rfc822`. 344 345 346 .. method:: set_default_type(ctype) 347 348 Set the default content type. *ctype* should either be 349 :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is 350 not enforced. The default content type is not stored in the 351 :mailheader:`Content-Type` header, so it only affects the return value of 352 the ``get_content_type`` methods when no :mailheader:`Content-Type` 353 header is present in the message. 354 355 356 .. method:: set_param(param, value, header='Content-Type', requote=True, \ 357 charset=None, language='', replace=False) 358 359 Set a parameter in the :mailheader:`Content-Type` header. If the 360 parameter already exists in the header, replace its value with *value*. 361 When *header* is ``Content-Type`` (the default) and the header does not 362 yet exist in the message, add it, set its value to 363 :mimetype:`text/plain`, and append the new parameter value. Optional 364 *header* specifies an alternative header to :mailheader:`Content-Type`. 365 366 If the value contains non-ASCII characters, the charset and language may 367 be explicitly specified using the optional *charset* and *language* 368 parameters. Optional *language* specifies the :rfc:`2231` language, 369 defaulting to the empty string. Both *charset* and *language* should be 370 strings. The default is to use the ``utf8`` *charset* and ``None`` for 371 the *language*. 372 373 If *replace* is ``False`` (the default) the header is moved to the 374 end of the list of headers. If *replace* is ``True``, the header 375 will be updated in place. 376 377 Use of the *requote* parameter with :class:`EmailMessage` objects is 378 deprecated. 379 380 Note that existing parameter values of headers may be accessed through 381 the :attr:`~email.headerregistry.BaseHeader.params` attribute of the 382 header value (for example, ``msg['Content-Type'].params['charset']``). 383 384 .. versionchanged:: 3.4 ``replace`` keyword was added. 385 386 387 .. method:: del_param(param, header='content-type', requote=True) 388 389 Remove the given parameter completely from the :mailheader:`Content-Type` 390 header. The header will be re-written in place without the parameter or 391 its value. Optional *header* specifies an alternative to 392 :mailheader:`Content-Type`. 393 394 Use of the *requote* parameter with :class:`EmailMessage` objects is 395 deprecated. 396 397 398 .. method:: get_filename(failobj=None) 399 400 Return the value of the ``filename`` parameter of the 401 :mailheader:`Content-Disposition` header of the message. If the header 402 does not have a ``filename`` parameter, this method falls back to looking 403 for the ``name`` parameter on the :mailheader:`Content-Type` header. If 404 neither is found, or the header is missing, then *failobj* is returned. 405 The returned string will always be unquoted as per 406 :func:`email.utils.unquote`. 407 408 409 .. method:: get_boundary(failobj=None) 410 411 Return the value of the ``boundary`` parameter of the 412 :mailheader:`Content-Type` header of the message, or *failobj* if either 413 the header is missing, or has no ``boundary`` parameter. The returned 414 string will always be unquoted as per :func:`email.utils.unquote`. 415 416 417 .. method:: set_boundary(boundary) 418 419 Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to 420 *boundary*. :meth:`set_boundary` will always quote *boundary* if 421 necessary. A :exc:`~email.errors.HeaderParseError` is raised if the 422 message object has no :mailheader:`Content-Type` header. 423 424 Note that using this method is subtly different from deleting the old 425 :mailheader:`Content-Type` header and adding a new one with the new 426 boundary via :meth:`add_header`, because :meth:`set_boundary` preserves 427 the order of the :mailheader:`Content-Type` header in the list of 428 headers. 429 430 431 .. method:: get_content_charset(failobj=None) 432 433 Return the ``charset`` parameter of the :mailheader:`Content-Type` header, 434 coerced to lower case. If there is no :mailheader:`Content-Type` header, or if 435 that header has no ``charset`` parameter, *failobj* is returned. 436 437 438 .. method:: get_charsets(failobj=None) 439 440 Return a list containing the character set names in the message. If the 441 message is a :mimetype:`multipart`, then the list will contain one element 442 for each subpart in the payload, otherwise, it will be a list of length 1. 443 444 Each item in the list will be a string which is the value of the 445 ``charset`` parameter in the :mailheader:`Content-Type` header for the 446 represented subpart. If the subpart has no :mailheader:`Content-Type` 447 header, no ``charset`` parameter, or is not of the :mimetype:`text` main 448 MIME type, then that item in the returned list will be *failobj*. 449 450 451 .. method:: is_attachment 452 453 Return ``True`` if there is a :mailheader:`Content-Disposition` header 454 and its (case insensitive) value is ``attachment``, ``False`` otherwise. 455 456 .. versionchanged:: 3.4.2 457 is_attachment is now a method instead of a property, for consistency 458 with :meth:`~email.message.Message.is_multipart`. 459 460 461 .. method:: get_content_disposition() 462 463 Return the lowercased value (without parameters) of the message's 464 :mailheader:`Content-Disposition` header if it has one, or ``None``. The 465 possible values for this method are *inline*, *attachment* or ``None`` 466 if the message follows :rfc:`2183`. 467 468 .. versionadded:: 3.5 469 470 471 The following methods relate to interrogating and manipulating the content 472 (payload) of the message. 473 474 475 .. method:: walk() 476 477 The :meth:`walk` method is an all-purpose generator which can be used to 478 iterate over all the parts and subparts of a message object tree, in 479 depth-first traversal order. You will typically use :meth:`walk` as the 480 iterator in a ``for`` loop; each iteration returns the next subpart. 481 482 Here's an example that prints the MIME type of every part of a multipart 483 message structure: 484 485 .. testsetup:: 486 487 from email import message_from_binary_file 488 with open('../Lib/test/test_email/data/msg_16.txt', 'rb') as f: 489 msg = message_from_binary_file(f) 490 491 .. doctest:: 492 493 >>> for part in msg.walk(): 494 ... print(part.get_content_type()) 495 multipart/report 496 text/plain 497 message/delivery-status 498 text/plain 499 text/plain 500 message/rfc822 501 text/plain 502 503 ``walk`` iterates over the subparts of any part where 504 :meth:`is_multipart` returns ``True``, even though 505 ``msg.get_content_maintype() == 'multipart'`` may return ``False``. We 506 can see this in our example by making use of the ``_structure`` debug 507 helper function: 508 509 .. doctest:: 510 511 >>> from email.iterators import _structure 512 >>> for part in msg.walk(): 513 ... print(part.get_content_maintype() == 'multipart', 514 ... part.is_multipart()) 515 True True 516 False False 517 False True 518 False False 519 False False 520 False True 521 False False 522 >>> _structure(msg) 523 multipart/report 524 text/plain 525 message/delivery-status 526 text/plain 527 text/plain 528 message/rfc822 529 text/plain 530 531 Here the ``message`` parts are not ``multiparts``, but they do contain 532 subparts. ``is_multipart()`` returns ``True`` and ``walk`` descends 533 into the subparts. 534 535 536 .. method:: get_body(preferencelist=('related', 'html', 'plain')) 537 538 Return the MIME part that is the best candidate to be the "body" of the 539 message. 540 541 *preferencelist* must be a sequence of strings from the set ``related``, 542 ``html``, and ``plain``, and indicates the order of preference for the 543 content type of the part returned. 544 545 Start looking for candidate matches with the object on which the 546 ``get_body`` method is called. 547 548 If ``related`` is not included in *preferencelist*, consider the root 549 part (or subpart of the root part) of any related encountered as a 550 candidate if the (sub-)part matches a preference. 551 552 When encountering a ``multipart/related``, check the ``start`` parameter 553 and if a part with a matching :mailheader:`Content-ID` is found, consider 554 only it when looking for candidate matches. Otherwise consider only the 555 first (default root) part of the ``multipart/related``. 556 557 If a part has a :mailheader:`Content-Disposition` header, only consider 558 the part a candidate match if the value of the header is ``inline``. 559 560 If none of the candidates matches any of the preferences in 561 *preferencelist*, return ``None``. 562 563 Notes: (1) For most applications the only *preferencelist* combinations 564 that really make sense are ``('plain',)``, ``('html', 'plain')``, and the 565 default ``('related', 'html', 'plain')``. (2) Because matching starts 566 with the object on which ``get_body`` is called, calling ``get_body`` on 567 a ``multipart/related`` will return the object itself unless 568 *preferencelist* has a non-default value. (3) Messages (or message parts) 569 that do not specify a :mailheader:`Content-Type` or whose 570 :mailheader:`Content-Type` header is invalid will be treated as if they 571 are of type ``text/plain``, which may occasionally cause ``get_body`` to 572 return unexpected results. 573 574 575 .. method:: iter_attachments() 576 577 Return an iterator over all of the immediate sub-parts of the message 578 that are not candidate "body" parts. That is, skip the first occurrence 579 of each of ``text/plain``, ``text/html``, ``multipart/related``, or 580 ``multipart/alternative`` (unless they are explicitly marked as 581 attachments via :mailheader:`Content-Disposition: attachment`), and 582 return all remaining parts. When applied directly to a 583 ``multipart/related``, return an iterator over the all the related parts 584 except the root part (ie: the part pointed to by the ``start`` parameter, 585 or the first part if there is no ``start`` parameter or the ``start`` 586 parameter doesn't match the :mailheader:`Content-ID` of any of the 587 parts). When applied directly to a ``multipart/alternative`` or a 588 non-``multipart``, return an empty iterator. 589 590 591 .. method:: iter_parts() 592 593 Return an iterator over all of the immediate sub-parts of the message, 594 which will be empty for a non-``multipart``. (See also 595 :meth:`~email.message.EmailMessage.walk`.) 596 597 598 .. method:: get_content(*args, content_manager=None, **kw) 599 600 Call the :meth:`~email.contentmanager.ContentManager.get_content` method 601 of the *content_manager*, passing self as the message object, and passing 602 along any other arguments or keywords as additional arguments. If 603 *content_manager* is not specified, use the ``content_manager`` specified 604 by the current :mod:`~email.policy`. 605 606 607 .. method:: set_content(*args, content_manager=None, **kw) 608 609 Call the :meth:`~email.contentmanager.ContentManager.set_content` method 610 of the *content_manager*, passing self as the message object, and passing 611 along any other arguments or keywords as additional arguments. If 612 *content_manager* is not specified, use the ``content_manager`` specified 613 by the current :mod:`~email.policy`. 614 615 616 .. method:: make_related(boundary=None) 617 618 Convert a non-``multipart`` message into a ``multipart/related`` message, 619 moving any existing :mailheader:`Content-` headers and payload into a 620 (new) first part of the ``multipart``. If *boundary* is specified, use 621 it as the boundary string in the multipart, otherwise leave the boundary 622 to be automatically created when it is needed (for example, when the 623 message is serialized). 624 625 626 .. method:: make_alternative(boundary=None) 627 628 Convert a non-``multipart`` or a ``multipart/related`` into a 629 ``multipart/alternative``, moving any existing :mailheader:`Content-` 630 headers and payload into a (new) first part of the ``multipart``. If 631 *boundary* is specified, use it as the boundary string in the multipart, 632 otherwise leave the boundary to be automatically created when it is 633 needed (for example, when the message is serialized). 634 635 636 .. method:: make_mixed(boundary=None) 637 638 Convert a non-``multipart``, a ``multipart/related``, or a 639 ``multipart-alternative`` into a ``multipart/mixed``, moving any existing 640 :mailheader:`Content-` headers and payload into a (new) first part of the 641 ``multipart``. If *boundary* is specified, use it as the boundary string 642 in the multipart, otherwise leave the boundary to be automatically 643 created when it is needed (for example, when the message is serialized). 644 645 646 .. method:: add_related(*args, content_manager=None, **kw) 647 648 If the message is a ``multipart/related``, create a new message 649 object, pass all of the arguments to its :meth:`set_content` method, 650 and :meth:`~email.message.Message.attach` it to the ``multipart``. If 651 the message is a non-``multipart``, call :meth:`make_related` and then 652 proceed as above. If the message is any other type of ``multipart``, 653 raise a :exc:`TypeError`. If *content_manager* is not specified, use 654 the ``content_manager`` specified by the current :mod:`~email.policy`. 655 If the added part has no :mailheader:`Content-Disposition` header, 656 add one with the value ``inline``. 657 658 659 .. method:: add_alternative(*args, content_manager=None, **kw) 660 661 If the message is a ``multipart/alternative``, create a new message 662 object, pass all of the arguments to its :meth:`set_content` method, and 663 :meth:`~email.message.Message.attach` it to the ``multipart``. If the 664 message is a non-``multipart`` or ``multipart/related``, call 665 :meth:`make_alternative` and then proceed as above. If the message is 666 any other type of ``multipart``, raise a :exc:`TypeError`. If 667 *content_manager* is not specified, use the ``content_manager`` specified 668 by the current :mod:`~email.policy`. 669 670 671 .. method:: add_attachment(*args, content_manager=None, **kw) 672 673 If the message is a ``multipart/mixed``, create a new message object, 674 pass all of the arguments to its :meth:`set_content` method, and 675 :meth:`~email.message.Message.attach` it to the ``multipart``. If the 676 message is a non-``multipart``, ``multipart/related``, or 677 ``multipart/alternative``, call :meth:`make_mixed` and then proceed as 678 above. If *content_manager* is not specified, use the ``content_manager`` 679 specified by the current :mod:`~email.policy`. If the added part 680 has no :mailheader:`Content-Disposition` header, add one with the value 681 ``attachment``. This method can be used both for explicit attachments 682 (:mailheader:`Content-Disposition: attachment`) and ``inline`` attachments 683 (:mailheader:`Content-Disposition: inline`), by passing appropriate 684 options to the ``content_manager``. 685 686 687 .. method:: clear() 688 689 Remove the payload and all of the headers. 690 691 692 .. method:: clear_content() 693 694 Remove the payload and all of the :exc:`Content-` headers, leaving 695 all other headers intact and in their original order. 696 697 698 :class:`EmailMessage` objects have the following instance attributes: 699 700 701 .. attribute:: preamble 702 703 The format of a MIME document allows for some text between the blank line 704 following the headers, and the first multipart boundary string. Normally, 705 this text is never visible in a MIME-aware mail reader because it falls 706 outside the standard MIME armor. However, when viewing the raw text of 707 the message, or when viewing the message in a non-MIME aware reader, this 708 text can become visible. 709 710 The *preamble* attribute contains this leading extra-armor text for MIME 711 documents. When the :class:`~email.parser.Parser` discovers some text 712 after the headers but before the first boundary string, it assigns this 713 text to the message's *preamble* attribute. When the 714 :class:`~email.generator.Generator` is writing out the plain text 715 representation of a MIME message, and it finds the 716 message has a *preamble* attribute, it will write this text in the area 717 between the headers and the first boundary. See :mod:`email.parser` and 718 :mod:`email.generator` for details. 719 720 Note that if the message object has no preamble, the *preamble* attribute 721 will be ``None``. 722 723 724 .. attribute:: epilogue 725 726 The *epilogue* attribute acts the same way as the *preamble* attribute, 727 except that it contains text that appears between the last boundary and 728 the end of the message. As with the :attr:`~EmailMessage.preamble`, 729 if there is no epilog text this attribute will be ``None``. 730 731 732 .. attribute:: defects 733 734 The *defects* attribute contains a list of all the problems found when 735 parsing this message. See :mod:`email.errors` for a detailed description 736 of the possible parsing defects. 737 738 739.. class:: MIMEPart(policy=default) 740 741 This class represents a subpart of a MIME message. It is identical to 742 :class:`EmailMessage`, except that no :mailheader:`MIME-Version` headers are 743 added when :meth:`~EmailMessage.set_content` is called, since sub-parts do 744 not need their own :mailheader:`MIME-Version` headers. 745 746 747.. rubric:: Footnotes 748 749.. [1] Originally added in 3.4 as a :term:`provisional module <provisional 750 package>`. Docs for legacy message class moved to 751 :ref:`compat32_message`. 752
