https://github.com/appenz/shmail
CLI and python library to access the local Superhuman Mail offline database. Pure python, no external dependencies, works offline, does not require credentials.
https://github.com/appenz/shmail
Last synced: about 2 months ago
JSON representation
CLI and python library to access the local Superhuman Mail offline database. Pure python, no external dependencies, works offline, does not require credentials.
- Host: GitHub
- URL: https://github.com/appenz/shmail
- Owner: appenz
- License: apache-2.0
- Created: 2026-04-22T17:29:14.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-22T19:01:56.000Z (3 months ago)
- Last Synced: 2026-05-09T05:10:08.771Z (3 months ago)
- Language: Python
- Size: 35.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.