Coming soon...
When creating Message objects from scratch, you often need to encode the payloads for transport through compliant mail servers. This is especially true for image/* and text/* type messages containing binary data.
The email package provides some convenient encodings in its Encoders module. These encoders are actually used by the MIMEImage and MIMEText class constructors to provide default encodings. All encoder functions take exactly one argument, the message object to encode. They usually extract the payload, encode it, and reset the payload to this newly encoded value. They should also set the Content-Transfer-Encoding: header as appropriate.
Here are the encoding functions provided:
Content-Transfer-Encoding:
header to
quoted-printable
12.4.
This is a good encoding to use when most of your payload is normal
printable data, but contains a few unprintable characters.
base64
. This is a good encoding to use when most of your payload
is unprintable data since it is a more compact form than
Quoted-Printable. The drawback of Base64 encoding is that it
renders the text non-human readable.
7bit
or
8bit
as appropriate, based on the payload data.
The following exception classes are defined in the email.Errors module:
Situations where it can be raised include finding a Unix-From header after the first RFC 2822 header of the message, finding a continuation line before the first RFC 2822 header is found, or finding a line in the headers which is neither a header or a continuation line.
Situations where it can be raised include not being able to find the starting or terminating boundary in a multipart/* message.
One of the most common tasks is to generate the flat text of the email message represented by a message object tree. You will need to do this if you want to send your message via the smtplib module or the nntplib module, or print the message on the console. Taking a message object tree and producing a flat text document is the job of the Generator class.
Again, as with the email.Parser module, you aren't limited to the functionality of the bundled generator; you could write one from scratch yourself. However the bundled generator knows how to generate most email in a standards-compliant way, should handle MIME and non-MIME email messages just fine, and is designed so that the transformation from flat text, to an object tree via the Parser class, and back to flat text, be idempotent (the input is identical to the output).
Here are the public methods of the Generator class:
Optional mangle_from_ is a flag that, when true, puts a ``>''
character in front of any line in the body that starts exactly as
"From " (i.e. From
followed by a space at the front of the
line). This is the only guaranteed portable way to avoid having such
lines be mistaken for Unix-From headers (see
WHY THE CONTENT-LENGTH FORMAT IS BAD
for details).
Optional maxheaderlen specifies the longest length for a non-continued header. When a header line is longer than maxheaderlen (in characters, with tabs expanded to 8 spaces), the header will be broken on semicolons and continued as per RFC 2822. If no semicolon is found, then the header is left alone. Set to zero to disable wrapping headers. Default is 78, as recommended (but not required) by RFC 2822.
The other public Generator methods are:
Optional unixfrom is a flag that forces the printing of the
Unix-From (a.k.a. envelope header or From_
header)
delimiter before the first RFC 2822 header of the root message
object. If the root object has no Unix-From header, a standard
one is crafted. By default, this is set to 0 to inhibit the printing
of the Unix-From delimiter.
Note that for sub-objects, no Unix-From header is ever printed.
As a convenience, see the methods Message.as_string() and
str(aMessage)
, a.k.a. Message.__str__(), which
simplify the generation of a formatted string representation of a
message object. For more detail, see email.Message.
Iterating over a message object tree is fairly easy with the Message.walk() method. The email.Iterators module provides some useful higher level iterations over message object trees.
Note that subtype is optional; if omitted, then subpart MIME type matching is done only with the main type. maintype is optional too; it defaults to text.
Thus, by default typed_subpart_iterator() returns each subpart that has a MIME type of text/*.
The central class in the email package is the Message class; it is the base class for the email object model. Message provides the core functionality for setting and querying header fields, and for accessing message bodies.
Conceptually, a Message object consists of headers and payloads. Headers are RFC 2822 style field names and values where the field name and value are separated by a colon. The colon is not part of either the field name or the field value.
Headers are stored and returned in case-preserving form but are
matched case-insensitively. There may also be a single
Unix-From header, also known as the envelope header or the
From_
header. The payload is either a string in the case of
simple message objects, a list of Message objects for
multipart MIME documents, or a single Message instance for
message/rfc822 type objects.
Message objects provide a mapping style interface for accessing the message headers, and an explicit interface for accessing both the headers and the payload. It provides convenience methods for generating a flat text representation of the message object tree, for accessing commonly used header parameters, and for recursively walking over the object tree.
Here are the methods of the Message class:
From_
header) to unixfrom, which should be a string.
None
if the
Unix-From header was never set.
None
(i.e. never before set), then after this method is called, the payload
will be the argument payload.
If the object's payload was already a list (i.e. is_multipart() returns 1), then payload is appended to the end of the existing payload list.
For any other type of existing payload, add_payload() will transform the new payload into a list consisting of the old payload and payload, but only if the document is already a MIME multipart document. This condition is satisfied if the message's Content-Type: header's main type is either multipart, or there is no Content-Type: header. In any other situation, MultipartConversionError is raised.
With optional i, get_payload() will return the i-th element of the payload, counting from zero, if is_multipart() returns 1. An IndexError will be raised if i is less than 0 or greater than or equal to the number of items in the payload. If the payload is scalar (i.e. is_multipart() returns 0) and i is given, a TypeError is raised.
Optional decode is a flag indicating whether the payload should be
decoded or not, according to the Content-Transfer-Encoding: header.
When true and the message is not a multipart, the payload will be
decoded if this header's value is "quoted-printable" or
"base64". If some other encoding is used, or
Content-Transfer-Encoding: header is
missing, the payload is returned as-is (undecoded). If the message is
a multipart and the decode flag is true, then None
is
returned.
The following methods implement a mapping-like interface for accessing the message object's RFC 2822 headers. Note that there are some semantic differences between these methods and a normal mapping (i.e. dictionary) interface. For example, in a dictionary there are no duplicate keys, but here there may be duplicate message headers. Also, in dictionaries there is no guaranteed order to the keys returned by keys(), but in a Message object, there is an explicit order. These semantic differences are intentional and are biased toward maximal convenience.
Note that in all cases, any optional Unix-From header the message may have is not included in the mapping interface.
in
operator,
e.g.:
if 'message-id' in myMessage: print 'Message-ID:', myMessage['message-id']
None
is returned; a KeyError is never raised.
Note that if the named field appears more than once in the message's headers, exactly which of those field values will be returned is undefined. Use the get_all() method to get the values of all the extant named headers.
Note that this does not overwrite or delete any existing header with the same name. If you want to ensure that the new header is the only one present in the message with field name name, first use __delitem__() to delete all named fields, e.g.:
del msg['subject'] msg['subject'] = 'Python roolz!'
None
).
Here are some additional useful methods:
If there are no such named headers in the message, failobj is
returned (defaults to None
).
For each item in the keyword argument dictionary _params, the
key is taken as the parameter name, with underscores converted to
dashes (since dashes are illegal in Python identifiers). Normally,
the parameter will be added as key="value"
unless the value is
None
, in which case only the key will be added.
Here's an example:
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
This will add a header that looks like
Content-Disposition: attachment; filename="bud.gif"
If there is no Content-Type: header in the message,
failobj is returned (defaults to None
).
Optional failobj is the object to return if there is no Content-Type: header. Optional header is the header to search instead of Content-Type:.
None
).
Optional header if given, specifies the message header to use instead of Content-Type:.
Each item in the list will be a string which is the value of the
charset
parameter in the Content-Type: header for the
represented subpart. However, if the subpart has no
Content-Type: header, no charset
parameter, or is not of
the text main MIME type, then that item in the returned list
will be failobj.
filename
parameter of the
Content-Disposition: header of the message, or failobj if
either the header is missing, or has no filename
parameter.
The returned string will always be unquoted as per
Utils.unquote().
boundary
parameter of the
Content-Type: header of the message, or failobj if either
the header is missing, or has no boundary
parameter. The
returned string will always be unquoted as per
Utils.unquote().
boundary
parameter of the Content-Type: header
to boundary. set_boundary() will always quote
boundary so you should not quote it yourself. A
HeaderParseError is raised if the message object has no
Content-Type: header.
Note that using this method is subtly different than deleting the old Content-Type: header and adding a new one with the new boundary via add_header(), because set_boundary() preserves the order of the Content-Type: header in the list of headers. However, it does not preserve any continuation lines which may have been present in the original Content-Type: header.
for ... in
loop; each
iteration returns the next subpart.
Here's an example that prints the MIME type of every part of a message object tree:
>>> for part in msg.walk(): >>> print part.get_type('text/plain') multipart/report text/plain message/delivery-status text/plain text/plain message/rfc822
Message objects can also optionally contain two instance attributes, which can be used when generating the plain text of a MIME message.
The preamble attribute contains this leading extra-armor text for MIME documents. When the Parser discovers some text after the headers but before the first boundary string, it assigns this text to the message's preamble attribute. When the Generator is writing out the plain text representation of a MIME message, and it finds the message has a preamble attribute, it will write this text in the area between the headers and the first boundary.
Note that if the message object has no preamble, the
preamble attribute will be None
.
Message object trees can be created in one of two ways: they can be created from whole cloth by instantiating Message objects and stringing them together via add_payload() and set_payload() calls, or they can be created by parsing a flat text representation of the email message.
The email package provides a standard parser that understands most email document structures, including MIME documents. You can pass the parser a string or a file object, and the parser will return to you the root Message instance of the object tree. For simple, non-MIME messages the payload of this root object will likely be a string containing the text of the message. For MIME messages, the root object will return true from its is_multipart() method, and the subparts can be accessed via the get_payload() and walk() methods.
Note that the parser can be extended in limited ways, and of course you can implement your own parser completely from scratch. There is no magical connection between the email package's bundled parser and the Message class, so your custom parser can create message object trees in any way it find necessary.
The primary parser class is Parser which parses both the headers and the payload of the message. In the case of multipart messages, it will recursively parse the body of the container message. The email.Parser module also provides a second class, called HeaderParser which can be used if you're only interested in the headers of the message. HeaderParser can be much faster in this situations, since it does not attempt to parse the message body, instead setting the payload to the raw body as a string. HeaderParser has the same API as the Parser class.