Metadata-Version: 2.4
Name: mailaccess
Version: 0.19.3
Summary: Open-source OSINT email intelligence tool
Project-URL: Homepage, https://github.com/YOUR_USERNAME/mailaccess
Project-URL: Documentation, https://github.com/YOUR_USERNAME/mailaccess/docs
Project-URL: Issues, https://github.com/YOUR_USERNAME/mailaccess/issues
Author: Katriel Moses
License: MIT
License-File: LICENSE
Keywords: email,intelligence,osint,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: aiodns>=3.2
Requires-Dist: aiosqlite>=0.20
Requires-Dist: alembic>=1.13
Requires-Dist: asyncpg>=0.29
Requires-Dist: curl-cffi>=0.7
Requires-Dist: dnspython>=2.6
Requires-Dist: fastapi>=0.111
Requires-Dist: httpx>=0.27
Requires-Dist: imagehash>=4.3
Requires-Dist: packaging>=23
Requires-Dist: pillow>=10.0
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic[email]>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-whois>=0.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: rich>=13
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: stix2>=3.0
Requires-Dist: typer[all]>=0.25.1
Requires-Dist: unidecode>=1.3
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: websockets>=12
Provides-Extra: browser
Requires-Dist: playwright-stealth>=1.0; extra == 'browser'
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: build
Requires-Dist: duckdb==1.5.5; extra == 'build'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: ml
Requires-Dist: spacy<4.0,>=3.7; extra == 'ml'
Provides-Extra: pdf
Requires-Dist: weasyprint>=60.0; extra == 'pdf'
Description-Content-Type: text/markdown

<p align="right">
  <sub>Let's connect</sub><br>
  <a href="https://x.com/delzynkatriel"><img src="https://img.shields.io/badge/@delzynkatriel-0D0D0D?style=flat&logo=x&logoColor=white&labelColor=555555" alt="X: @delzynkatriel"></a>
  <a href="https://www.linkedin.com/in/katriel-moses"><img src="https://img.shields.io/badge/%2Fin%2Fkatriel--moses-0D0D0D?style=flat&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTIwLjQ0NyAyMC40NTJoLTMuNTU0di01LjU2OWMwLTEuMzI4LS4wMjctMy4wMzctMS44NTItMy4wMzctMS44NTMgMC0yLjEzNiAxLjQ0NS0yLjEzNiAyLjkzOXY1LjY2N0g5LjM1MVY5aDMuNDE0djEuNTYxaC4wNDZjLjQ3Ny0uOSAxLjYzNy0xLjg1IDMuMzctMS44NSAzLjYwMSAwIDQuMjY3IDIuMzcgNC4yNjcgNS40NTV2Ni4yODZ6TTUuMzM3IDcuNDMzYy0xLjE0NCAwLTIuMDYzLS45MjYtMi4wNjMtMi4wNjUgMC0xLjEzOC45Mi0yLjA2MyAyLjA2My0yLjA2MyAxLjE0IDAgMi4wNjQuOTI1IDIuMDY0IDIuMDYzIDAgMS4xMzktLjkyNSAyLjA2NS0yLjA2NCAyLjA2NXptMS43ODIgMTMuMDE5SDMuNTU1VjloMy41NjR2MTEuNDUyek0yMi4yMjUgMEgxLjc3MUMuNzkyIDAgMCAuNzc0IDAgMS43Mjl2MjAuNTQyQzAgMjMuMjI3Ljc5MiAyNCAxLjc3MSAyNGgyMC40NTFDMjMuMiAyNCAyNCAyMy4yMjcgMjQgMjIuMjcxVjEuNzI5QzI0IC43NzQgMjMuMiAwIDIyLjIyMiAwaC4wMDN6Ii8%2BPC9zdmc%2B&labelColor=555555" alt="LinkedIn: /in/katriel-moses"></a>
</p>

<p align="center">
  <a href="https://mailaccess.pro"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/hero.png" alt="MailAccess: email recon that shows its work" width="100%"></a>
</p>

<p align="center">
  <a href="https://github.com/KatrielMoses/MailAccess/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-18171A.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-18171A.svg" alt="Python 3.10+"></a>
  <a href="https://github.com/KatrielMoses/MailAccess/blob/main/docker-compose.yml"><img src="https://img.shields.io/badge/Docker-Compose-18171A.svg" alt="Docker Compose"></a>
  <a href="https://pypi.org/project/mailaccess/"><img src="https://img.shields.io/pypi/v/mailaccess?label=PyPI&color=B86A73&logo=pypi&logoColor=white" alt="PyPI version"></a>
  <a href="https://pepy.tech/projects/mailaccess"><img src="https://img.shields.io/pepy/dt/mailaccess?color=B86A73&label=downloads" alt="PyPI downloads"></a>
</p>

<p align="center">
  <a href="https://mailaccess.pro"><b>mailaccess.pro</b></a>
  &nbsp;·&nbsp; <a href="https://github.com/KatrielMoses/MailAccess/blob/main/docs/modules.md">Docs</a>
  &nbsp;·&nbsp; <a href="https://pypi.org/project/mailaccess/">PyPI</a>
  &nbsp;·&nbsp; <a href="https://github.com/KatrielMoses/MailAccess/blob/main/CHANGELOG.md">Changelog</a>
</p>

Open-source email OSINT and email scraper. One email in, every account behind it: 82 modules check 5,300+ platforms, and every finding says how it was found and how sure we are. One domain in, every public email at the company. Run it on your own machine, or use it hosted at [mailaccess.pro](https://mailaccess.pro).

<a href="https://netlas.io"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-netlas.png" alt="Powered by Netlas: see what runs on every host behind a domain" width="100%"></a>
<a href="https://ipgeolocation.io/?utm_source=github&utm_medium=referral&utm_campaign=mailaccess"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-ipgeolocation-io.png" alt="Powered by ipgeolocation.io: IP geolocation and threat intel for every IP" width="100%"></a>
<a href="https://whoisfreaks.com/?utm_source=github&utm_medium=referral&utm_campaign=mailaccess"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-whoisfreaks.png" alt="Powered by WhoisFreaks: who owned a domain, and what else they registered" width="100%"></a>
<a href="https://www.ipburger.com/?utm_source=mailaccess&utm_medium=github_readme&utm_campaign=sponsorship"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-ipburger.png" alt="Partnered with IPBurger: dedicated ISP IPs that stay yours, built for recon" width="100%"></a>
<a href="https://mangoproxy.com/?utm_source=katrielmoses&utm_medium=partner&utm_campaign=katrielmoses_github"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-mango.png" alt="Partnered with Mango Proxy: residential IPs that keep big harvests clean" width="100%"></a>
<a href="https://www.swiftproxy.net/?ref=MailAccess"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-swiftproxy.png" alt="Partnered with Swiftproxy: reliable residential IPs for scalable email harvesting" width="100%"></a>
<a href="https://www.rapidproxy.io/?ref=MailAccess"><img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/sponsor-rapidproxy.png" alt="Partnered with Rapidproxy: 90M+ rotating residential IPs for scalable scraping" width="100%"></a>

Built for security researchers, OSINT analysts and penetration testers working under authorization. Read [DISCLAIMER.md](https://github.com/KatrielMoses/MailAccess/blob/main/DISCLAIMER.md) before use.

## See it run

<img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/demo-web.gif" alt="Example run on the web app: jane@example.com is investigated live, accounts appear as each check returns, then the report opens" width="100%">

<sub>Example run with fictional data (jane@example.com). The live view, then the report it opens into.</sub>

## Install

```bash
pip install mailaccess
mailaccess investigate jane@example.com
```

Python 3.10+. The CLI starts and stops its backend for each run. Use `mailaccess serve` for a persistent server, `mailaccess[ml]` for spaCy name classification, and `mailaccess[browser]` (then `playwright install chromium`) for the optional [headless-browser checks](https://github.com/KatrielMoses/MailAccess/blob/main/docs/account-existence-platforms.md#browser-tier-optional). Docker and self-hosting: [docs/self-hosting.md](https://github.com/KatrielMoses/MailAccess/blob/main/docs/self-hosting.md).

## Quick start

```bash
mailaccess investigate jane@example.com                  # every account behind an email
mailaccess investigate jane@example.com -o report.html   # save the report (also .pdf, .md, .json)
mailaccess harvest-emails --domain example.com           # every public email at a domain
mailaccess find-email --name "Jane Doe" --domain example.com
mailaccess login                                         # sign in for your free key
mailaccess doctor                                        # check your setup
mailaccess keys set HIBP_API_KEY your-key                # optional providers
mailaccess upgrade
```

Pipelines, stdin, JSONL and CI: [docs/integrations.md](https://github.com/KatrielMoses/MailAccess/blob/main/docs/integrations.md#pipeline-integration).

## What it does

- **Accounts behind an email.** About 340 sign-up and login checks on public, logged-out pages, plus a username sweep over the 746 strongest of 5,300+ platforms. [Full list and methods](https://github.com/KatrielMoses/MailAccess/blob/main/docs/account-existence-platforms.md).
- **Every finding shows its work.** The check that ran, what the site said back, why it counts, and a grade: Confirmed, Likely, Possible or Username match.
- **Who is behind it.** A name consensus across independent sources. With an operator credential, the Google profile name and photo; with an Oxylabs key, Instagram, Facebook and LinkedIn profiles that match the address.
- **What it means.** A Defender's Brief with the next action, an exposure score, a credential risk score and public breach records.
- **Email scraper.** `harvest-emails` finds the public addresses at a domain from Common Crawl, GitHub, certificate logs, keyservers, team pages and patterns, then grades each one.
- **Company patterns.** `find-email` turns a name and an employer domain into one graded likely address, offline, from a bundled 384K-domain pattern index.
- **Exports.** JSON, CSV, HTML, PDF, Markdown, STIX 2.1 and Maltego (CSV for graph import).

## Email scraper

<img src="https://raw.githubusercontent.com/KatrielMoses/MailAccess/main/assets/demo-scraper.gif" alt="Example run in the terminal: mailaccess harvest-emails --domain example.com runs 19 sources live, then lists graded addresses, people and role accounts" width="100%">

<sub>Example run with fictional data (example.com).</sub>

## Sign in for the MailAccess Index

`mailaccess login` (free) saves your account key. Harvests then add the MailAccess Index, our own index of emails seen on the public web: 5 harvests a day and 30 a month on the free plan, more with Pro.

## MailAccess Pro

Your free harvest finds the addresses that are public. Pro adds the people who make the decisions: business contacts with name, role, company, email and LinkedIn, from public and third-party commercial sources.

```text
$ mailaccess harvest-emails --domain example.com
  11 found · 194 available with Pro
  ──────────────────────────────────────────────────────────────────
  Dana Reed    VP Security           Example   dana.reed@example.com   in/danareed
  Sam Okoye    Head of Procurement   Example   s.okoye@example.com     in/samokoye
  Priya Nair   Director, Platform    Example   p.nair@example.com      in/priyanair
  … 180 more business contacts (name, role, company, email, LinkedIn)
```

- **See the gap first.** Every free harvest prints how many contacts Pro would add for that domain.
- **Company names work too.** `--company "Example Corp"` resolves the domain for you.
- **The hosted app too.** Photos, location and every export on any report at [mailaccess.pro](https://mailaccess.pro), 30 investigations and 10 scrapes a day.
- **$5 a month, locked for life, for the first 100 subscribers. Then $9.** Run `mailaccess pro` for seats left.

Pro contacts stay in their own view. They never enter your exports, local database or history. Without a key, nothing changes.

[Get Pro](https://mailaccess.pro/pricing?src=readme) · [How it works](https://github.com/KatrielMoses/MailAccess/blob/main/docs/modules.md#mailaccess-pro-corpus-lead-enrichment)

## Modules and API keys

82 modules, and 70 of them need no API key. Investigations probe a bounded, evidence-first set of the highest-signal platforms rather than the whole corpus. Optional keys (HIBP, Netlas, ipgeolocation.io, WhoisFreaks, Oxylabs and others) add coverage: set them with `mailaccess keys set`.

[Module reference](https://github.com/KatrielMoses/MailAccess/blob/main/docs/modules.md) · [API keys](https://github.com/KatrielMoses/MailAccess/blob/main/docs/api-keys.md) · [Export formats](https://github.com/KatrielMoses/MailAccess/blob/main/docs/exports.md) · [Self-hosting](https://github.com/KatrielMoses/MailAccess/blob/main/docs/self-hosting.md)

## Staying up to date

MailAccess checks PyPI for a newer release (cached, never blocking) and prints a hint when you're behind. Update with `mailaccess upgrade`. Silence it with `MAILACCESS_NO_UPDATE_CHECK=1`, or [get release notes by email](https://mailaccess.pro/updates?src=readme).

To stop the calls MailAccess makes on its own (the coverage teaser, the sponsor feed, the founder-seat counter and this update check), run `mailaccess --local-only <command>`, or turn it on for good with `mailaccess local-only enable`. OSINT checks still run. With a Pro key set, Pro enrichment still runs, and the CLI tells you before it sends anything.

## Sponsors

MailAccess is free and MIT licensed. Sponsors keep the corpus and the infrastructure running. [Sponsor this project](https://mailaccess.pro/sponsors?src=readme).

## Links

| | |
|-|-|
| [Self-hosting guide](https://github.com/KatrielMoses/MailAccess/blob/main/docs/self-hosting.md) | Docker Compose, `.env` reference, PostgreSQL, proxy and Tor, Maltego setup |
| [Module reference](https://github.com/KatrielMoses/MailAccess/blob/main/docs/modules.md) | Every module, the findings schema, adding a module |
| [False-positive controls](https://github.com/KatrielMoses/MailAccess/blob/main/docs/fp-control.md) | Common names, disposable domains, clustering, platform health, scoring |
| [API reference](https://github.com/KatrielMoses/MailAccess/blob/main/docs/api.md) | REST endpoints, live run events, authentication |
| [Export formats](https://github.com/KatrielMoses/MailAccess/blob/main/docs/exports.md) | Formats, MIME types, file names |
| [Integrations](https://github.com/KatrielMoses/MailAccess/blob/main/docs/integrations.md) | Maltego, Slack, Discord, webhooks |
| [Brand assets](https://github.com/KatrielMoses/MailAccess/blob/main/docs/brand.md) | Logo, palette, type, downloadable SVGs |
| [Contributing](https://github.com/KatrielMoses/MailAccess/blob/main/CONTRIBUTING.md) | Adding modules and exporters, code style, PR checklist |

## License

MIT. By default MailAccess reads public, logged-out sources; optional providers you configure, and Pro, bring their own data. See [DISCLAIMER.md](https://github.com/KatrielMoses/MailAccess/blob/main/DISCLAIMER.md) for authorized use and legal responsibility.

---

If MailAccess saved you time, a ⭐ helps other researchers find it.
