MailAccess

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.

Install

CLI only (no Docker)

pip install mailaccess

mailaccess investigate [email protected]
# Server starts automatically, runs investigation,
# stops when done.

# Option B: keep server running
mailaccess serve  # in one terminal
mailaccess investigate [email protected]  # in another

# Option C: full stack with Web UI
git clone https://github.com/YOUR_USERNAME/mailaccess
docker compose up -d

Quick Start

mailaccess investigate [email protected]
mailaccess investigate [email protected] -o report.pdf
mailaccess investigate [email protected] --format jsonl
mailaccess investigate -                        # read email from stdin
mailaccess serve                                # start backend server on :8000
mailaccess keys list
mailaccess keys set HIBP_API_KEY your-key-here
mailaccess modules
mailaccess doctor                               # coming soon

What It Does

• Identity graph — cross-platform correlation of accounts, usernames, and signals from each investigation
• Phone number recovery — pipeline to surface and validate numbers tied to the target
• Telegram / WhatsApp hints — lightweight messaging-app footprint checks alongside other modules
• YAML-driven platform system — social-style checks defined in backend/platforms/; community extensible without new Python for each site
• Concurrent module execution — all modules run in parallel, results stream as they arrive
• WebSocket streaming — partial results arrive in real time without polling
• REST API + web UI + CLI — use whatever interface fits your workflow
• Plugin module system — drop a .py file in backend/modules/ and it auto-registers; no wiring required
• 6 export formats: JSON, CSV, PDF, Markdown, STIX 2.1, Maltego XML
• Maltego local transform server — run investigations directly from the Maltego desktop app
• Webhook notifications — Slack, Discord, or any HTTP endpoint
• Exposure score (0–100) with risk label: low / medium / high / critical
• SQLite by default; PostgreSQL optional via Docker Compose profile

Modules

800+ platforms checked when all opt-in modules enabled. YAML platform system — add new platforms via PR, no Python required.

Identity Graph

Every investigation generates a cross-platform identity graph linking accounts by shared usernames, photos, display names, and breach data. View at:

/investigation/:id/graph

Export as D3-compatible JSON via GET /api/report/{id}/graph or fetch clusters with confidence scores via GET /api/report/{id}/clusters.

Findings are automatically grouped into identity clusters with confidence scoring. Use --show-collisions to expand low-confidence matches in CLI output.

Pipeline

MailAccess is pipeline-friendly: read target emails from stdin, stream JSONL output, and branch on exit codes in CI/CD scripts.

# Batch from file
cat emails.txt | mailaccess investigate -

# Stream JSONL
mailaccess investigate [email protected] --format jsonl | jq .

# Filter critical findings
mailaccess investigate [email protected] --format jsonl | jq 'select(.severity=="critical")'

Exit codes: 0 clean · 1 findings · 2 breaches · 3 error

See docs/integrations.md for GitHub Actions examples.

Adding a Platform

No Python required. Drop a YAML file in backend/platforms/:

cp backend/platforms/TEMPLATE.yaml backend/platforms/mysite.yaml

Edit fields, submit PR.

See CONTRIBUTING.md for full guide.

Export Formats

Integrations

Self-Hosting

cp .env.example .env      # all API keys are optional
docker compose up         # backend :8000  ·  frontend :3000

Open http://localhost:3000 in your browser. Full setup guide: docs/self-hosting.md.

CLI Reference

The --output / -o flag on investigate saves the report to a file. The extension determines the format: .json, .csv, .pdf, .md, .stix.json, .maltego.csv.

API Keys

Troubleshooting

Links