Superhuman Mail

Overview

An unofficial CLI and Python client for Superhuman, built by reverse-engineering the private API. It reads credentials directly from the local Superhuman desktop app — no manual config, no OAuth dance. Just shm setup and go.

I built this because I wanted my AI agent to manage email the same way I do — through Superhuman, not Gmail. The official MCP beta exists but doesn't cover what I need: read receipts, draft sharing, scheduled sends, and the kind of thread search that Superhuman is actually good at.

What it does

• Threads — search, list, read messages from the local cache
• Read receipts — inspect per-thread opens and the Recent Opens feed
• Drafts — create reply, reply-all, forward, and compose drafts with smart-send options (scheduled sends, abort-on-reply, reminders)
• Draft management — read, discard, attach files, share and unshare drafts
• Comments — post, read, and discard thread comments
• Send — validate and send with an explicit safety gate (--dry-run or --confirm required)

Design

Every command returns the same JSON envelope:

{"status": "succeeded", "command": "...", "data": {...}, "errors": [], "warnings": []}

No tables, no pretty-printing, no alternate modes. Agents always get the same shape. Humans pipe to jq.

Errors are structured for agent recovery — each one has a class (auth, network, not-found, input, conflict, rate-limit), a code, a retryable flag, and a hint. This matters when the agent is composing multi-step email workflows and needs to know whether to retry or bail.

Safety tiers

Usage

# Bootstrap from local Superhuman app
shm setup
shm doctor

# Search and read
shm thread search "quarterly review"
shm thread messages <thread_id>

# Check who opened your email
shm opens <thread_id>
shm opens --recent --limit 10

# Draft and send
shm draft reply <thread_id> --body "Thanks for the update"
shm draft reply <thread_id> --body "Following up" --scheduled-for "2026-03-26T09:00:00Z"
shm send --dry-run <thread_id> <draft_id>
shm send --confirm <thread_id> <draft_id>

There's also a Python client:

from superhuman_mail import Client

c = Client()
c.thread.search("quarterly review")
c.draft.create_reply("19d001f35612a211", body="Thanks!")
c.opens.recent(limit=10)

Installation

As a Pi package (includes the agent skill):

pi install git:github.com/tmustier/superhuman-mail

Or standalone:

git clone https://github.com/tmustier/superhuman-mail.git
cd superhuman-mail
pip install -e .
shm setup && shm doctor

Requires the Superhuman desktop app installed and signed in. Python 3.11+.

Why not just use Gmail?

I do, for some things. But Superhuman's local cache is fast, the read receipt data isn't available through Gmail, and when I'm asking an agent to draft a reply, I want the draft to appear in the same app where I'll review and send it — not in a separate Gmail interface I never look at.