Metadata-Version: 2.4
Name: shmail
Version: 0.1.0
Summary: Read-only Python library and CLI for the Superhuman local mail database
Keywords: superhuman,email,sqlite,electron,macos
Author: Guido Appenzeller
Author-email: Guido Appenzeller <guido@appenzeller.net>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/appenz/shmail
Project-URL: Issues, https://github.com/appenz/shmail/issues
Project-URL: Repository, https://github.com/appenz/shmail
Description-Content-Type: text/markdown

# shmail

Read-only access to the Superhuman email client's local offline database on macOS.

Superhuman is an Electron app that caches your entire mailbox in a local
SQLite database (via WebSQL). shmail extracts and queries that database
directly — no API keys, no network requests, no temp files.

## Requirements

- Python 3.13+ (for `sqlite3.deserialize`)
- macOS with Superhuman desktop app installed
- No third-party dependencies

## Quick Start

### CLI

```bash
python3.13 cli.py --inbox 10          # recent inbox threads
python3.13 cli.py --search "GPU"      # full-text search
python3.13 cli.py --show 19db387d     # full thread by ID prefix
python3.13 cli.py --splits            # list split inboxes
python3.13 cli.py --split Infra 5     # threads in a split inbox
python3.13 cli.py --contacts          # top contacts by frequency
python3.13 cli.py                     # interactive shell
```

See [docs/cli.md](docs/cli.md) for the full CLI reference.

### Library

```python
from shmail import Mailbox

with Mailbox() as mb:
    # Browse inbox
    for t in mb.inbox(10):
        print(t.short_id, t.subject, t.latest_date)

    # Full-text search
    for t in mb.search("quarterly report"):
        print(t.subject, [str(a) for a in t.participants])

    # Read a full thread
    thread = mb.thread("19db387d")
    for msg in thread.messages:
        print(msg.date, msg.sender, msg.snippet)

    # Split inboxes
    for split in mb.split_inboxes:
        threads = mb.split_inbox_threads(split)
        print(f"{split.name}: {len(threads)} threads")
```

See [docs/library.md](docs/library.md) for the full library reference.

## Architecture

```
cli.py                 Thin CLI — formatting and argument parsing only
  |
shmail/
  mailbox.py           Mailbox — high-level Python API (the public interface)
  store.py             SuperhumanStore — SQL queries, JSON parsing, file I/O
  models.py            Frozen dataclasses: Thread, Message, Contact, etc.

specs/
  database.md          Reverse-engineered Superhuman database format

docs/
  cli.md               CLI reference
  library.md           Library reference
```

All domain objects are immutable frozen dataclasses. The store layer is the
only code that touches SQL or the filesystem. The CLI contains zero business
logic — it calls `Mailbox` methods and formats the output.

## Data Location

Superhuman stores its SQLite database inside Chromium's File System API at:

```
~/Library/Application Support/Superhuman/File System/001/t/00/00000001
```

The file has a 4096-byte Chromium header; the actual SQLite database starts at
that offset. shmail uses `sqlite3.deserialize()` to load it directly into
memory (~220 MB, ~0.1s) with no extraction step.

See [specs/database.md](specs/database.md) for the full reverse-engineered
database specification.