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.
Metadata
Release files for shmail 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shmail-0.1.0.tar.gz | 6.9 kB | Without provenance | Details for shmail-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shmail-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for shmail-0.1.0-py3-none-any.whl |
Total release size: 15.7 kB
Release files / shmail-0.1.0.tar.gz
| Download URL | shmail-0.1.0.tar.gz |
|---|---|
| Size | 6.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a12350bb783c9532a8f33ac5535ac4d0a374ec8f5dac6342c76d8fea72e3ff72
|
|
BLAKE2b-256 checksum How to use checksums |
d065b84602911ffb1ac5466e03a0de19cdfb9cb790a0743746117312450abb59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / shmail-0.1.0-py3-none-any.whl
| Download URL | shmail-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d55b7414c832fb03bc0ecbb6c78b38646203abcf522251239483991f733541d7
|
|
BLAKE2b-256 checksum How to use checksums |
fafb5f0969128febd864a877e4650c3bb3322b0eb31b0af87553da9c7b374e46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for shmail 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.