CtrlK
BlogDocsLog inGet started
Tessl Logo

odyssey4me/gmail

Send, search, and organize Gmail messages, drafts, and labels. Use when asked to compose an email, reply to mail, forward a message, search inbox, manage attachments, or organize Gmail.

94

Quality

94%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Skills
Evals
Files

gmail-queries.mdreferences/

Gmail Search Query Reference

Gmail's search syntax is powerful and allows you to find exactly what you need. This reference covers the search operators you can use with gmail.py messages list --query.

Basic Search Operators

Sender and Recipient

OperatorDescriptionExample
from:Messages from specific senderfrom:alice@example.com
to:Messages sent to recipientto:bob@example.com
cc:Messages CC'd to recipientcc:team@example.com
bcc:Messages BCC'd to recipientbcc:boss@example.com

Examples:

# All emails from Alice
python scripts/gmail.py messages list --query "from:alice@example.com"

# Emails I sent to Bob
python scripts/gmail.py messages list --query "to:bob@example.com"

# Emails where team was CC'd
python scripts/gmail.py messages list --query "cc:team@example.com"

Subject and Body

OperatorDescriptionExample
subject:Subject contains textsubject:meeting
(no operator)Body or subject containsproject alpha
"exact phrase"Exact phrase match"quarterly review"

Examples:

# Emails with "meeting" in subject
python scripts/gmail.py messages list --query "subject:meeting"

# Emails containing "project alpha" anywhere
python scripts/gmail.py messages list --query "project alpha"

# Exact phrase in subject or body
python scripts/gmail.py messages list --query '"quarterly review"'

Message States

Read/Unread

OperatorDescription
is:unreadUnread messages
is:readRead messages

Examples:

# All unread emails
python scripts/gmail.py messages list --query "is:unread"

# Read emails from last week
python scripts/gmail.py messages list --query "is:read newer_than:7d"

Starred/Important

OperatorDescription
is:starredStarred messages
is:importantImportant messages (Gmail priority)

Examples:

# Starred emails
python scripts/gmail.py messages list --query "is:starred"

# Important unread emails
python scripts/gmail.py messages list --query "is:important is:unread"

Labels and Categories

Labels

OperatorDescriptionExample
label:Has specific labellabel:work
has:userlabelsHas any user labelhas:userlabels
has:nouserlabelsHas no user labelshas:nouserlabels

Examples:

# Emails with "work" label
python scripts/gmail.py messages list --query "label:work"

# Emails with any custom label
python scripts/gmail.py messages list --query "has:userlabels"

# Emails without custom labels
python scripts/gmail.py messages list --query "has:nouserlabels"

Categories (Gmail tabs)

OperatorDescription
category:primaryPrimary inbox
category:socialSocial tab
category:promotionsPromotions tab
category:updatesUpdates tab
category:forumsForums tab

Examples:

# Unread emails in primary inbox
python scripts/gmail.py messages list --query "category:primary is:unread"

# Social emails from last day
python scripts/gmail.py messages list --query "category:social newer_than:1d"

Attachments

OperatorDescriptionExample
has:attachmentHas any attachmenthas:attachment
filename:Attachment filenamefilename:pdf
filename: (exact)Exact filenamefilename:report.pdf

Examples:

# Emails with attachments
python scripts/gmail.py messages list --query "has:attachment"

# Emails with PDF attachments
python scripts/gmail.py messages list --query "filename:pdf"

# Specific file
python scripts/gmail.py messages list --query "filename:report.pdf"

# Attachments from specific sender
python scripts/gmail.py messages list --query "from:alice@example.com has:attachment"

Date and Time

Relative Dates

OperatorDescriptionExample
newer_than:Newer than time periodnewer_than:7d
older_than:Older than time periodolder_than:30d

Time units:

  • d = days (e.g., 7d = 7 days)
  • m = months (e.g., 2m = 2 months)
  • y = years (e.g., 1y = 1 year)

Examples:

# Emails from last 7 days
python scripts/gmail.py messages list --query "newer_than:7d"

# Emails older than 30 days
python scripts/gmail.py messages list --query "older_than:30d"

# Last 2 months from specific sender
python scripts/gmail.py messages list --query "from:boss@example.com newer_than:2m"

Absolute Dates

OperatorDescriptionExample
after:After specific dateafter:2024/01/01
before:Before specific datebefore:2024/12/31

Date formats:

  • YYYY/MM/DD (e.g., 2024/01/15)
  • YYYY-MM-DD (e.g., 2024-01-15)

Examples:

# Emails after January 1, 2024
python scripts/gmail.py messages list --query "after:2024/01/01"

# Emails before end of year
python scripts/gmail.py messages list --query "before:2024/12/31"

# Emails in specific date range
python scripts/gmail.py messages list --query "after:2024/01/01 before:2024/01/31"

Relative Date Shortcuts

OperatorDescription
newer_than:1dLast 24 hours
newer_than:7dLast week
newer_than:1mLast month
older_than:1yOlder than 1 year

Size

OperatorDescriptionExample
size:Exact size in bytessize:1000000
larger:Larger than sizelarger:10M
smaller:Smaller than sizesmaller:1M

Size units:

  • No unit = bytes
  • K = kilobytes
  • M = megabytes

Examples:

# Emails larger than 10 MB
python scripts/gmail.py messages list --query "larger:10M"

# Small emails (less than 100 KB)
python scripts/gmail.py messages list --query "smaller:100K"

# Large attachments from last week
python scripts/gmail.py messages list --query "has:attachment larger:5M newer_than:7d"

Conversation Threads

OperatorDescription
is:chatChat messages
is:snoozedSnoozed messages
list:Messages from mailing list

Examples:

# Chat messages
python scripts/gmail.py messages list --query "is:chat"

# Snoozed messages
python scripts/gmail.py messages list --query "is:snoozed"

# Messages from specific mailing list
python scripts/gmail.py messages list --query "list:dev-team@example.com"

Special Searches

Trash and Spam

OperatorDescription
in:trashIn trash
in:spamIn spam
in:inboxIn inbox
in:sentIn sent mail
in:draftsIn drafts
in:anywhereAnywhere (including trash/spam)

Examples:

# Trash items
python scripts/gmail.py messages list --query "in:trash"

# Sent emails to specific person
python scripts/gmail.py messages list --query "in:sent to:alice@example.com"

# Search everywhere including trash
python scripts/gmail.py messages list --query "in:anywhere subject:important"

Boolean Operators

Combining Searches

OperatorDescriptionExample
AND (implicit)Both conditionsfrom:alice subject:meeting
OREither conditionfrom:alice OR from:bob
NOT or -Exclude condition-from:spam@example.com
( )Grouping(from:alice OR from:bob) subject:meeting

Examples:

# From Alice AND about meetings (implicit AND)
python scripts/gmail.py messages list --query "from:alice@example.com subject:meeting"

# From Alice OR Bob
python scripts/gmail.py messages list --query "from:alice@example.com OR from:bob@example.com"

# NOT from spam sender
python scripts/gmail.py messages list --query "-from:spam@example.com"

# Complex: (Alice OR Bob) AND meeting AND unread
python scripts/gmail.py messages list --query "(from:alice@example.com OR from:bob@example.com) subject:meeting is:unread"

Negation Examples

# Unread emails NOT from Alice
python scripts/gmail.py messages list --query "is:unread -from:alice@example.com"

# Emails without attachments
python scripts/gmail.py messages list --query "-has:attachment"

# Not labeled
python scripts/gmail.py messages list --query "-has:userlabels"

# Not in trash or spam
python scripts/gmail.py messages list --query "-in:trash -in:spam"

Practical Examples

Daily Email Triage

# Today's unread emails
python scripts/gmail.py messages list --query "is:unread newer_than:1d"

# Important unread from last 3 days
python scripts/gmail.py messages list --query "is:important is:unread newer_than:3d" --max-results 20

# Starred emails I haven't read
python scripts/gmail.py messages list --query "is:starred is:unread"

Project Management

# All project-related emails
python scripts/gmail.py messages list --query "subject:project-alpha"

# Project emails with attachments
python scripts/gmail.py messages list --query "subject:project-alpha has:attachment"

# Team emails from last sprint (2 weeks)
python scripts/gmail.py messages list --query "from:team@example.com newer_than:14d"

# Unread project emails
python scripts/gmail.py messages list --query "label:project-alpha is:unread"

Finding Specific Content

# Invoice emails
python scripts/gmail.py messages list --query "subject:invoice has:attachment"

# Password reset emails
python scripts/gmail.py messages list --query "subject:password subject:reset"

# Meeting invites from this month
python scripts/gmail.py messages list --query "subject:meeting subject:invite newer_than:1m"

# Receipts with PDFs
python scripts/gmail.py messages list --query "subject:receipt filename:pdf"

Cleanup Tasks

# Large old emails
python scripts/gmail.py messages list --query "larger:10M older_than:1y"

# Old read emails
python scripts/gmail.py messages list --query "is:read older_than:6m"

# Promotional emails
python scripts/gmail.py messages list --query "category:promotions older_than:30d"

# Social emails older than 3 months
python scripts/gmail.py messages list --query "category:social older_than:3m"

Sender Analysis

# All emails from domain
python scripts/gmail.py messages list --query "from:@example.com"

# Emails TO a specific domain
python scripts/gmail.py messages list --query "to:@clients.com"

# Emails from boss with attachments
python scripts/gmail.py messages list --query "from:boss@example.com has:attachment"

# Team emails I sent
python scripts/gmail.py messages list --query "to:team@example.com in:sent"

Advanced Patterns

Date Range Searches

# Q1 2024 emails
python scripts/gmail.py messages list --query "after:2024/01/01 before:2024/04/01"

# Last year's December
python scripts/gmail.py messages list --query "after:2023/12/01 before:2024/01/01"

# Specific week
python scripts/gmail.py messages list --query "after:2024/01/15 before:2024/01/22"

Multi-Condition Searches

# Unread, important, with attachments from this week
python scripts/gmail.py messages list \
  --query "is:unread is:important has:attachment newer_than:7d"

# Large PDFs from specific sender in last month
python scripts/gmail.py messages list \
  --query "from:reports@example.com filename:pdf larger:5M newer_than:1m"

# Meeting invites not yet read
python scripts/gmail.py messages list \
  --query "subject:meeting subject:invite is:unread"

Exclusion Patterns

# Inbox emails excluding newsletters
python scripts/gmail.py messages list \
  --query "in:inbox -category:promotions -category:social -category:updates"

# Emails from domain EXCEPT automated@
python scripts/gmail.py messages list \
  --query "from:@example.com -from:automated@example.com"

# Important emails without certain labels
python scripts/gmail.py messages list \
  --query "is:important -label:archived -label:reviewed"

Tips and Best Practices

Performance

  1. Use specific operators - from: is faster than searching body text
  2. Add date constraints - Narrows search space significantly
  3. Limit results - Use --max-results to avoid fetching too many

Quotes and Escaping

  1. Use quotes for exact phrases: "quarterly review"
  2. Shell quoting: Wrap entire query in quotes when using shell 
    python scripts/gmail.py messages list --query "from:alice subject:meeting"
  3. Special characters: Gmail handles most special chars, but quotes need escaping in shell

Common Mistakes

  1. Date format: Use YYYY/MM/DD not MM/DD/YYYY
  2. Time units: 7d not 7days, 2m not 2months
  3. Spaces in AND: from:alice subject:meeting (implicit AND) not from:alice AND subject:meeting
  4. Case sensitivity: Most operators are case-insensitive

Testing Queries

Before using in automation:

  1. Test in Gmail web interface first
  2. Start broad, then narrow - Add constraints incrementally
  3. Verify result counts - Use --max-results 5 to spot-check

Additional Resources

  • Official Gmail Search Operators
  • Advanced Gmail Search

Install with Tessl CLI

npx tessl i odyssey4me/gmail

references

gmail-queries.md

SKILL.md

tile.json