MailAccess: a self-hostable email OSINT platform with an identity graph and graded findings

What MailAccess does, and the authorization boundary

MailAccess is a self-hostable OSINT platform for investigating email addresses. It fans out across breach databases, social networks, DNS records and the open web and returns a unified exposure score with structured findings you can export or pipe into Maltego. The README sets the boundary in the second sentence: it is built for security researchers, OSINT analysts and penetration testers operating under authorization, and it tells you to read DISCLAIMER.md before use. That framing is the right one to keep in view, because the same modules that let a defender check whether corporate credentials are exposed also enumerate where a person has accounts. Everything below assumes you have the authorization to run it.

75 modules, 5,000 platforms, and the bounded wave

Scale is the headline, and the README is precise about what the numbers mean. There are 75 modules over a corpus of more than 5,000 platform definitions held in data/mailaccess_sites.json, with two-marker detection and zero runtime dependencies. An investigation does not probe all of them: it probes a bounded, rank- and health-prioritized subset of the highest-signal platforms, roughly 700 vetted by default, on an evidence-first basis. Alongside that sits a native account-existence engine covering more than 250 email-checkable services, native Google-account intelligence that is unauthenticated and on by default, and a deep breach mode that probes the highest-severity breach corpus for account-existence risk. Most modules work with no API keys at all, and optional keys unlock further coverage.

Installing it and running a first investigation

The CLI is the fastest way in, and it manages its own backend.

pip install mailaccess
mailaccess investigate you@example.com

The README states that the CLI auto-starts and stops the backend for each investigation, so there is nothing to run in a second terminal. Use mailaccess serve when you want a persistent server instead, install mailaccess[ml] to add optional spaCy-based name classification, and run mailaccess modules to see the module list. An optional key is set the same way, with mailaccess keys set HIBP_API_KEY your-key and mailaccess keys list to check what is configured. Reports are written with -o, and the same command set covers domain harvesting and address inference.

mailaccess find-email --name "Jane Doe" --domain company.com

That last one is the most interesting design decision in the project, and it is covered below.

What an investigation returns

Four things come back from an investigation. An identity graph links accounts by shared usernames, photos, display names and breach data, viewable at /investigation/:id/graph or through GET /api/report/{id}/graph. A name consensus engine synthesises independent name signals into confirmed, probable, possible or unknown bands, and prints its reasoning, so a name is not asserted without saying how many sources agree. A Defender's Brief is a 30-second risk summary aimed at security managers, with prioritized findings and one concrete next action, which you can suppress with --no-brief. And a Credential Risk Score gives a separate 0 to 100 credential exposure band with top drivers and recommended next steps. Separately, findings export to six formats: JSON, CSV, PDF, Markdown, STIX 2.1 and Maltego XML.

Harvesting and inference, with honest grading

Two capabilities deserve their own warning labels, and the project supplies both. Domain email harvesting discovers organisation addresses across Common Crawl, GitHub, certificate transparency logs, registries, keyservers, dorks, employee pages and patterns. Company email patterns take a name plus an employer domain and return one most-likely address, offline from a bundled index of roughly 384,000 domains learned from real verified addresses, with no network access needed. The README calls that result honest by construction: an inferred address is always labelled unverified and graded likely, never presented as confirmed, and where a domain runs on Microsoft 365 the candidate is checked against a mailbox-existence oracle and either upgraded to provider_verified or dropped. Add --title to apply per-role pattern overrides. Domains the index does not cover fall back to live inference.

Self-hosting it with Docker

Self-hosting is a Docker compose stack with a backend, a frontend and an optional Postgres, driven by a Makefile.

make dev

The backend runs uvicorn against backend.main:app on port 8000 with reload, the frontend runs a dev server on port 3000, and Postgres 16 Alpine sits behind a profile that activates only when POSTGRES_ENABLED is true, exposed on 5432. Two configuration details will bite otherwise: DATABASE_URL needs an async driver, because the app uses SQLAlchemy's async engine and a plain postgresql:// URL fails at startup, and CORS_ORIGINS and MODULE_TIMEOUT_OVERRIDES must be a JSON array and a JSON object respectively rather than plain strings. Defaults cap concurrency at MAX_CONCURRENT_MODULES=10 with a 30 second per-module timeout, and an overall investigation budget can truncate in-flight modules, which are reported as budget_truncated. The Makefile is explicit that the stack has no Kubernetes, no CI/CD and no SSL termination, and that internet-facing deployments need a reverse proxy such as Nginx, Caddy or Traefik in front of it.

holehe, and why this is a different shape of tool

The comparison that matters is with holehe, which the repository lists among its topics. Holehe answers one question, whether an email is registered on a list of sites, from a single command, and it does that well. MailAccess wraps that kind of account-existence checking in something much larger: an identity graph that correlates usernames, avatars, display names and breach data, a name consensus engine that grades how confident it is, a credential risk score, an exposure score, a defender-facing summary, six export formats including STIX 2.1 and Maltego XML, and a web backend you can host yourself. That is a different shape of tool. If you want a fast yes or no per site, holehe is enough. If you need a report that survives being handed to someone else, the graph and the exports are the reason to run this instead.

Limits, licence and upkeep

MailAccess declares MIT in its project metadata and requires Python 3.10 or newer, with current version 0.16.0 in pyproject.toml and a Development Status classifier of 4 Beta, which is a fair summary of where it sits. The last push was on 2026-09-14. The dependency list is substantial and tells you what kind of software this is: FastAPI and uvicorn for the backend, SQLAlchemy with aiosqlite and asyncpg, httpx and curl-cffi for requests, dnspython and python-whois for DNS and registration lookups, stix2 for the export format, and both imagehash and Pillow, which points at avatar comparison across profiles. Optional extras add spaCy for name classification and weasyprint for PDF. Two things the repository does not claim: that the corpus is complete, and that an inferred email address is verified, which is why unverified is a label rather than a disclaimer.

Editorial conclusion

Run MailAccess if you do authorized exposure work and need findings you can hand to someone else, because the identity graph, the name consensus bands and the six export formats, including STIX 2.1 and Maltego XML, are what make the output defensible. Do not run it on anyone you are not authorized to investigate, and read DISCLAIMER.md first, since the same modules enumerate where a person holds accounts. Start with pip install mailaccess and one investigate run against an address you own, then check the Defender's Brief and the credentials score before you decide whether the optional API keys are worth adding.

Frequently asked questions

Official sources

1. Issues
2. KatrielMoses/MailAccess on GitHub
3. Project website
4. README