pyoeclassic 0.2.4

Fast full-text search and MCP server for OE Classic email — sub-second Whoosh search over large mailboxes, plus read/write/send tools for AI agents

pyoeclassic

Fast full-text search and MCP server for OE Classic email. Indexes your entire mailbox with Whoosh for sub-second search across tens of thousands of messages, and exposes read, write, and send operations as a local MCP server so AI agents (Claude, Codex) can search, file, move, and send email directly — using OE Classic's own stored Gmail and Microsoft OAuth credentials for outbound mail. No cloud dependency, no new OAuth setup.

Installation

pip install -e .

Quick Start

from pyoeclassic import Client

# Connect to an identity
client = Client(identity="Testing")

# List folders
for folder in client.folders.list():
    print(f"{folder.name}: {folder.total_count} emails")

# Access emails
inbox = client.emails("Inbox")
print(f"Total: {inbox.count()}, Unread: {inbox.unread_count()}")

# Search emails
results = inbox.search(subject="*report*", limit=10)

# Get full email content
email = inbox.get(1)
print(email.body_text)

# Export emails
inbox.export("backup.jsonl", format="jsonl")

OEC Browser

A simple command-line tool for browsing OE Classic email data:

# Interactive mode (menu-driven)
python oec_browser.py

# List folders and email counts
python oec_browser.py --list

# Show all files in identity folder
python oec_browser.py --all-files

# List detached folders (files not in database)
python oec_browser.py --detached

# Browse a specific folder
python oec_browser.py --folder Inbox

# Browse a detached folder directly
python oec_browser.py --detached-folder "Archive"

# Search by subject or sender
python oec_browser.py --search-subject "report" --search-folder Inbox
python oec_browser.py --search-sender "[e-mail]"

# Analytics
python oec_browser.py --stats              # Folder statistics
python oec_browser.py --top-senders Inbox  # Top senders in folder
python oec_browser.py --top-senders-all    # Top senders across all folders

Interactive Menu Features

• Browse: Folder tree, detached folders, all files
• Search: By subject, sender, or content (single folder or all)
• Analytics: Folder stats, top senders, top domains

CLI

# List identities
pyoeclassic identities

# Show identity info
pyoeclassic info -i Testing

# List folders
pyoeclassic folders list --tree

# Folder operations
pyoeclassic folders attach "MyFolder"
pyoeclassic folders detach 5
pyoeclassic folders status

# Email operations
pyoeclassic emails list -f Inbox
pyoeclassic emails search "*report*" -f Inbox
pyoeclassic emails export backup.jsonl -f Inbox

MCP Service (Internal Install)

The OE Classic search/write MCP server is packaged as optional PyOEClassic features for the local Windows automation setup:

pip install -e ".[all]"
pyoeclassic-mcp --host 127.0.0.1 --port 8093
pyoeclassic-build-index --update

The Windows service wrapper can be installed/refreshed through a local deployment script that runs the packaged service module under a Python environment with pywin32. The service is intentionally local-only (127.0.0.1:8093) and bound to Main Identity.

The local Windows runtime is installed under:

C:\Servers\oeclassic-email-mcp

Use these runtime commands on this workstation:

C:\Servers\oeclassic-email-mcp\refresh.cmd
C:\Servers\oeclassic-email-mcp\remove.cmd

Runtime state is split from source: logs and the search index live under the runtime directory, local secrets and workstation paths live in config\local.env.cmd, and package source remains in the MBX checkout.

External Gmail/Hotmail sending is handled by queueing messages into OE Classic so OE can use its existing account authentication. The packaged MCP does not ship the abandoned direct Gmail API send path.

OE Classic Corruption Recovery

Operational recovery notes are included for agents and operators:

• Human runbook: docs/runbooks/oeclassic-corrupt-mbx-recovery.md
• Packaged LLM card: pyoeclassic/llm/oeclassic-corruption-recovery.md

The short version: stop OE Classic and PythonOEClassicEmailMCP, back up the .mbx/.db pair, repair copied files first, and deploy only after structural verification passes.

Folder Attach/Detach

Archive old folders by detaching them:

from pathlib import Path
from pyoeclassic import Client

client = Client(identity="Testing")

# Detach folder and move files to archive
client.folders.detach_to_archive(
    folder_id=5,
    archive_path=Path("/backups/email_archive")
)

# Re-attach later
client.folders.attach_from_archive(
    name="OldEmails",
    archive_path=Path("/backups/email_archive")
)

Safety

The library protects "Main Identity" from write operations. Test identities (Testing, Testing2, Testing3) are safe for development.

Project Structure

pyoeclassic/           # Main library
  client.py            # Client class
  core/                # Config, database, MBX parser
  operations/          # Folder and email managers
  models/              # Folder and Email models
  cli/                 # Command-line interface
  runtime/             # Packaged Windows service runtime assets

oec_browser.py         # Simple browser tool
examples/              # Example scripts
tests/                 # Test suite
_legacy/               # Old scripts (archived)

MBX File Format

OE Classic MBX files use a specific format:

• [hdr] - Message header marker
• mlen=<hex> - Message length in hexadecimal
• [msg] - Message content follows

Running Tests

pytest