The query language

Everything InboxQL shows you is the answer to a query, and every query is something you can type. This page is the whole language. It is short, because most of its power comes from a few pieces that combine.

A query is a filter, optionally followed by stages after a |:

from:*@stripe.com after:2026-01-01 has:attachment
is:unread -from:*@acme.com | count by week

The same text works in the Desk’s query bar and on the command line, as iql query "…".

Filters

Terms written side by side must all match. OR gives alternatives, and parentheses group:

from:alice subject:invoice
from:alice OR from:bob
(from:alice OR from:bob) after:2026-06

People and addresses

from:me() is your own addresses — the ones on the accounts you set up — so to:me() is mail sent to you and from:me() is what you sent.

from:(alice OR bob) scopes a group to one field, which saves repeating it.

Words

These match whole words: subject:invoice finds invoice, not invoiced hidden inside another word. Use subject:*invoice* for any text containing it.

Search is by words, not by meaning. invoice does not find billing. When it matters, ask more than one way: subject:(invoice OR bill OR receipt).

Where mail is

Mail has labels, not folders, as in Gmail: the system ones — inbox, sent, drafts, important, spam, trash — and your own. A message carries any number. folder: names views over them: folder:inbox is label:inbox outside Spam and Trash, folder:archive is mail not in the inbox (outside Spam and Trash), and folder:allmail is everything but Spam and Trash. They overlap, as labels do.

Trash and Spam stay out unless you ask

A query leaves out mail in Trash and Spam unless it mentions them, as Gmail’s search does. from:bob is Bob’s mail you have kept; the newsletter of his you binned, and the spam sent in his name, are not in it. That goes for everything built on queries: counts, charts, the Dashboard, a contact card’s figures, saved queries and annotators.

Each bin comes back when the query mentions it, and only that one:

• Trash — folder:trash, label:trash, is:deleted
• Spam — folder:spam, label:spam, is:junk
• Both — folder:all, which is how you say “everywhere”

A mention counts anywhere in the query: inside ( … OR … ), after a -, or in a saved: query it uses. id: names messages exactly, so a query with one finds them wherever they are.

When a list leaves something out, the Desk says so under the query bar — “3 more in Trash or Spam” — with Show them, which adds folder:all. A conversation says what it holds back, too: “4 messages · 1 in Trash”. --explain and iql query say the same.

State

Time and size

Conversations

thread:<message-id> is every message in that conversation. The | thread stage, below, expands any list to whole conversations.

Files

attached:contract is mail that carried a file named contract; attached:*.pdf after:7d is mail with a PDF on it this week. Given eight or more hex characters, attached: matches a file’s content fingerprint instead, so it finds the same document whatever it was called. Files has more.

Labels and extracted values

label: answers for both kinds of label: the ones you, Gmail or your other mail client put on, and the ones an annotator decides. A label of yours is there or it is not. An annotator’s has three states, not two, and this is the thing in the language most worth getting right. -label:x means the annotator evaluated the message and said no. It does not include mail the annotator has never seen — if it did, a label that had read a tenth of your mailbox would present the other nine tenths as a negative answer. When you do want both, ask for both: -label:x OR unlabeled:x. See Labels.

When one name is both — you made a label called purchased and an annotator has the same name — label:purchased is either one saying yes, and -label:purchased is neither.

Saved queries

saved:clients is everything the saved query clients matches, so it combines with anything: saved:clients after:7d is:unread.

Three ways to match

from:acme          contains "acme" — also notacme@x.com
from:=a@acme.com   exactly this address
from:*@acme.com    a pattern; * stands for any run of characters

They are different questions, so the language keeps them apart instead of guessing which you meant.

Leaving things out

- or NOT in front of any term or group leaves out what it matches:

-from:alice
-(from:alice after:2026-01)
from:*@acme.com -to:bob@acme.com

On recipients, -to:bob means no recipient is Bob — not “some recipient is not Bob”, which would match nearly every message with more than one recipient.

What a query is about

A query is about one kind of thing. Mail is the default; in: says otherwise:

A field that only one kind has implies it: due:7d is about tickets, origin:agent about drafts. Each kind adds its own fields — kind:system for contacts, filetype:pdf for files, level>warn for the log — and the guides for contacts, files and tickets list them. Message fields still work inside them and ask about the mail behind the thing: in:attachments from:*@acme.com is files that came from Acme.

Calendar events

in:events asks about the calendar. A row is one occurrence — a weekly meeting is fifty-two rows a year — because that is what “what is on” and “how many hours” are about.

A proposal an agent made is left out of lists and totals unless you ask for it with is:proposed. Group events by calendar, attendee, domain, organizer, status, title, or a time bucket, and add up their length with | sum hours or | sum minutes:

in:events after:30d | sum hours by attendee
in:events next:14d | count by day

Stages

After a |, a stage changes what comes back. A query has at most one stage that adds things up.

You can group by from, domain, to, cc, account, mailbox, label, thread and subject; by hour, day, week, month and year; and by any extracted value, written annotator.field — | count by receipts.merchant. A field whose name has a space in it is quoted: | count by "receipts.order number".

| count by counts messages: a message naming two merchants adds one to each. | sum and | series add up records, because a weekly digest with seven daily figures is seven of them.

Examples worth stealing

extract:importance.level=important after:7d | thread
is:unread to:me() -label:automated after:7d
from:me() after:90d | top to 20
in:contacts awaiting:me | sort last desc
awaiting:me | timeline
in:attachments filetype:pdf is:shared | count by from
extract:receipts after:2026 | sum receipts.amount by month
label:loops -from:me() after:30d | thread
in:logs level>warn after:1d | count by category

When a query is wrong

A query that does not parse says where: the position of the problem and what was expected there. An unknown field suggests the nearest real one — form: asks whether you meant from:.

On the command line, iql query "…" --explain shows the SQL a query becomes, and iql sql runs read-only SQL for anything the language cannot say. Both are covered in the command line.