Gmail Search Syntax

Standard Gmail search operators work in the query argument.

Common Operators

Operator	Example	Description
`is:unread`	`is:unread`	Unread messages
`is:starred`	`is:starred`	Starred messages
`is:important`	`is:important`	Important messages
`in:inbox`	`in:inbox`	Inbox only
`in:sent`	`in:sent`	Sent folder
`in:drafts`	`in:drafts`	Drafts
`in:trash`	`in:trash`	Trash
`in:anywhere`	`in:anywhere`	All mail including spam/trash
`from:`	`from:alice@example.com`	Sender
`to:`	`to:bob@example.com`	Recipient
`cc:`	`cc:team@example.com`	CC recipient
`subject:`	`subject:invoice`	Subject contains
`label:`	`label:work`	Has label
`has:attachment`	`has:attachment`	Has attachments
`filename:`	`filename:pdf`	Attachment filename/type
`larger:`	`larger:5M`	Larger than size
`smaller:`	`smaller:1M`	Smaller than size

Date Operators

Operator	Example	Description
`newer_than:`	`newer_than:7d`	Within last N days (d), months (m), years (y)
`older_than:`	`older_than:30d`	Older than N days/months/years
`after:`	`after:2026/02/01`	After date (YYYY/MM/DD)
`before:`	`before:2026/03/01`	Before date

Combining

Syntax	Example	Description
space	`from:alice subject:meeting`	AND (implicit)
`OR`	`from:alice OR from:bob`	OR
`-`	`-from:noreply@`	NOT (exclude)
`()`	`(from:alice OR from:bob) subject:meeting`	Grouping
`""`	`"exact phrase"`	Exact phrase match

Common Patterns

# Unread emails from the last day
is:unread newer_than:1d

# Emails with PDF attachments from a specific sender
from:accounting@company.com has:attachment filename:pdf

# Important unread emails (not promotions/social)
is:unread -category:promotions -category:social

# Emails in a thread about a topic
subject:"Q4 budget" newer_than:30d

# Large attachments to clean up
has:attachment larger:10M older_than:90d

Referenced from SKILL.md

SKILL.mdView in source ↗

26- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)27- `references/daily-brief.md` — daily/morning brief procedure: schedule + conflicts + meeting prep + urgent mail from Gmail and Calendar. Load it when the user asks for a morning brief, meeting preparation, or "what's on my calendar and what email needs attention."

SKILL.mdView in source ↗

3172. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.3183. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.3194. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).