📧 MixMail

Talk to your Gmail in plain English. MixMail is a command-line agent that turns natural-language requests — "summarize the visa thread", "draft a reply saying I'm available Friday", "archive this month's promotions" — into real Gmail actions. It runs on any OpenAI-compatible LLM, local or hosted.

pip install mixmail
mixmail

You ❯ what came in from recruiters this week, and star anything urgent
· Searching Gmail…
MixMail ▸
You have 3 recruiter emails this week:
  1. Amazon Recruiting — "ML Engineer, Seattle" (Tue) ★ starred
  2. Deloitte Talent — "Interview scheduling" (Mon)
  3. Stealth Startup — "Founding engineer" (Mon)

What it can do

• Safety first. Sending, replying, and trashing always show a preview and ask for confirmation. Gmail access defaults to read-only until you opt in to full.
• Streaming. Answers stream as they're generated, with live progress for each tool the agent runs.
• Bring your own model. Local (LM Studio, llama.cpp, Ollama, vLLM) or hosted (OpenAI, Groq, Together, OpenRouter). Use OpenRouter to run Claude or Gemini through the same interface.

Install

pip install mixmail        # from PyPI
mixmail                    # first run launches a guided setup wizard

Or from source:

git clone <your-fork> && cd MixMail
pip install -e ".[dev]"

Setup

On first launch MixMail walks you through setup. You can re-run it anytime with /wizard. You'll need two things:

1. A language model

MixMail talks to an OpenAI-compatible Chat Completions endpoint.

• Local (no API key): start your server and use its base URL, e.g. http://localhost:1200/v1.
• Hosted: set the base URL and an API key, e.g. OpenAI (https://api.openai.com/v1), Groq, Together, or OpenRouter. For Claude or Gemini, use OpenRouter's base URL and a model id like anthropic/claude-3.5-sonnet.

Configure inside the app with /llm_url, /model, and /api_key.

2. Gmail credentials

1. In the Google Cloud Console, create a project and enable the Gmail API.
2. Configure the OAuth consent screen (add your address as a test user).
3. Create an OAuth client ID of type Desktop app and download the JSON.
4. In MixMail, run /mail_creds and paste the JSON or its file path.

On your first query MixMail opens a browser for Google sign-in and stores the token automatically.

Choosing access level

/scope

• readonly (default) — search and read only.
• full — also send, reply, draft, label, archive, and trash.

Switching scope requires re-authenticating: delete the token shown in /setup and sign in again.

Commands

Configuration

All settings live in ~/.mixmail/.env (or a .env in the working directory). See .env.example. Key variables:

How it works

You ──▶ mixmail CLI ──▶ EmailAgent ──▶ LLM (tool-calling)
                              │              │
                              │     tool calls (search, send, …)
                              ▼              ▼
                        confirmation     Gmail API

The agent sends your message plus tool descriptions to the model, runs whatever tools the model requests (asking you first for destructive ones), feeds results back, and repeats until it has a final answer — which it streams to you.

Development

pip install -e ".[dev]"
python -m unittest discover -s tests -t .   # or: pytest
python -m build                              # build a wheel + sdist

The test suite stubs out Google and network access, so it runs anywhere without touching your real inbox.

Security notes

• MixMail runs entirely on your machine; your email and API key never leave it except to the LLM endpoint and Gmail you configure.
• .env, token.json, and client_secret*.json are git-ignored. Don't commit them. If you ever did, rotate the credentials.
• Read-only is the default. Grant full access only when you want MixMail to send or modify mail.

License

MIT — see LICENSE.