Skip to main content

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)

Source distribution for shmail 0.1.0
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)

Table of built distributions (wheels) for shmail 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page