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