imail

Triage your inbox in five seconds per email.
Local app · multi-provider · 3 LLM-drafted replies per message · keyboard-first.

🧭 The idea

You wake up to 30 emails. Each one needs a yes / no / "let me get back to you." Each takes 30 seconds of phrasing even though the decision takes one. imail flips it: the phrasing is one keystroke, the decision is yours.

┌──────────────────────────────────────────────────────────────┐
│  From       advisor@uni.edu                                  │
│  Subject    Can you join the panel on Thursday?              │
│  …                                                           │
└──────────────────────────────────────────────────────────────┘
  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
  │ 1·POSITIVE  │   │ 2·NEUTRAL   │   │ 3·NEGATIVE  │
  │ Yes, I'll … │   │ Let me  …   │   │ Thanks for  │
  │             │   │             │   │ asking, but │
  └─────────────┘   └─────────────┘   └─────────────┘
   1 / 2 / 3 → save draft     S → skip     Q → end session

🚀 Install

Pick whichever fits your setup. The command after install is always imail.

uv tool install \
  imail-cli

pipx install \
  imail-cli

brew install \
  jessecu2024/tap/imail

docker pull \
  ghcr.io/jessecu2024/imail

💡 Distribution name on PyPI is imail-cli (the bare imail slot was taken). The command you run after install is still imail.

⚡ First run

export DEEPSEEK_API_KEY=sk-...   # https://platform.deepseek.com/api_keys (free signup)
imail                             # opens http://127.0.0.1:8765

First boot lands on an "Add account" screen. Pick Gmail / Outlook / 163 / etc., sign in once, you're triaging.

Docker variant (no Python needed locally):

docker run --rm -p 8765:8765 \
  -v ~/.config/imail:/root/.config/imail \
  -e DEEPSEEK_API_KEY=sk-... \
  ghcr.io/jessecu2024/imail:latest

The mounted ~/.config/imail keeps your accounts and saved replies between container restarts.

✨ Why imail

🔌 Mail providers

🚧 Work or school account locked down? (CityU, many universities, some enterprises.) See docs/forwarding-workflow.md for the validated forwarding-to-personal fallback — adds your work mail to imail in 5 minutes of server-side setup, no code needed.

⚙️ Configuration

All settings come from .env or environment variables.

🧑‍💻 Develop

git clone https://github.com/jessecu2024/imail
cd imail
uv sync                      # install dev + runtime deps
cp .env.example .env         # fill in DEEPSEEK_API_KEY
uv run imail                 # → opens http://127.0.0.1:8765

CI quartet, run anything before pushing:

uv run ruff check .          # lint
uv run ruff format .         # format
uv run mypy src              # type check
uv run pytest                # tests

Release flow: see docs/release.md. The short version is "bump pyproject + tag vX.Y.Z + push" — the workflow publishes to PyPI via Trusted Publishing and to GHCR via OIDC, then attaches the wheel to a GitHub release.

📁 Project layout

src/imail/
  cli.py                Launcher — boots uvicorn + opens browser
  config.py             .env loader
  server.py             FastAPI app — status, accounts, triage session
  accounts.py           Account manifest + keyring-backed secrets
  reply_generator.py    DeepSeek call + JSON parser
  reply_store.py        On-disk pending/done state per account
  providers/
    base.py             EmailMsg + MailProvider Protocol
    gmail.py            Gmail API provider (OAuth)
    imap.py             Generic IMAP provider with presets (Outlook/163/QQ/…)
  static/
    index.html          Single-page UI (Alpine.js)
    app.js              SPA state + handlers
    style.css           Light theme
    icon.svg            Brand mark
docs/
  gmail-setup.md        Google Cloud Console walk-through
  imap-setup.md         Per-provider app-password steps
  forwarding-workflow.md Locked-tenant fallback (163 as relay)
  release.md            How to cut a PyPI release
  troubleshooting.md    Recurring problems (macOS keychain after brew upgrade, …)

🔒 Security

• 📧 Gmail OAuth scopes: gmail.readonly (fetch), gmail.modify (mark-read / archive), gmail.compose (drafts), and gmail.send (one-keystroke send from the triage view). If you'd rather only ever save drafts and send manually from Gmail, remove gmail.send from SCOPES in src/imail/providers/gmail.py and revoke the token.
• 🔑 IMAP app passwords stay in the OS keyring, never in accounts.json or .env.
• 🔐 OAuth tokens live at ~/.config/imail/token-<account-id>.json (mode 0600).
• 🏠 Local-only by default. Server listens on 127.0.0.1. Don't move it to 0.0.0.0 on a shared machine.
• ☁️ Email content reaches DeepSeek's servers. If you'd rather keep all bodies on-device, point IMAIL_BASE_URL at a self-hosted Ollama / vLLM endpoint running an instruction model.

📜 License

Dual-licensed. Pick whichever fits your use.

• 🆓 AGPL-3.0-or-later (default) — full text in LICENSE. You're free to use, modify, fork, and self-host. The catch: if you modify and either redistribute or run it as a network service (SaaS, hosted product, anything end users reach over a network), your modifications must also be AGPL-3.0. The standard "no closed-source forks, no proprietary SaaS rebrand" guarantee — see the GNU AGPL FAQ for the rationale.
• 💼 Commercial license — if AGPL's copyleft obligations don't fit your product (proprietary version, closed-source SaaS, distributing imail as a library without exposing your source), email wzh4464@gmail.com.

Versions ≤ 1.3.0 on PyPI were published under MIT. From v1.3.1 onward the license is AGPL-3.0-or-later (or commercial). If you installed imail-cli==1.3.0 you remain on MIT terms for that copy.

🤝 Contributing

Issues and PRs welcome — use the bug report or feature request templates. For substantial changes, open an issue first so we can align on the shape before you write code.

See CHANGELOG.md for what shipped in each version.