gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator/skills/gmail-assistant/references/gmail-search-syntax.md

Gmail Search Syntax Reference

Complete reference for Gmail search operators. Use these with the gmail search command.

Quick Start

# Basic search
gmail search "from:user@example.com"

# Combined search
gmail search "from:user@example.com has:attachment after:2024/10/01"

# Complex search
gmail search "(from:alice OR from:bob) subject:report -is:read"

---

Basic Operators

From/To/CC/BCC

from:sender@example.com       # Emails from sender
to:recipient@example.com      # Emails to recipient
cc:person@example.com         # CC'd to person
bcc:person@example.com        # BCC'd to person (only sent emails)

Examples:

# All emails from professor
gmail search "from:professor@university.edu" --max 20

# All emails to colleague
gmail search "to:colleague@company.com" --max 10

# Emails CC'd to manager
gmail search "cc:manager@company.com" --max 5

Subject

subject:keyword               # Subject contains keyword
subject:"exact phrase"        # Subject contains exact phrase
subject:(word1 word2)         # Subject contains both words

Examples:

# Emails about meetings
gmail search "subject:meeting" --max 10

# Exact subject phrase
gmail search 'subject:"Weekly Report"' --max 5

# Subject with multiple keywords
gmail search "subject:(project deadline)" --max 10

Body Content

keyword                       # Body or subject contains keyword
"exact phrase"                # Body or subject has exact phrase

Examples:

# Emails mentioning budget
gmail search "budget" --max 10

# Exact phrase in email
gmail search '"quarterly results"' --max 5

---

Date Operators

Absolute Dates

after:YYYY/MM/DD             # After specific date
before:YYYY/MM/DD            # Before specific date

Examples:

# Emails after October 1, 2024
gmail search "after:2024/10/01" --max 20

# Emails before September 30, 2024
gmail search "before:2024/09/30" --max 10

# Emails in date range
gmail search "after:2024/10/01 before:2024/10/31" --max 20

Relative Dates

newer_than:Nd                # Newer than N days
older_than:Nd                # Older than N days
newer_than:Nm                # Newer than N months
older_than:Nm                # Older than N months
newer_than:Ny                # Newer than N years
older_than:Ny                # Older than N years

Examples:

# Last 7 days
gmail search "newer_than:7d" --max 20

# Older than 30 days
gmail search "older_than:30d" --max 10

# Last 2 months
gmail search "newer_than:2m" --max 20

# Last year
gmail search "newer_than:1y" --max 50

---

Status Operators

Read/Unread

is:read                      # Read emails
is:unread                    # Unread emails

Examples:

# All unread emails
gmail search "is:unread" --max 20

# Unread emails from specific person
gmail search "from:boss@company.com is:unread" --max 10

Starred/Important

is:starred                   # Starred emails
is:important                 # Marked important
-is:important                # NOT important

Examples:

# Starred emails
gmail search "is:starred" --max 20

# Important emails from last week
gmail search "is:important newer_than:7d" --max 10

---

Attachment Operators

Has Attachment

has:attachment               # Has any attachment
has:drive                    # Has Google Drive attachment
has:document                 # Has document
has:spreadsheet              # Has spreadsheet
has:presentation             # Has presentation
has:youtube                  # Has YouTube link

Examples:

# All emails with attachments
gmail search "has:attachment" --max 20

# Emails with PDFs
gmail search "filename:pdf" --max 10

# Emails with Google Drive files
gmail search "has:drive" --max 10

Filename

filename:name                # Attachment filename contains name
filename:pdf                 # Attachment is PDF
filename:xlsx                # Attachment is Excel file

Examples:

# Emails with PDF attachments
gmail search "filename:pdf" --max 10

# Specific filename
gmail search 'filename:"report.pdf"' --max 5

# Invoices
gmail search "filename:invoice" --max 20

---

Size Operators

size:N                       # Larger than N bytes
larger:N                     # Larger than N (use M/K for MB/KB)
smaller:N                    # Smaller than N

Examples:

# Larger than 1MB
gmail search "larger:1M" --max 10

# Larger than 10MB
gmail search "larger:10M" --max 5

# Smaller than 500KB
gmail search "smaller:500K" --max 10

# Large emails with attachments
gmail search "has:attachment larger:5M" --max 10

---

Label Operators

label:name                   # Has specific label
-label:name                  # Does NOT have label

System labels:

• INBOX - In inbox
• SENT - Sent emails
• DRAFT - Drafts
• TRASH - Trash
• SPAM - Spam
• STARRED - Starred
• IMPORTANT - Important
• UNREAD - Unread
• CATEGORY_PERSONAL - Personal category
• CATEGORY_SOCIAL - Social category
• CATEGORY_PROMOTIONS - Promotions category
• CATEGORY_UPDATES - Updates category
• CATEGORY_FORUMS - Forums category

Examples:

# Emails in inbox
gmail search "label:inbox" --max 20

# Archived emails (not in inbox)
gmail search "-label:inbox" --max 20

# Sent emails
gmail search "label:sent" --max 10

# Custom label
gmail search "label:work" --max 20

---

Boolean Operators

AND (implicit)

keyword1 keyword2            # Both keywords (space = AND)
keyword1 AND keyword2        # Explicit AND

Examples:

# Both keywords
gmail search "project deadline" --max 10

# Explicit AND
gmail search "project AND deadline" --max 10

OR

keyword1 OR keyword2         # Either keyword

Examples:

# Emails from either person
gmail search "from:alice@example.com OR from:bob@example.com" --max 10

# Multiple subjects
gmail search "subject:meeting OR subject:schedule" --max 10

NOT (-)

-keyword                     # Does NOT contain keyword
-operator:value              # Does NOT match operator

Examples:

# Exclude sender
gmail search "subject:report -from:manager@company.com" --max 10

# Not in inbox (archived)
gmail search "-label:inbox" --max 20

# Not read
gmail search "-is:read" --max 10

Grouping ( )

(condition1 OR condition2)   # Group conditions

Examples:

# Emails from alice OR bob with attachments
gmail search "(from:alice OR from:bob) has:attachment" --max 10

# Multiple subjects with specific date range
gmail search "(subject:meeting OR subject:schedule) after:2024/10/01" --max 20

---

Thread Operators

in:thread_id                 # Emails in specific thread

Example:

# Get all emails in a thread (use thread_id from email details)
gmail search "in:19abc123def456" --max 20

---

Wildcard Operator

*                           # Wildcard (limited use in Gmail)

Note: Gmail's wildcard support is limited. It works best with:

• Email addresses: from:*@example.com
• Not recommended for general text searches

---

Common Search Patterns

Workflow-Specific Searches

Before Composing to Someone

Find all correspondence (sent + received):

gmail search "to:person@example.com OR from:person@example.com" --max 10

Finding Unread Important Emails

gmail search "is:unread is:important" --max 20

Recent Emails About a Topic

gmail search "subject:project-name newer_than:30d" --max 10

Emails from Team with Attachments

gmail search "(from:alice@team.com OR from:bob@team.com) has:attachment" --max 10

Large Emails to Clean Up

gmail search "larger:10M older_than:1y" --max 20

Unanswered Emails

gmail search "is:unread from:important@person.com newer_than:7d" --max 10

---

Advanced Search Patterns

Finding Email Threads

Search for initial email and use thread view:

# Find thread starter
gmail search "subject:keyword from:person@example.com" --max 5

# Then use thread command
gmail thread <message_id>

Combining Multiple Criteria

# Complex search: unread emails from professor with attachments in last 30 days
gmail search "from:professor@edu.edu is:unread has:attachment newer_than:30d" --max 10

# Emails from multiple people about specific topic
gmail search "(from:alice OR from:bob) subject:budget newer_than:7d" --max 10

Excluding Common Patterns

# Important emails excluding automated notifications
gmail search "is:important -from:noreply -from:no-reply" --max 20

# Emails with attachments excluding newsletters
gmail search "has:attachment -label:promotions" --max 20

---

Search Best Practices

1. Start Broad, Then Refine

# Start broad
gmail search "project" --max 20

# Refine
gmail search "project from:alice@example.com" --max 10

# Further refine
gmail search "project from:alice@example.com after:2024/10/01" --max 5

2. Use Date Ranges for Context

# Recent context (last 7 days)
gmail search "to:person@example.com newer_than:7d" --max 5

# Historical context (last 6 months)
gmail search "to:person@example.com newer_than:6m" --max 20

3. Combine Sender and Recipient

# All correspondence with someone
gmail search "to:person@example.com OR from:person@example.com" --max 10

4. Use Labels for Organization

# Search within labeled emails
gmail search "label:work subject:report" --max 10

# Exclude certain labels
gmail search "has:attachment -label:spam -label:trash" --max 20

---

CLI-Specific Options

Max Results

# Limit results (1-50)
gmail search "query" --max 10
gmail search "query" --max 20
gmail search "query" --max 50

Folder Filtering

# Search within specific folder
gmail search "is:unread" --folder INBOX --max 10
gmail search "keyword" --folder SENT --max 20

---

Common Mistakes

1. Not Quoting Phrases

Wrong:

gmail search "subject:meeting notes"  # Searches for subject:meeting AND notes anywhere

Right:

gmail search 'subject:"meeting notes"'  # Searches for exact phrase in subject

2. Forgetting OR is Uppercase

Wrong:

gmail search "from:alice or from:bob"  # "or" treated as keyword

Right:

gmail search "from:alice OR from:bob"  # OR is operator

3. Using Wildcards for General Text

Wrong:

gmail search "meet*"  # Limited wildcard support

Right:

gmail search "meeting"  # Use complete words

4. Not Using Parentheses for Complex Queries

Wrong:

gmail search "from:alice OR from:bob has:attachment"  # Ambiguous

Right:

gmail search "(from:alice OR from:bob) has:attachment"  # Clear grouping

---

Quick Reference Table

Operator	Description	Example
from:	From sender	from:user@example.com
to:	To recipient	to:user@example.com
subject:	Subject contains	subject:meeting
after:	After date	after:2024/10/01
before:	Before date	before:2024/10/31
newer_than:	Newer than N days/months/years	newer_than:7d
older_than:	Older than N days/months/years	older_than:30d
is:unread	Unread emails	is:unread
is:starred	Starred emails	is:starred
has:attachment	Has attachment	has:attachment
filename:	Attachment filename	filename:pdf
larger:	Larger than size	larger:10M
smaller:	Smaller than size	smaller:500K
label:	Has label	label:inbox
-	NOT operator	-from:noreply
OR	OR operator	from:alice OR from:bob
( )	Grouping	(from:a OR from:b) subject:x

---

Testing Searches

Always test searches with small result sets first:

# Test with --max 5 first
gmail search "complex query here" --max 5

# If results look good, increase
gmail search "complex query here" --max 20

---

Pagination

For large result sets, use pagination:

# Get first page
gmail search "query" --max 50

# Use next_page_token from results for subsequent pages
# (Python API supports this; CLI shows truncated results)

---

Additional Resources

• Gmail search operators: https://support.google.com/mail/answer/7190
• gmaillm API reference: references/api-reference.md