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 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