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