Doc/library/email.message.rst

   1 :mod:`email`: Representing an email message
   2 -------------------------------------------
   3
   4 .. module:: email.message
   5    :synopsis: The base class representing email messages.
   6
   7
   8 The central class in the :mod:`email` package is the :class:`Message` class,
   9 imported from the :mod:`email.message` module.  It is the base class for the
  10 :mod:`email` object model.  :class:`Message` provides the core functionality for
  11 setting and querying header fields, and for accessing message bodies.
  12
  13 Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
  14 Headers are :rfc:`2822` style field names and values where the field name and
  15 value are separated by a colon.  The colon is not part of either the field name
  16 or the field value.
  17
  18 Headers are stored and returned in case-preserving form but are matched
  19 case-insensitively.  There may also be a single envelope header, also known as
  20 the *Unix-From* header or the ``From_`` header.  The payload is either a string
  21 in the case of simple message objects or a list of :class:`Message` objects for
  22 MIME container documents (e.g. :mimetype:`multipart/\*` and
  23 :mimetype:`message/rfc822`).
  24
  25 :class:`Message` objects provide a mapping style interface for accessing the
  26 message headers, and an explicit interface for accessing both the headers and
  27 the payload.  It provides convenience methods for generating a flat text
  28 representation of the message object tree, for accessing commonly used header
  29 parameters, and for recursively walking over the object tree.
  30
  31 Here are the methods of the :class:`Message` class:
  32
  33
  34 .. class:: Message()
  35
  36    The constructor takes no arguments.
  37
  38
  39    .. method:: as_string([unixfrom])
  40
  41       Return the entire message flattened as a string.  When optional *unixfrom*
  42       is ``True``, the envelope header is included in the returned string.
  43       *unixfrom* defaults to ``False``.
  44
  45       Note that this method is provided as a convenience and may not always
  46       format the message the way you want.  For example, by default it mangles
  47       lines that begin with ``From``.  For more flexibility, instantiate a
  48       :class:`Generator` instance and use its :meth:`flatten` method directly.
  49       For example::
  50
  51          from cStringIO import StringIO
  52          from email.generator import Generator
  53          fp = StringIO()
  54          g = Generator(fp, mangle_from_=False, maxheaderlen=60)
  55          g.flatten(msg)
  56          text = fp.getvalue()
  57
  58
  59    .. method:: __str__()
  60
  61       Equivalent to ``as_string(unixfrom=True)``.
  62
  63
  64    .. method:: is_multipart()
  65
  66       Return ``True`` if the message's payload is a list of sub-\
  67       :class:`Message` objects, otherwise return ``False``.  When
  68       :meth:`is_multipart` returns False, the payload should be a string object.
  69
  70
  71    .. method:: set_unixfrom(unixfrom)
  72
  73       Set the message's envelope header to *unixfrom*, which should be a string.
  74
  75
  76    .. method:: get_unixfrom()
  77
  78       Return the message's envelope header.  Defaults to ``None`` if the
  79       envelope header was never set.
  80
  81
  82    .. method:: attach(payload)
  83
  84       Add the given *payload* to the current payload, which must be ``None`` or
  85       a list of :class:`Message` objects before the call. After the call, the
  86       payload will always be a list of :class:`Message` objects.  If you want to
  87       set the payload to a scalar object (e.g. a string), use
  88       :meth:`set_payload` instead.
  89
  90
  91    .. method:: get_payload([i[, decode]])
  92
  93       Return a reference the current payload, which will be a list of
  94       :class:`Message` objects when :meth:`is_multipart` is ``True``, or a
  95       string when :meth:`is_multipart` is ``False``.  If the payload is a list
  96       and you mutate the list object, you modify the message's payload in place.
  97
  98       With optional argument *i*, :meth:`get_payload` will return the *i*-th
  99       element of the payload, counting from zero, if :meth:`is_multipart` is
 100       ``True``.  An :exc:`IndexError` will be raised if *i* is less than 0 or
 101       greater than or equal to the number of items in the payload.  If the
 102       payload is a string (i.e.  :meth:`is_multipart` is ``False``) and *i* is
 103       given, a :exc:`TypeError` is raised.
 104
 105       Optional *decode* is a flag indicating whether the payload should be
 106       decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
 107       header. When ``True`` and the message is not a multipart, the payload will
 108       be decoded if this header's value is ``quoted-printable`` or ``base64``.
 109       If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
 110       header is missing, or if the payload has bogus base64 data, the payload is
 111       returned as-is (undecoded).  If the message is a multipart and the
 112       *decode* flag is ``True``, then ``None`` is returned.  The default for
 113       *decode* is ``False``.
 114
 115
 116    .. method:: set_payload(payload[, charset])
 117
 118       Set the entire message object's payload to *payload*.  It is the client's
 119       responsibility to ensure the payload invariants.  Optional *charset* sets
 120       the message's default character set; see :meth:`set_charset` for details.
 121
 122       .. versionchanged:: 2.2.2
 123          *charset* argument added.
 124
 125
 126    .. method:: set_charset(charset)
 127
 128       Set the character set of the payload to *charset*, which can either be a
 129       :class:`Charset` instance (see :mod:`email.charset`), a string naming a
 130       character set, or ``None``.  If it is a string, it will be converted to a
 131       :class:`Charset` instance.  If *charset* is ``None``, the ``charset``
 132       parameter will be removed from the :mailheader:`Content-Type`
 133       header. Anything else will generate a :exc:`TypeError`.
 134
 135       The message will be assumed to be of type :mimetype:`text/\*` encoded with
 136       *charset.input_charset*.  It will be converted to *charset.output_charset*
 137       and encoded properly, if needed, when generating the plain text
 138       representation of the message.  MIME headers (:mailheader:`MIME-Version`,
 139       :mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
 140       be added as needed.
 141
 142       .. versionadded:: 2.2.2
 143
 144
 145    .. method:: get_charset()
 146
 147       Return the :class:`Charset` instance associated with the message's
 148       payload.
 149
 150       .. versionadded:: 2.2.2
 151
 152    The following methods implement a mapping-like interface for accessing the
 153    message's :rfc:`2822` headers.  Note that there are some semantic differences
 154    between these methods and a normal mapping (i.e. dictionary) interface.  For
 155    example, in a dictionary there are no duplicate keys, but here there may be
 156    duplicate message headers.  Also, in dictionaries there is no guaranteed
 157    order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
 158    headers are always returned in the order they appeared in the original
 159    message, or were added to the message later.  Any header deleted and then
 160    re-added are always appended to the end of the header list.
 161
 162    These semantic differences are intentional and are biased toward maximal
 163    convenience.
 164
 165    Note that in all cases, any envelope header present in the message is not
 166    included in the mapping interface.
 167
 168
 169    .. method:: __len__()
 170
 171       Return the total number of headers, including duplicates.
 172
 173
 174    .. method:: __contains__(name)
 175
 176       Return true if the message object has a field named *name*. Matching is
 177       done case-insensitively and *name* should not include the trailing colon.
 178       Used for the ``in`` operator, e.g.::
 179
 180          if 'message-id' in myMessage:
 181              print 'Message-ID:', myMessage['message-id']
 182
 183
 184    .. method:: __getitem__(name)
 185
 186       Return the value of the named header field.  *name* should not include the
 187       colon field separator.  If the header is missing, ``None`` is returned; a
 188       :exc:`KeyError` is never raised.
 189
 190       Note that if the named field appears more than once in the message's
 191       headers, exactly which of those field values will be returned is
 192       undefined.  Use the :meth:`get_all` method to get the values of all the
 193       extant named headers.
 194
 195
 196    .. method:: __setitem__(name, val)
 197
 198       Add a header to the message with field name *name* and value *val*.  The
 199       field is appended to the end of the message's existing fields.
 200
 201       Note that this does *not* overwrite or delete any existing header with the same
 202       name.  If you want to ensure that the new header is the only one present in the
 203       message with field name *name*, delete the field first, e.g.::
 204
 205          del msg['subject']
 206          msg['subject'] = 'Python roolz!'
 207
 208
 209    .. method:: __delitem__(name)
 210
 211       Delete all occurrences of the field with name *name* from the message's
 212       headers.  No exception is raised if the named field isn't present in the headers.
 213
 214
 215    .. method:: has_key(name)
 216
 217       Return true if the message contains a header field named *name*, otherwise
 218       return false.
 219
 220
 221    .. method:: keys()
 222
 223       Return a list of all the message's header field names.
 224
 225
 226    .. method:: values()
 227
 228       Return a list of all the message's field values.
 229
 230
 231    .. method:: items()
 232
 233       Return a list of 2-tuples containing all the message's field headers and
 234       values.
 235
 236
 237    .. method:: get(name[, failobj])
 238
 239       Return the value of the named header field.  This is identical to
 240       :meth:`__getitem__` except that optional *failobj* is returned if the
 241       named header is missing (defaults to ``None``).
 242
 243    Here are some additional useful methods:
 244
 245
 246    .. method:: get_all(name[, failobj])
 247
 248       Return a list of all the values for the field named *name*. If there are
 249       no such named headers in the message, *failobj* is returned (defaults to
 250       ``None``).
 251
 252
 253    .. method:: add_header(_name, _value, **_params)
 254
 255       Extended header setting.  This method is similar to :meth:`__setitem__`
 256       except that additional header parameters can be provided as keyword
 257       arguments.  *_name* is the header field to add and *_value* is the
 258       *primary* value for the header.
 259
 260       For each item in the keyword argument dictionary *_params*, the key is
 261       taken as the parameter name, with underscores converted to dashes (since
 262       dashes are illegal in Python identifiers).  Normally, the parameter will
 263       be added as ``key="value"`` unless the value is ``None``, in which case
 264       only the key will be added.
 265
 266       Here's an example::
 267
 268          msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
 269
 270       This will add a header that looks like ::
 271
 272          Content-Disposition: attachment; filename="bud.gif"
 273
 274
 275    .. method:: replace_header(_name, _value)
 276
 277       Replace a header.  Replace the first header found in the message that
 278       matches *_name*, retaining header order and field name case.  If no
 279       matching header was found, a :exc:`KeyError` is raised.
 280
 281       .. versionadded:: 2.2.2
 282
 283
 284    .. method:: get_content_type()
 285
 286       Return the message's content type.  The returned string is coerced to
 287       lower case of the form :mimetype:`maintype/subtype`.  If there was no
 288       :mailheader:`Content-Type` header in the message the default type as given
 289       by :meth:`get_default_type` will be returned.  Since according to
 290       :rfc:`2045`, messages always have a default type, :meth:`get_content_type`
 291       will always return a value.
 292
 293       :rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
 294       unless it appears inside a :mimetype:`multipart/digest` container, in
 295       which case it would be :mimetype:`message/rfc822`.  If the
 296       :mailheader:`Content-Type` header has an invalid type specification,
 297       :rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
 298
 299       .. versionadded:: 2.2.2
 300
 301
 302    .. method:: get_content_maintype()
 303
 304       Return the message's main content type.  This is the :mimetype:`maintype`
 305       part of the string returned by :meth:`get_content_type`.
 306
 307       .. versionadded:: 2.2.2
 308
 309
 310    .. method:: get_content_subtype()
 311
 312       Return the message's sub-content type.  This is the :mimetype:`subtype`
 313       part of the string returned by :meth:`get_content_type`.
 314
 315       .. versionadded:: 2.2.2
 316
 317
 318    .. method:: get_default_type()
 319
 320       Return the default content type.  Most messages have a default content
 321       type of :mimetype:`text/plain`, except for messages that are subparts of
 322       :mimetype:`multipart/digest` containers.  Such subparts have a default
 323       content type of :mimetype:`message/rfc822`.
 324
 325       .. versionadded:: 2.2.2
 326
 327
 328    .. method:: set_default_type(ctype)
 329
 330       Set the default content type.  *ctype* should either be
 331       :mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
 332       enforced.  The default content type is not stored in the
 333       :mailheader:`Content-Type` header.
 334
 335       .. versionadded:: 2.2.2
 336
 337
 338    .. method:: get_params([failobj[, header[, unquote]]])
 339
 340       Return the message's :mailheader:`Content-Type` parameters, as a list.
 341       The elements of the returned list are 2-tuples of key/value pairs, as
 342       split on the ``'='`` sign.  The left hand side of the ``'='`` is the key,
 343       while the right hand side is the value.  If there is no ``'='`` sign in
 344       the parameter the value is the empty string, otherwise the value is as
 345       described in :meth:`get_param` and is unquoted if optional *unquote* is
 346       ``True`` (the default).
 347
 348       Optional *failobj* is the object to return if there is no
 349       :mailheader:`Content-Type` header.  Optional *header* is the header to
 350       search instead of :mailheader:`Content-Type`.
 351
 352       .. versionchanged:: 2.2.2
 353          *unquote* argument added.
 354
 355
 356    .. method:: get_param(param[, failobj[, header[, unquote]]])
 357
 358       Return the value of the :mailheader:`Content-Type` header's parameter
 359       *param* as a string.  If the message has no :mailheader:`Content-Type`
 360       header or if there is no such parameter, then *failobj* is returned
 361       (defaults to ``None``).
 362
 363       Optional *header* if given, specifies the message header to use instead of
 364       :mailheader:`Content-Type`.
 365
 366       Parameter keys are always compared case insensitively.  The return value
 367       can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
 368       encoded.  When it's a 3-tuple, the elements of the value are of the form
 369       ``(CHARSET, LANGUAGE, VALUE)``.  Note that both ``CHARSET`` and
 370       ``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
 371       to be encoded in the ``us-ascii`` charset.  You can usually ignore
 372       ``LANGUAGE``.
 373
 374       If your application doesn't care whether the parameter was encoded as in
 375       :rfc:`2231`, you can collapse the parameter value by calling
 376       :func:`email.Utils.collapse_rfc2231_value`, passing in the return value
 377       from :meth:`get_param`.  This will return a suitably decoded Unicode
 378       string whn the value is a tuple, or the original string unquoted if it
 379       isn't.  For example::
 380
 381          rawparam = msg.get_param('foo')
 382          param = email.Utils.collapse_rfc2231_value(rawparam)
 383
 384       In any case, the parameter value (either the returned string, or the
 385       ``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
 386       to ``False``.
 387
 388       .. versionchanged:: 2.2.2
 389          *unquote* argument added, and 3-tuple return value possible.
 390
 391
 392    .. method:: set_param(param, value[, header[, requote[, charset[, language]]]])
 393
 394       Set a parameter in the :mailheader:`Content-Type` header.  If the
 395       parameter already exists in the header, its value will be replaced with
 396       *value*.  If the :mailheader:`Content-Type` header as not yet been defined
 397       for this message, it will be set to :mimetype:`text/plain` and the new
 398       parameter value will be appended as per :rfc:`2045`.
 399
 400       Optional *header* specifies an alternative header to
 401       :mailheader:`Content-Type`, and all parameters will be quoted as necessary
 402       unless optional *requote* is ``False`` (the default is ``True``).
 403
 404       If optional *charset* is specified, the parameter will be encoded
 405       according to :rfc:`2231`. Optional *language* specifies the RFC 2231
 406       language, defaulting to the empty string.  Both *charset* and *language*
 407       should be strings.
 408
 409       .. versionadded:: 2.2.2
 410
 411
 412    .. method:: del_param(param[, header[, requote]])
 413
 414       Remove the given parameter completely from the :mailheader:`Content-Type`
 415       header.  The header will be re-written in place without the parameter or
 416       its value.  All values will be quoted as necessary unless *requote* is
 417       ``False`` (the default is ``True``).  Optional *header* specifies an
 418       alternative to :mailheader:`Content-Type`.
 419
 420       .. versionadded:: 2.2.2
 421
 422
 423    .. method:: set_type(type[, header][, requote])
 424
 425       Set the main type and subtype for the :mailheader:`Content-Type`
 426       header. *type* must be a string in the form :mimetype:`maintype/subtype`,
 427       otherwise a :exc:`ValueError` is raised.
 428
 429       This method replaces the :mailheader:`Content-Type` header, keeping all
 430       the parameters in place.  If *requote* is ``False``, this leaves the
 431       existing header's quoting as is, otherwise the parameters will be quoted
 432       (the default).
 433
 434       An alternative header can be specified in the *header* argument. When the
 435       :mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
 436       header is also added.
 437
 438       .. versionadded:: 2.2.2
 439
 440
 441    .. method:: get_filename([failobj])
 442
 443       Return the value of the ``filename`` parameter of the
 444       :mailheader:`Content-Disposition` header of the message.  If the header
 445       does not have a ``filename`` parameter, this method falls back to looking
 446       for the ``name`` parameter.  If neither is found, or the header is
 447       missing, then *failobj* is returned.  The returned string will always be
 448       unquoted as per :meth:`Utils.unquote`.
 449
 450
 451    .. method:: get_boundary([failobj])
 452
 453       Return the value of the ``boundary`` parameter of the
 454       :mailheader:`Content-Type` header of the message, or *failobj* if either
 455       the header is missing, or has no ``boundary`` parameter.  The returned
 456       string will always be unquoted as per :meth:`Utils.unquote`.
 457
 458
 459    .. method:: set_boundary(boundary)
 460
 461       Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
 462       *boundary*.  :meth:`set_boundary` will always quote *boundary* if
 463       necessary.  A :exc:`HeaderParseError` is raised if the message object has
 464       no :mailheader:`Content-Type` header.
 465
 466       Note that using this method is subtly different than deleting the old
 467       :mailheader:`Content-Type` header and adding a new one with the new
 468       boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
 469       the order of the :mailheader:`Content-Type` header in the list of
 470       headers. However, it does *not* preserve any continuation lines which may
 471       have been present in the original :mailheader:`Content-Type` header.
 472
 473
 474    .. method:: get_content_charset([failobj])
 475
 476       Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
 477       coerced to lower case.  If there is no :mailheader:`Content-Type` header, or if
 478       that header has no ``charset`` parameter, *failobj* is returned.
 479
 480       Note that this method differs from :meth:`get_charset` which returns the
 481       :class:`Charset` instance for the default encoding of the message body.
 482
 483       .. versionadded:: 2.2.2
 484
 485
 486    .. method:: get_charsets([failobj])
 487
 488       Return a list containing the character set names in the message.  If the
 489       message is a :mimetype:`multipart`, then the list will contain one element
 490       for each subpart in the payload, otherwise, it will be a list of length 1.
 491
 492       Each item in the list will be a string which is the value of the
 493       ``charset`` parameter in the :mailheader:`Content-Type` header for the
 494       represented subpart.  However, if the subpart has no
 495       :mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
 496       the :mimetype:`text` main MIME type, then that item in the returned list
 497       will be *failobj*.
 498
 499
 500    .. method:: walk()
 501
 502       The :meth:`walk` method is an all-purpose generator which can be used to
 503       iterate over all the parts and subparts of a message object tree, in
 504       depth-first traversal order.  You will typically use :meth:`walk` as the
 505       iterator in a ``for`` loop; each iteration returns the next subpart.
 506
 507       Here's an example that prints the MIME type of every part of a multipart
 508       message structure::
 509
 510          >>> for part in msg.walk():
 511          ...     print part.get_content_type()
 512          multipart/report
 513          text/plain
 514          message/delivery-status
 515          text/plain
 516          text/plain
 517          message/rfc822
 518
 519    .. versionchanged:: 2.5
 520       The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
 521       :meth:`get_subtype` were removed.
 522
 523    :class:`Message` objects can also optionally contain two instance attributes,
 524    which can be used when generating the plain text of a MIME message.
 525
 526
 527    .. attribute:: preamble
 528
 529       The format of a MIME document allows for some text between the blank line
 530       following the headers, and the first multipart boundary string. Normally,
 531       this text is never visible in a MIME-aware mail reader because it falls
 532       outside the standard MIME armor.  However, when viewing the raw text of
 533       the message, or when viewing the message in a non-MIME aware reader, this
 534       text can become visible.
 535
 536       The *preamble* attribute contains this leading extra-armor text for MIME
 537       documents.  When the :class:`Parser` discovers some text after the headers
 538       but before the first boundary string, it assigns this text to the
 539       message's *preamble* attribute.  When the :class:`Generator` is writing
 540       out the plain text representation of a MIME message, and it finds the
 541       message has a *preamble* attribute, it will write this text in the area
 542       between the headers and the first boundary.  See :mod:`email.parser` and
 543       :mod:`email.generator` for details.
 544
 545       Note that if the message object has no preamble, the *preamble* attribute
 546       will be ``None``.
 547
 548
 549    .. attribute:: epilogue
 550
 551       The *epilogue* attribute acts the same way as the *preamble* attribute,
 552       except that it contains text that appears between the last boundary and
 553       the end of the message.
 554
 555       .. versionchanged:: 2.5
 556          You do not need to set the epilogue to the empty string in order for the
 557          :class:`Generator` to print a newline at the end of the file.
 558
 559
 560    .. attribute:: defects
 561
 562       The *defects* attribute contains a list of all the problems found when
 563       parsing this message.  See :mod:`email.errors` for a detailed description
 564       of the possible parsing defects.
 565
 566       .. versionadded:: 2.4
 567