Adding an example of reproducing the rfc822.Message() parsing.

Doc/includes/email-headers.py

+# Import the email modules we'll need
+from email.parser import Parser
+
+#  If the e-mail headers are in a file, uncomment this line:
+#headers = Parser().parse(messagefile)
+
+#  Or for parsing headers in a string, use:
+headers = Parser().parsestr('From: <user@example.com>\n'
+        'To: <someone_else@example.com>\n'
+        'Subject: Test message\n'
+        '\n'
+        'Body would go here\n')
+
+#  Now the header items can be accessed as a dictionary:
+print 'To: %s' % headers['to']
+print 'From: %s' % headers['from']
+print 'Subject: %s' % headers['subject']

Doc/library/email-examples.rst

@@ -11,6 +11,12 @@ First, let's see how to create and send a simple text message:
 .. literalinclude:: ../includes/email-simple.py
 
 
+And parsing RFC822 headers can easily be done by the parse(filename) or
+parsestr(message_as_string) methods of the Parser() class:
+
+.. literalinclude:: ../includes/email-headers.py
+
+
 Here's an example of how to send a MIME message containing a bunch of family
 pictures that may be residing in a directory: