InboxQL is a mailbox you can ask questions of. It keeps a copy of your mail on your own computer, in a database you can query, and puts a mail client, an analytics dashboard and a query language on top of it.
It is built for people who would rather type from:*@stripe.com after:2026 | sum receipts.amount by month than scroll. You do not have to start there —
it reads mail like any other client — but everything it shows you is a query,
and every query is something you can change.
What it is, and what it is not
It is local. Your mail is copied into a database on this machine. Nothing is sent anywhere unless you set up a remote AI provider and then ask it to read something — and even then, InboxQL asks first. See Privacy.
It is a server you open in a browser. InboxQL runs in the background and
you use it at http://localhost:8420. That makes it one program on every
platform, and it means an agent or a script can use the same mailbox you do.
It is your mail client. It keeps a full copy of each account, current both ways: new mail arrives in seconds, and archiving, labelling or reading here does the same on the server. It sends mail, with a few seconds to undo. Mail has labels, as in Gmail, rather than folders.
It is early. The mail client, the query language, labels, contacts, files and tickets all work. Some things are deliberately not there yet — there is no calendar, and search is by words, not by meaning.
Install it
One command. It downloads the release for your computer, checks it against
the published checksums, installs it in ~/.iql, and starts InboxQL when you
log in.
On macOS or Linux:
curl -fsSL https://techmuch.github.io/InboxQL/install.sh | sh
On Windows, in PowerShell:
irm https://techmuch.github.io/InboxQL/install.ps1 | iex
Then open http://localhost:8420 — or type iql open, which opens whatever
address the running server is at. Installing, updating and
removing has the details, including what each file is for.
Finding your way around
The menus along the top:
| Menu | What is in it |
|---|---|
| File | New message, New event, New task; importing mail and calendars; Settings |
| Go | the places: Desk, Calendar, Board, Contacts, Files, the Dashboard |
| View | the chat panel, how conversations and viewer tabs behave, the theme, Windows and the Log |
| Intelligence | Waiting for approval, Labels & extractors, the AI assistants on this computer |
| Help | this documentation, keyboard shortcuts, the guide for agents, updates, About |
Your name at the top right has your profile, Settings and Sign out. And Ctrl+K (⌘K) finds any of it by name, every setting included.
A small ? beside a heading — on the Desk’s rail, the query bar, a Settings section, the Calendar and the rest — opens the part of this documentation that explains it. Going the other way, a link marked ↗ in a guide opens the place in the application it describes: Settings at that setting, or a tab.
Your first hour
1. Add an account
Open Settings → Mail Accounts and choose Add account. Type your address: InboxQL works out the servers. Then the password — for iCloud, Yahoo and most providers with two-step sign-in an app password, not the one you sign in with; Gmail can use Sign in with Google instead. InboxQL signs in before saving and says exactly what went wrong if something does: a rejected password, a server name that does not exist, a server that did not answer. Accounts has the details.
Saving the account connects it, and it stays connected: you never need to press Sync. The first time, it reads the whole account, newest first, so this week’s mail is there in minutes and older mail fills in behind it — a large Gmail account can take a few days. The account’s card says how far it has got.
Already have years of mail in Apple Mail? Importing reads it straight from Mail’s own files, without changing them.
2. Find your way around the Desk
The Desk is where mail is read. The rail on the left lists your folders, your saved queries and the labels that have found something. Clicking one puts its query in the bar at the top, so you learn the language by watching it.
Use the arrow keys to move through the list; the message opens beside it. The Desk covers the rest.
3. Ask it something
Type into the query bar:
from:me() after:30d | count by week
That is how much mail you sent in each of the last four weeks. Replace
count by week with top to 10 for the ten people you wrote to most. The
query language has the full list.
4. Let it sort your mail
Install the elements — receipts, travel, calendar events, tasks, who is
waiting, importance, what kind of sender someone is, topics — with
iql elements install, then ask the AI you already use (Claude Code,
Antigravity) to run iql work guide and read your newest conversations.
Reading with your AI harness explains the loop, and
Labels how to correct an answer when it is wrong.
5. See how it is running
Help → About InboxQL opens the System section of Settings: which version this is, where your mail is stored and why, whether it is running as your login service, and whether there is an update. Settings describes all of it.
Where to next
- The Desk — reading, conversations, keyboard.
- The query language — the part worth learning.
- Contacts — who is waiting for you, and whom you are waiting on.
- Troubleshooting — when something is not right.
Everything here is also in the application, under Help → Documentation, and describes the version you are running.