mailaccess 0.17.5

Self-hostable OSINT platform for investigating email addresses. Fan out across breach databases, social networks, DNS records, and the open web — get back a unified exposure score and structured findings you can export or pipe into Maltego.

Built for security researchers, OSINT analysts, and penetration testers operating under authorization. Read DISCLAIMER.md before use.

Terminal Output

Install

pip install mailaccess
mailaccess investigate you@example.com

The CLI auto-starts and stops the backend for each investigation. Use mailaccess serve when you want a persistent server, or install mailaccess[ml] for optional spaCy-based name classification.

Full install options (Docker, persistent server, self-hosting) -> docs/self-hosting.md.

Quick Start

mailaccess investigate you@example.com
mailaccess investigate you@example.com -o report.pdf
mailaccess harvest-emails --domain company.com
mailaccess harvest-emails --domain company.com --export harvest.csv
mailaccess find-email --name "Jane Doe" --domain company.com
mailaccess keys set HIBP_API_KEY your-key
mailaccess keys list
mailaccess serve
mailaccess modules

Pipeline, stdin, JSONL, and CI examples -> docs/integrations.md.

What It Does

• Identity graph - cross-platform correlation of accounts, usernames, names, avatars, breach data, and profile links.
• Name Consensus Engine - synthesizes independent name signals into confirmed, probable, possible, or unknown identity bands.
• Defender's Brief - security-manager-ready risk summary with prioritized findings and a concrete next action.
• Domain email harvesting - harvest-emails discovers organization addresses across Common Crawl, GitHub, CT logs, registries, keyservers, dorks, employee pages, and patterns.
• Company email patterns - find-email turns a name plus an employer domain into one honestly-graded likely address, offline from a bundled 384K-domain pattern index; unverified guesses are labelled as such, and Microsoft 365 mailboxes are verified where the provider allows.
• 5,000+ platform corpus - a native username-platform engine over a MailAccess-verified corpus of 5,000+ platform definitions (data/mailaccess_sites.json), with two-marker detection and zero runtime dependencies; each investigation probes a bounded, rank- and health-prioritized subset of the highest-signal platforms. Plus a native account-existence engine covering 250+ email-checkable services, and native Google-account intelligence (unauthenticated, on by default).
• Deep breach mode - probes the highest-severity breach corpus for account-existence risk.
• Credential Risk Score - separate 0-100 credential exposure band with top drivers and recommended next steps.
• 6 export formats - JSON, CSV, PDF, Markdown, STIX 2.1, and Maltego XML.

Identity Graph

Every investigation builds an identity graph linking accounts by shared usernames, photos, display names, and breach data. View it at /investigation/:id/graph, export it with GET /api/report/{id}/graph, or read the full model in docs/modules.md.

Name Consensus Engine

MailAccess collects name signals from profile modules and returns a defensible identity summary:

CONFIRMED IDENTITY
  Name:     Katriel Moses  [CONFIRMED]
  Sources:  GitHub . Gravatar . Keybase . PGP
  Reasoning: 4 independent sources agree.

Full confidence rules and source behavior -> docs/modules.md.

Defender's Brief

Every investigation includes a 30-second risk summary designed for security managers:

DEFENDER'S BRIEF
  Risk:    CRITICAL
  Summary: Active infostealer infection detected.
  1. Active credential theft   [CRITICAL]
     -> Rotate credentials immediately.
  Next action: Immediately rotate credentials and enforce hardware MFA.

Suppress it with --no-brief; full details live in docs/modules.md.

Find Email (Company Patterns)

Give MailAccess a person's name and their employer domain and it returns one most-likely email address — not a spray of guesses:

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

Company email pattern - company.com
  email          jane.doe@company.com
  verification   unverified
  confidence     likely (0.78)
  support        142 verified samples
  provenance     company email pattern (P04, 142 verified samples, conf 0.91)

The pattern comes from a bundled index of ~384,000 domains learned from real verified addresses — it loads offline, no network access. The result is honest by construction: an inferred address is always labelled unverified and graded likely, never presented as confirmed. Where the domain runs on Microsoft 365, the candidate is checked against the mailbox-existence oracle — a confirmed one is upgraded to provider_verified, and one proven not to exist is dropped. Add --title to apply per-role pattern overrides. Domains the index doesn't cover fall back cleanly to live inference. Full details -> docs/modules.md.

MailAccess Pro — corpus lead enrichment

Availability is controlled by the hosted service. The tier is served only when its server-side compliance gate is enabled; this section documents the client surface.

MailAccess Pro is an optional paid managed-enrichment add-on that enriches a lead-gen-mode harvest with business-contact leads (name, title, email, LinkedIn) aggregated from publicly-available and third-party commercial sources. It is strictly additive: without a key the open engine behaves exactly as it always has.

mailaccess keys set MAILACCESS_PRO_KEY <your-key>
# harvest a domain, with corpus leads appended (lead-gen mode required):
mailaccess harvest-emails --domain company.com --mode public-business-contact
# or resolve a company name to its domain first (a Pro-tier feature):
mailaccess harvest-emails --company "Stripe" --mode public-business-contact

Honest by construction:

• Corpus leads are always labelled unverified with explicit [MailAccess Pro · corpus · unverified] provenance — never dressed as a verified/native hit — and the eligibility gate caps them at REVIEW (research / outreach-review, not ready-to-send).
• The key never forces a mode. Corpus leads are only injected in a lead-gen mode (public-business-contact / org-authorized-verification); a key in the default security-investigation mode prints a hint and injects nothing.
• Fail-open. If the service is unreachable, the harvest shows the full open result with a one-line "corpus enrichment unavailable" note.
• Honest framing: the fee recovers paid infrastructure and processing cost; queries are unlimited but serialized per key (one at a time) to protect result quality.

Corpus leads are live-only: they remain in their own unverified Pro surface and never enter the open-result exports, local database, or history. See docs/modules.md.

Modules

75 modules over a 5,000+ platform corpus. Investigations probe a bounded, evidence-first wave of the highest-signal platforms (~700 vetted by default) rather than the whole corpus. Full module reference -> docs/modules.md.

API Keys

Most modules work with zero keys. Optional keys unlock more coverage. Full list -> docs/api-keys.md.

Export Formats

Save reports as JSON, CSV, PDF, Markdown, STIX 2.1, or Maltego XML with -o. Full export reference -> docs/exports.md.

Integrations

Use Maltego, Slack, Discord, generic webhooks, JSONL pipelines, and CI workflows. Full integration guide -> docs/integrations.md.

Self-Hosting

Run the CLI locally or launch the full web stack with Docker Compose. Full guide -> docs/self-hosting.md.

Changelog

See CHANGELOG.md for release history.

Troubleshooting

Links

License

MIT. All data queried by MailAccess comes from public sources. See DISCLAIMER.md for authorized use cases and legal responsibility.