email2dict

Archived

This project has been archived by its maintainers, and is no longer receiving any updates.

Project Status: Active — The project has reached a stable, usable state and is being actively developed.

https://codecov.io/gh/jwodder/email2dict/branch/master/graph/badge.svg

https://img.shields.io/pypi/pyversions/email2dict.svg

GitHub | PyPI | Issues

Note: This project has been renamed to mailbits. Please see there for all future updates & new features.

email2dict converts Python Message & EmailMessage instances into structured dicts. Need to examine a Message but find the builtin Python API too fiddly? Need to check that a Message has the content & structure you expect? Need to compare two Message instances for equality? Need to pretty-print the structure of a Message? Then email2dict has your back.

Installation

email2dict requires Python 3.6 or higher. Just use pip for Python 3 (You have pip, right?) to install it:

python3 -m pip install email2dict

Example

The email examples page in the Python docs includes an example of constructing an HTML e-mail with an alternative plain text version (It’s the one with the subject “Ayons asperges pour le déjeuner”). Passing the resulting EmailMessage object to the email2dict() function produces the following output structure:

{
    "unixfrom": None,
    "headers": {
        "subject": "Ayons asperges pour le déjeuner",
        "from": [
            {
                "display_name": "Pepé Le Pew",
                "address": "pepe@example.com",
            },
        ],
        "to": [
            {
                "display_name": "Penelope Pussycat",
                "address": "penelope@example.com",
            },
            {
                "display_name": "Fabrette Pussycat",
                "address": "fabrette@example.com",
            },
        ],
        "content-type": {
            "content_type": "multipart/alternative",
            "params": {},
        },
    },
    "preamble": None,
    "content": [
        {
            "unixfrom": None,
            "headers": {
                "content-type": {
                    "content_type": "text/plain",
                    "params": {},
                },
            },
            "preamble": None,
            "content": (
                "Salut!\n"
                "\n"
                "Cela ressemble à un excellent recipie[1] déjeuner.\n"
                "\n"
                "[1] http://www.yummly.com/recipe/Roasted-Asparagus-Epicurious-203718\n"
                "\n"
                "--Pepé\n"
            ),
            "epilogue": None,
        },
        {
            "unixfrom": None,
            "headers": {
                "content-type": {
                    "content_type": "multipart/related",
                    "params": {},
                },
            },
            "preamble": None,
            "content": [
                {
                    "unixfrom": None,
                    "headers": {
                        "content-type": {
                            "content_type": "text/html",
                            "params": {},
                        },
                    },
                    "preamble": None,
                    "content": (
                        "<html>\n"
                        "  <head></head>\n"
                        "  <body>\n"
                        "    <p>Salut!</p>\n"
                        "    <p>Cela ressemble à un excellent\n"
                        "        <a href=\"http://www.yummly.com/recipe/Roasted-Asparagus-"
                        "Epicurious-203718\">\n"
                        "            recipie\n"
                        "        </a> déjeuner.\n"
                        "    </p>\n"
                        "    <img src=\"cid:RANDOM_MESSAGE_ID\" />\n"
                        "  </body>\n"
                        "</html>\n"
                    ),
                    "epilogue": None,
                },
                {
                    "unixfrom": None,
                    "headers": {
                        "content-type": {
                            "content_type": "image/png",
                            "params": {},
                        },
                        "content-disposition": {
                            "disposition": "inline",
                            "params": {},
                        },
                        "content-id": ["<RANDOM_MESSAGE_ID>"],
                    },
                    "preamble": None,
                    "content": b'IMAGE BLOB',
                    "epilogue": None,
                },
            ],
            "epilogue": None,
        },
    ],
    "epilogue": None,
}

API

The email2dict module provides a single function, also named email2dict:

email2dict(msg: email.message.Message, include_all: bool = False) -> Dict[str, Any]

Convert a Message object to a dict. All encoded text & bytes are decoded into their natural values.

By default, any information specific to how the message is encoded (Content-Type parameters, Content-Transfer-Encoding, etc.) is not reported, as the focus is on the actual content rather than the choices made in representing it. To include this information anyway, set include_all to True.

The output structure has the following fields:

unixfrom

The “From “ line marking the start of the message in a mbox, if any

headers

A dict mapping lowercased header field names to values. The following headers have special representations:

subject: A single string
from, to, cc, bcc, resent-from, resent-to, resent-cc, resent-bcc, reply-to: A list of groups and/or addresses. Addresses are represented as dicts with two string fields: display_name (an empty string if not given) and address. Groups are represented as dicts with a group field giving the name of the group and an addresses field giving a list of addresses in the group.
message-id: A single string
content-type: A dict containing a content_type field (a string of the form maintype/subtype, e.g., "text/plain") and a params field (a dict of string keys & values). The charset and boundary parameters are discarded unless include_all is True.
date: A datetime.datetime instance
orig-date: A datetime.datetime instance
resent-date: A list of datetime.datetime instances
sender: A single address dict
resent-sender: A list of address dicts
content-disposition: A dict containing a disposition field (value either "inline" or "attachment") and a params field (a dict of string keys & values)
content-transfer-encoding: A single string. This header is discarded unless include_all is True.
mime-version: A single string. This header is discarded unless include_all is True.

All other headers are represented as lists of strings.

preamble

The message’s preamble

content

If the message is multipart, this is a list of message dicts, structured the same way as the top-level dict. If the message’s Content-Type is message/rfc822 or message/external-body, this is a single message dict. If the message’s Content-Type is text/*, this is a str giving the contents of the message. Otherwise, it is a bytes giving the contents of the message.

epilogue

The message’s epilogue

Release files for email2dict 0.1.0.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for email2dict 0.1.0.post1
File	Size	Uploaded
email2dict-0.1.0.post1.tar.gz	28.4 kB	Mar 14, 2021	Details

Built distribution (wheel)

Table of built distributions (wheels) for email2dict 0.1.0.post1
File	Interpreter	ABI	Platform	Reset
email2dict-0.1.0.post1-py3-none-any.whl 7.7 kB Mar 14, 2021	Python 3	none	any	Details

Total release size: 36.1 kB

Release files / email2dict-0.1.0.post1.tar.gz

Download URL	email2dict-0.1.0.post1.tar.gz
Size	28.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`67a17a3ca107ca19db09417bfac9091473953abc672c7f3e49d488f05759c7df`
BLAKE2b-256 checksum How to use checksums	`5184000b599c4d6a63dd96db0950d3c9b69f99aa1a49d2c0228409d21ab65872`
Upload date	Mar 14, 2021
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/54.1.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2`

Release files / email2dict-0.1.0.post1-py3-none-any.whl

Download URL	email2dict-0.1.0.post1-py3-none-any.whl
Size	7.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`114f9f1d9dbdab1cfbf285a19bd0a6320e55273605aa317423665917b2f1d8ed`
BLAKE2b-256 checksum How to use checksums	`5e405ea8bd42f83b6be09b2d7cc4788bdbb88275bf78d83b0134c8a9922b73c4`
Upload date	Mar 14, 2021
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/54.1.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2`