{"id":17464185,"url":"https://github.com/onlyphantom/emailnetwork","last_synced_at":"2025-04-19T18:25:33.957Z","repository":{"id":42490344,"uuid":"331910707","full_name":"onlyphantom/emailnetwork","owner":"onlyphantom","description":"Network graphing utilities for email/mailbox (.mbox) data","archived":false,"fork":false,"pushed_at":"2023-03-02T00:59:44.000Z","size":4304,"stargazers_count":20,"open_issues_count":4,"forks_count":34,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T11:41:29.396Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onlyphantom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-22T10:21:12.000Z","updated_at":"2024-12-06T09:40:43.000Z","dependencies_parsed_at":"2024-11-08T16:00:44.207Z","dependency_job_id":"18f73843-236c-4cce-84f5-d64256b815fd","html_url":"https://github.com/onlyphantom/emailnetwork","commit_stats":{"total_commits":54,"total_committers":8,"mean_commits":6.75,"dds":"0.38888888888888884","last_synced_commit":"24b323e7c5159b5a02a7933b5f609664689a7316"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlyphantom%2Femailnetwork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlyphantom%2Femailnetwork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlyphantom%2Femailnetwork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onlyphantom%2Femailnetwork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onlyphantom","download_url":"https://codeload.github.com/onlyphantom/emailnetwork/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631686,"owners_count":21136562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-18T10:44:55.306Z","updated_at":"2025-04-19T18:25:33.924Z","avatar_url":"https://github.com/onlyphantom.png","language":"Python","readme":"\n[![Supertype](https://img.shields.io/badge/supertype.ai-incubate-b1976b)](https://supertype.ai/incubate)\n[![PyPI Version](https://img.shields.io/pypi/v/emailnetwork)](https://pypi.org/project/emailnetwork/)\n[![Colab Notebook](https://img.shields.io/badge/notebook-colab%20notebook-orange)](https://colab.research.google.com/drive/1mSKbt9-dTTtQq296QUkMZlZpAMybgmpV?usp=sharing)\n[![Downloads](https://pepy.tech/badge/emailnetwork)](https://pepy.tech/project/emailnetwork)\n\n# Email Network\n\n## Description\nNetwork graphing utilities for email/mailbox data.\n\n\u003cimg align=\"left\" width=\"50%\" src=\"https://github.com/onlyphantom/emailnetwork/blob/main/assets/graph1.png?raw=true\" style=\"margin-right:10%\"\u003e\n\u003cimg align=\"left\" width=\"50%\" src=\"https://github.com/onlyphantom/emailnetwork/blob/main/assets/graph4.png?raw=true\" style=\"margin-right:10%\"\u003e\n\u003cimg align=\"left\" width=\"50%\" src=\"https://github.com/onlyphantom/emailnetwork/raw/main/assets/graph5.png?raw=true\" style=\"margin-right:10%\"\u003e\n\u003cimg align=\"left\" width=\"50%\" src=\"https://github.com/onlyphantom/emailnetwork/blob/main/assets/graph3.png?raw=true\" style=\"margin-right:10%\"\u003e\n\n\nFor the social scientists, creating social networks from your mailbox data and among other things:\n* Discover subgroups within your organization (whether the different task forces established were as cohesive as it seems on the outside)  \n* Study social actors (most emails from Marketing involve Peter and Andy) and their relative influence  \n* Identify the key social groups (Sales team hangs out a lot, but the IT / product division less so)\n* Key account managers of the company (Despite being with the company only recently, Margaretha is connected to more key clients than her peers)\n* Compare distributions and patterns of email behaviors and aggregated statistics between groups of employees  \n\n\nIf you're a graph theorist and looking for something more statistical:\n* Support directed and undirected graphs (**already implemented in version 0.0.2**, see below)\n* Also output statistical measurements such as centrality distribution (**planned for version 0.0.3**)\n* Betweenness, closeness, hubness, distance histograms plotting (**planned for version 0.0.3**) \n* Exports to `.graphml` format for use in other graphing software (**already implemented in version 0.0.2**, see below)\n\n## Dependencies\n* Python 3.7+\n* Only dependencies are NetworkX and Matplotlib\n\n## Example Usage\nTo install `emailnetwork`:\n```\npip install emailnetwork\n```\n\nA sample `.mbox` file is provided to you, but you can obtain export your own mailbox from your email service provider. If you use Google (Gmail), you can [use the Google Takeout service](https://takeout.google.com/settings/takeout) to export your mail data.\n\n\n```python\nfrom emailnetwork.extract import MBoxReader\nreader = MBoxReader('path-to-mbox.mbox')\nprint(f'{len(reader)} emails in the sample mbox.')\n\n# extract a specific email\nfrom emailnetwork.extract import extract_meta\nemail = reader.mbox[5]\nemailmsg = extract_meta(email)\n\n# filter emails by certain date\nthisyearmails = reader.filter_emails(dateoperator='\u003e=', datestring='2021-01-05')\n\n# print email domains of recipients\nprint(emailmsg.recipients)\nprint(emailmsg.recipients[0].domain)\n\n# extract all emails\nemails = reader.extract()\n```\n\nFor graph visualization:\n```py\nfrom emailnetwork.extract import MBoxReader\nfrom emailnetwork.graph import plot_directed, plot_undirected, plot_single_directed, plot_single_undirected\n\n# Read from .mbox\nMBOX_PATH = f'{os.path.dirname(__file__)}/tests/test.mbox'\nreader = MBoxReader(MBOX_PATH)\n\n# Try the following: \n# plot a single directed graph the email at index 3\nplot_single_directed(reader,3)\n\n# plot a single undirected graph the email at index 3, show title in plot\nplot_single_undirected(reader, 1, showtitle=True)\n\n# plot a directed graph, optionally specifying a layout style\nplot_directed(reader)\nplot_directed(reader, 'shell')\n# optionally export a .graphml to your working directory for use\n# in other network / graphing software\nplot_undirected(reader, 'spring', graphml=True)\n```\n\n#### Email Header Analysis \n\u003cimg align=\"left\" width=\"40%\" src=\"https://github.com/onlyphantom/emailnetwork/raw/main/assets/histo.png?raw=true\" style=\"margin-right:10%\"\u003e\nTo obtain a histogram:\n\n```py\nfrom emailnetwork.extract import MBoxReader\nreader = MBoxReader('path-to-mbox')\nheaders = HeaderCounter(reader)\nheaders.histogram()\n# to show only top 10 header, set an optional n parameter\n# headers.histogram(n=10)\n```\nBecause `HeaderCounter` is a subclass of Python's `Counter`, you can also perform operations such as `headers.most_common(8)` to get the 8 most-common headers from the `mbox` file.\n\nIf you want to find all email headers with the word \"spam\" in it (e.g spam score, other antispam mechanism), you can use Python's `filter()` function:\n```python\nreader = MBoxReader('path-to-mbox')\nheaders = HeaderCounter(reader)\nspamheaders = list(filter(lambda v: \"spam\" in v.lower(), headers.keys()))\n# return:\n# ['X-Spam-Checked-In-Group', 'X-Microsoft-Antispam-PRVS', 'X-Microsoft-Antispam-Untrusted', 'X-Microsoft-Antispam-Message-Info-Original', 'X-Forefront-Antispam-Report-Untrusted', 'x-ms-exchange-antispam-messagedata', 'X-Microsoft-Antispam', 'X-Microsoft-Antispam-Message-Info', 'X-Forefront-Antispam-Report', 'X-Mimecast-Spam-Score', 'x-microsoft-antispam-prvs', 'x-microsoft-antispam', 'x-microsoft-antispam-message-info', 'x-forefront-antispam-report']\n```\n\n#### Mailbox Summary\n\nTo get a simple barchart on the distribution of email domains in your `.mbox`, you can create a `DomainSummary` object and call the `.plot()` function:\n\n\u003cimg align=\"left\" width=\"50%\" src=\"https://github.com/onlyphantom/emailnetwork/raw/main/assets/summaryplot.png\" /\u003e\n\n```python\nfrom emailnetwork.summary import DomainSummary\nsummary = DomainSummary(reader)\nsummary.plot()\n```\n\nYou can also return a `Counter()` (a subclass of `dict`) instead of a plot:\n\n```python\nsummary.summary\n# return:\n# Counter({'supertype.ai': 203, 'hubspot.com': 115, 'gmail.com': 75, 'google.com': 53, 'adcolony.com': 38, 'fbworkmail.com': 35, 'elementor.com': 29, 'payoneer.com': 15, 'gogame.net': 14, 'zoomd.com': 13, 'am.atlassian.com': 10, 'theafternaut.com': 6, 'alegrium.com': 5, 'accounts.google.com': 4, 'e.atlassian.com': 4, 'tnbaura.com': 4, 'support.lazada.sg': 4, '3kraters.com': 3, 'go.facebookmail.com': 2, 'docs.google.com': 2, 'mail.hellosign.com': 2, 'algorit.ma': 2, 'supertype.atlassian.net': 2, 'ucdconnect.ie': 2, 'mc.facebookmail.com': 1, 'inplacesoftware.com': 1, 'aura.co': 1, 'atlassian.com': 1, 'greenhouse.io': 1})\n```\n##### Why Python 3.7+?\nPython 3.7+ is required because the package is written to take advantage of many features of Python 3.7 and above. \n\nExamples of features that were used extensively in the creation of this package:\n* [Dataclasses, new in Python 3.7](https://www.youtube.com/watch?v=sH_jLQvnpBo)\n* [Insertion-ordered Dictionaries, new in Python 3.7](https://www.youtube.com/watch?v=h-DBWPjpqWY)\n* [Typing (Type hints), new in Python 3.5](https://docs.python.org/3/library/typing.html)\n* [Formatted string literal, new in Python 3.6](https://docs.python.org/3/reference/lexical_analysis.html#f-strings)\n## Testing\nGit clone, and run `pytest`. You can also run pytest with coverage:\n```\npytest --cov\n\n.........\n\nName                       Stmts   Miss  Cover\n----------------------------------------------\nemailnetwork/__init__.py       2      0   100%\nemailnetwork/emails.py        39      1    97%\nemailnetwork/extract.py       94     15    84%\nemailnetwork/graph.py        120     12    90%\nemailnetwork/header.py        39     24    38%\nemailnetwork/network.py       13      1    92%\nemailnetwork/summary.py       73     22    70%\nemailnetwork/utils.py         30      9    70%\nemailnetwork/version.py        1      0   100%\n----------------------------------------------\nTOTAL                        411     84    80%\n\n\n=============== 17 passed in 2.85s ==============\n```\n\nAll tests are located in the `/tests/` directory.\n\n## Email Network Demo\n\n[Aurellia Christie](https://github.com/AurelliaChristie) has created a Colab Notebook: [Email Network Walkthrough](https://colab.research.google.com/drive/1mSKbt9-dTTtQq296QUkMZlZpAMybgmpV?usp=sharing) to walk you through the most common functionalities of Email Network\n\n## Authors and Copyright\n\nSamuel Chan, [Supertype](https://supertype.ai)\n - Github: [onlyphantom](https://github.com/onlyphantom)\n\nVincentius Christopher Calvin, [Supertype](https://supertype.ai)\n - Github: [vccalvin33](https://github.com/vccalvin33)\n\nIf you find the code useful in your project, please link to this repository in your citation.\n\n##### The MIT License (MIT)\n\nCopyright (c) 2021 Supertype Pte Ltd\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\n* The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonlyphantom%2Femailnetwork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonlyphantom%2Femailnetwork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonlyphantom%2Femailnetwork/lists"}