shmail 0.1.0

Read-only Python library and CLI for the Superhuman local mail database

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

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 for the full CLI reference.

Library

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 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 for the full reverse-engineered database specification.