{"id":50512462,"url":"https://github.com/appenz/shmail","last_synced_at":"2026-06-02T21:03:29.370Z","repository":{"id":356651366,"uuid":"1218252189","full_name":"appenz/shmail","owner":"appenz","description":"CLI and python library to access the local Superhuman Mail offline database. Pure python, no external dependencies, works offline, does not require credentials.","archived":false,"fork":false,"pushed_at":"2026-04-22T19:01:56.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T05:10:08.771Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appenz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T17:29:14.000Z","updated_at":"2026-04-22T19:01:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/appenz/shmail","commit_stats":null,"previous_names":["appenz/shmail"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/appenz/shmail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appenz%2Fshmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appenz%2Fshmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appenz%2Fshmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appenz%2Fshmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appenz","download_url":"https://codeload.github.com/appenz/shmail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appenz%2Fshmail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33835766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T21:03:28.419Z","updated_at":"2026-06-02T21:03:29.364Z","avatar_url":"https://github.com/appenz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shmail\n\nRead-only access to the Superhuman email client's local offline database on macOS.\n\nSuperhuman is an Electron app that caches your entire mailbox in a local\nSQLite database (via WebSQL). shmail extracts and queries that database\ndirectly — no API keys, no network requests, no temp files.\n\n## Requirements\n\n- Python 3.13+ (for `sqlite3.deserialize`)\n- macOS with Superhuman desktop app installed\n- No third-party dependencies\n\n## Quick Start\n\n### CLI\n\n```bash\npython3.13 cli.py --inbox 10          # recent inbox threads\npython3.13 cli.py --search \"GPU\"      # full-text search\npython3.13 cli.py --show 19db387d     # full thread by ID prefix\npython3.13 cli.py --splits            # list split inboxes\npython3.13 cli.py --split Infra 5     # threads in a split inbox\npython3.13 cli.py --contacts          # top contacts by frequency\npython3.13 cli.py                     # interactive shell\n```\n\nSee [docs/cli.md](docs/cli.md) for the full CLI reference.\n\n### Library\n\n```python\nfrom shmail import Mailbox\n\nwith Mailbox() as mb:\n    # Browse inbox\n    for t in mb.inbox(10):\n        print(t.short_id, t.subject, t.latest_date)\n\n    # Full-text search\n    for t in mb.search(\"quarterly report\"):\n        print(t.subject, [str(a) for a in t.participants])\n\n    # Read a full thread\n    thread = mb.thread(\"19db387d\")\n    for msg in thread.messages:\n        print(msg.date, msg.sender, msg.snippet)\n\n    # Split inboxes\n    for split in mb.split_inboxes:\n        threads = mb.split_inbox_threads(split)\n        print(f\"{split.name}: {len(threads)} threads\")\n```\n\nSee [docs/library.md](docs/library.md) for the full library reference.\n\n## Architecture\n\n```\ncli.py                 Thin CLI — formatting and argument parsing only\n  |\nshmail/\n  mailbox.py           Mailbox — high-level Python API (the public interface)\n  store.py             SuperhumanStore — SQL queries, JSON parsing, file I/O\n  models.py            Frozen dataclasses: Thread, Message, Contact, etc.\n\nspecs/\n  database.md          Reverse-engineered Superhuman database format\n\ndocs/\n  cli.md               CLI reference\n  library.md           Library reference\n```\n\nAll domain objects are immutable frozen dataclasses. The store layer is the\nonly code that touches SQL or the filesystem. The CLI contains zero business\nlogic — it calls `Mailbox` methods and formats the output.\n\n## Data Location\n\nSuperhuman stores its SQLite database inside Chromium's File System API at:\n\n```\n~/Library/Application Support/Superhuman/File System/001/t/00/00000001\n```\n\nThe file has a 4096-byte Chromium header; the actual SQLite database starts at\nthat offset. shmail uses `sqlite3.deserialize()` to load it directly into\nmemory (~220 MB, ~0.1s) with no extraction step.\n\nSee [specs/database.md](specs/database.md) for the full reverse-engineered\ndatabase specification.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappenz%2Fshmail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappenz%2Fshmail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappenz%2Fshmail/lists"}