Product · Python · Windows Desktop
EML Contacts is a local-first Windows desktop application that turns historical email archives into a clean, deduplicated and reviewable address book.
It imports EML, Outlook PST and MBOX archives, extracts contact details, consolidates repeated observations into canonical contacts, preserves the evidence behind each result and provides a structured human review workflow before export.
The business problem
Organisations often accumulate years of correspondence with clients, suppliers, professional advisers, prospects, former colleagues, introducers and commercial partners without ever having maintained a complete or systematic address book.
When key staff leave, email systems migrate, or companies undergo reorganisation, those critical business relationships remain trapped inside historical mail archives.
Simple pattern matching is rarely enough: email signatures contain complex layouts, mobile numbers appear alongside corporate switchboards, and the same person may appear across multiple email addresses and organisations over time. EML Contacts addresses this through structured entity extraction, conservative consolidation, and human review.
How it works
EML Contacts guides the user through an end-to-end recovery pipeline designed for auditability and control.
Step 01
Ingest standard EML files, native Outlook PST mailboxes, or standard MBOX archives directly from local storage.
Step 02
Combine deterministic analysis with local AI-assisted entity extraction to identify names, roles, phone numbers and companies.
Step 03
Combine repeated observations across years of mail into canonical records for people and organisation roles.
Step 04
Inspect source message evidence, verify confidence ratings, and approve or reject uncertain candidate records.
Step 05
Compare recovered contacts against an existing address book to pinpoint previously missing relationships.
Step 06
Export approved, cleaned contacts to standard CSV, Excel XLSX, or vCard (VCF) formats ready for CRM or mail client import.
Product capabilities
Supports standard EML message files, native Microsoft Outlook PST archives, and standard UNIX/Thunderbird MBOX mailbox formats.
Recovers names, email addresses, telephone numbers, organisations, job roles, websites and postal addresses from message headers, bodies and signatures without assuming perfect formatting.
Uses a local Ollama model to assist signature and contact interpretation. Email archives never leave the local computer and are never uploaded to public cloud LLMs.
Every recovered contact and field retains verifiable evidence back to the underlying source messages, timestamps, and observed raw text.
Merges repeated sightings into canonical records while remaining conservative around shared telephone numbers, departmental role addresses (e.g. info@, sales@) and ambiguous identities.
A structured desktop workspace allows users to inspect contact candidates, review evidence, and accept or reject uncertain records rather than blindly trusting automated output.
Compares extracted contacts against existing contact lists to highlight new contacts and prevent redundant work.
Subsequent extraction builds can be compared against earlier runs, carrying forward prior human review decisions rather than forcing a full re-review.
Outputs cleaned, structured data directly into standard CSV, Excel XLSX, and vCard (VCF) formats for immediate import into address books or CRMs.
Includes project backup and restore capabilities along with local diagnostic bundle generation for troubleshooting without leaking sensitive message content.
Large-archive validation
To ensure the pipeline could operate at realistic scale rather than only on small development fixtures, the architecture was validated against a substantial real-world Outlook archive.
28,982
Emails in archive
14,110
Selected for AI extraction
14,092
Successful extractions
12,435
Contact candidates
542
Canonical contacts
541
Cleaned contacts
516
READY or USABLE
95.4%
READY or USABLE rate
Significance of the validation run: This historical validation established that the processing pipeline, SQLite schema, consolidation logic and Ollama inference engine could operate reliably at production scale across tens of thousands of real messages without memory exhaustion or data corruption. While extraction percentages will naturally vary across different archives and correspondence patterns, it proved that the system scales well beyond synthetic test fixtures.
Local-first architecture
Email archives often contain privileged legal correspondence, confidential financial data, and sensitive personal information.
EML Contacts is architected from the ground up around a strict local-first model: all extraction, inference, database storage, review, backups and exports take place entirely on the user's local machine.
Technology stack
The system maintains a clean boundary between the user-facing desktop application and the underlying data processing engine.
Core domain engine responsible for archive parsing, deterministic extraction rules, LLM orchestration, consolidation, and exposing a local REST API.
Local relational project database with Alembic schema migrations, transaction integrity, and performant indexing across thousands of records.
Local on-device inference using Ollama for signature interpretation, paired with Pydantic for structured validation and typing guarantees.
Modern Windows desktop application shell providing responsive UI, background job monitoring, and review workspaces.
High-performance desktop grids and review controls for sorting, filtering, and managing large volumes of contact records smoothly.
Standalone engine bundling via PyInstaller, clean Windows installer packaging via WiX Toolset, and automated validation with pytest.
Architectural Boundary: The architecture is deliberately split: Python owns the domain logic, archive handling and SQLite project database, while the WPF application provides the desktop user experience. The desktop application communicates with the local engine exclusively through a defined local API; C# does not directly manipulate the SQLite project database.
Engineering method
EML Contacts was not created by giving an AI model one large prompt and accepting the output. It was developed through a long sequence of small, controlled, and reviewable engineering phases.
Product & Engineering Direction
Paul defined the original business problem, established what reviewable recovered contacts should look like, made all architectural decisions, supplied and evaluated real-world email archives, reviewed extraction quality and edge cases, tested desktop workflows, and decided when phases were acceptable.
Engineering judgement, acceptance, privacy, and commercial decisions remained human responsibilities throughout.
Reasoning, specification & review
ChatGPT helped reason about extraction and consolidation architecture, converted technical discussions into phased requirements and PRDs, produced focused implementation prompts, reviewed implementation summaries, identified edge cases, and helped structure validation gates across the programme.
Maintained project continuity and requirements discipline across successive development milestones.
Implementation & verification
Codex worked directly in the codebase, implementing narrowly scoped phases, writing and refining automated tests, running build/test/lint verification, investigating defects, generating evidence reports, and applying corrections across Python, C#, WPF, packaging and tests.
Executed scoped technical tasks against explicit boundaries, test requirements and verification criteria.
Disciplined engineering
EML Contacts was built through a long sequence of deliberately constrained phases. Each phase had explicit requirements, implementation boundaries, automated tests, human review and a decision to correct, freeze or advance.
AI dramatically accelerated implementation and technical investigation, but it did not replace requirements analysis, architecture, testing, evidence collection, code review, human judgement or release discipline.
Feedback loop
Every feature, refactor and bug fix moved through a controlled, repeatable cycle before code was accepted into the main tree.
01
A real problem, requirement or defect is identified from testing or archive data.
02
Paul and ChatGPT discuss constraints, edge cases and architectural impact.
03
ChatGPT generates a focused, bounded implementation and review prompt.
04
Codex writes the code, updates schemas and creates automated test coverage.
05
Codex reports test results, diff evidence and flags any unresolved edge cases.
06
Paul reviews the desktop behaviour, extraction results and code quality.
07
ChatGPT reviews evidence, preparing corrections or framing the next phase.
08
Stable semantics are frozen into regression tests before advancing.
Evidence-driven development
Architecture decisions were not dogmatic; when empirical evidence conflicted with initial assumptions, the project adapted.
Dedicated research investigated whether deterministic heuristics and regular expressions could replace local LLM extraction for a sufficient percentage of messages to eliminate AI dependencies. The empirical evidence showed too many varied, unstructured signature conventions to achieve acceptable recall deterministically.
Decision: Retained the local LLM extraction path as a core workflow component.
Research evaluated whether sending a small, privacy-minimised payload to a remote inference server could improve processing speed while protecting privacy. The complexity, network dependency, and residual privacy trade-offs did not justify moving away from on-device inference.
Decision: Retained 100% local Ollama inference on the user's machine.
Support for Outlook PST and standard MBOX formats was introduced as distinct importer phases rather than allowing format-specific quirks to leak across the core extraction and consolidation engine.
Decision: Maintained strict modular decoupling between archive ingestion and contact consolidation.
UI work did not begin until the processing, consolidation, schema migrations and local API contracts were thoroughly validated via automated test suites.
Decision: Ensured UI development focused purely on user experience over rock-solid backend semantics.
Packaging, project backups, uninstall data preservation, clean-machine installation, open-source delivery notices, and website release gates were executed in dedicated phases rather than left as afterthoughts.
Decision: Applied full engineering rigor and automated validation through to final packaging.
Phased development
Development was organized into high-level functional stages, freezing stable semantics at milestones so subsequent work did not compromise validated extraction behavior.
Extraction and evidence
Consolidation and canonical cleanup
Quality and review semantics
PST and MBOX archive import
Address-book comparison
Incremental build comparison
Review decision carry-forward
Local FastAPI engine & API contracts
WPF desktop shell & layout
Project, import & processing workflow
Contact review workspace
Address-book comparison workspace
Build comparison & carry workspace
Export, settings & diagnostics
Release engineering & packaging
Website, support & release preparation
Quality assurance
Testing was integral to every phase rather than deferred to the end of development. Verification evidence accompanied each implementation milestone.
Comprehensive pytest suites covering parsing, extraction algorithms, SQLite database interactions, and Alembic migrations.
Desktop application unit tests validating view models, state management, API communication, and command execution.
Dedicated test fixtures for standard EML messages, complex nested Outlook PST files, and standard MBOX archives.
Validation of OpenAPI schemas, request/response models, error handling, and authentication tokens.
Manual and automated verification of DevExpress grid interactions, filtering, search, and review actions.
Full installation, execution, and uninstallation audits on isolated, clean Windows virtual machines.
Verification of installer binaries, file associations, registry keys, and runtime dependency bundles.
Automated generation of synthetic PST archives to stress-test rebuild and consolidation logic.
Baseline regression suites executed before freezing milestone semantics to prevent unintended behavioral drift.
Release discipline
Shipping a commercial desktop application requires extensive operational rigor beyond writing code.
Current public status: Preparing for first public release.
Commercial value
Built for professionals and organisations where historical correspondence holds substantial commercial, legal or operational value.
Solicitors, accountants, management consultants, executive recruiters, financial advisers, estate agents, membership bodies, sales teams, and SMEs with legacy email archives.
Product status
EML Contacts is currently in final preparation for its initial public release. The product informational website is live and details supported archive formats, local-first privacy specifications, and upcoming availability.
The public EML Contacts website explains the product, local-first privacy model, supported archive formats and current release status.