EmailOS Search Command Documentation

The mailos search command provides advanced email search capabilities with fuzzy matching, boolean operators, flexible date ranges, and size filters.

Basic Usage

mailos search

Searches and displays unlimited emails by default (use --limit to restrict). The search command uses cached emails from your local inbox for fast searching. Use sync options to update the cache with latest emails.

Quick Examples

# Boolean search with OR operator
mailos search -q "urgent OR deadline OR important"

# Field-specific search
mailos search -q "from:support AND subject:invoice"

# Date range with size filter
mailos search --date-range "last week" --min-size 1MB

# Complex query with NOT operator
mailos search -q "project AND NOT spam" --has-attachments

# Fuzzy search for typos
mailos search --from "supprt" # matches "support"

# Resync emails before searching
mailos search --resync --from "[email protected]"

# Search with attachment filtering
mailos search --has-attachments --attachment-size 1MB

# Search sent emails with alias authentication
mailos search --type sent --account [email protected] -q "contract"

# Advanced domain filtering
mailos search --external-only --exclude-domains spam.com,ads.com

# Content and body analysis
mailos search --body-contains "confidential" --word-count 100 --html-only

# Threading and conversation analysis
mailos search --is-reply --conversation-length 3

# Security and verification filtering
mailos search --encrypted --dkim-status pass --importance high

Command-Line Flags

Basic Options

Flag	Short	Type	Default	Description	Example
--body		string		Search in email body content	mailos search --body value
--days		int	0	search emails from last n days	mailos search --days value
--from		string		filter by sender	mailos search --from value
--limit		int	0	number of emails to search (0 = no limit) - alias for --number	mailos search --limit value
--number	-n	int	0	number of emails to search (0 = no limit)	mailos search --number value
--subject		string		filter by subject	mailos search --subject value
--to		string		filter by recipient (defaults to from-email in config if set)	mailos search --to value
--type		string	inbox	email type to search (inbox, sent, drafts, all)	mailos search --type value
--unread	-u	bool	false	show only unread emails	mailos search --unread

Advanced Options

Flag	Short	Type	Default	Description	Example
--alltime		bool	false	Search all emails (overrides default 30-day limit)	mailos search --alltime
--attachment-count		int	0	Filter by minimum number of attachments	mailos search --attachment-count value
--attachment-dir		string	attachments	directory to save attachments	mailos search --attachment-dir value
--attachment-name		string		Filter by attachment filename (supports wildcards)	mailos search --attachment-name value
--attachment-size		string		Minimum attachment size (e.g., '1MB')	mailos search --attachment-size value
--body-contains		string		Search for specific text in email body	mailos search --body-contains value
--body-length		string		Filter by body length in characters	mailos search --body-length value
--business-hours		bool	false	Only show emails sent during business hours (9-5)	mailos search --business-hours
--case-sensitive		bool	false	Enable case sensitive search	mailos search --case-sensitive
--conversation-length		int	0	Filter by minimum conversation/thread length	mailos search --conversation-length value
--conversation-start		bool	false	Filter emails that start conversations	mailos search --conversation-start
--date-range		string		Flexible date range (e.g., 'today', 'last week', '2023-01-01 to 2023-12-31')	mailos search --date-range value
--dkim-status		string		Filter by DKIM verification status (pass, fail)	mailos search --dkim-status value
--dmarc-status		string		Filter by DMARC verification status (pass, fail)	mailos search --dmarc-status value
--domain		string		Filter by sender domain (e.g., 'gmail.com')	mailos search --domain value
--download-attachments		bool	false	download email attachments	mailos search --download-attachments
--encoding		string		Filter by email encoding (e.g., 'utf-8', 'iso-8859-1')	mailos search --encoding value
--encrypted		bool	false	Filter encrypted emails	mailos search --encrypted
--exact		bool	false	Match exact phrases only (no fuzzy matching)	mailos search --exact
--exact-subject		bool	false	match subject exactly (no fuzzy matching)	mailos search --exact-subject
--exclude-domains		[]string		Exclude emails from specific domains	mailos search --exclude-domains value
--explain		bool	false	Explain search strategy and applied filters	mailos search --explain
--external-only		bool	false	Only show emails from external domains	mailos search --external-only
--extract-emails		[]string		Extract and filter email addresses from body	mailos search --extract-emails value
--extract-phones		[]string		Extract and filter phone numbers from body	mailos search --extract-phones value
--extract-urls		[]string		Extract and filter URLs from email body	mailos search --extract-urls value
--filetype		string		Filter by attachment file type (e.g., 'pdf', 'jpg', 'docx')	mailos search --filetype value
--filetypes		[]string		Filter by multiple attachment file types (e.g., 'pdf,docx,xlsx')	mailos search --filetypes value
--first		bool	false	Get the oldest email (sorts by date ascending, limits to 1, shows full content)	mailos search --first
--from-domain		string		Filter by sender domain	mailos search --from-domain value
--from-file		string		Path to CSV/text file containing email addresses to filter by (searches emails FROM these addresses)	mailos search --from-file value
--from-file-column		string		Column name in CSV to extract emails from (default: auto-detect 'email' column)	mailos search --from-file-column value
--fuzzy-threshold		float64	0.7	Fuzzy matching threshold (0.0-1.0)	mailos search --fuzzy-threshold value
--has-attachments		bool	false	Filter emails with attachments	mailos search --has-attachments
--has-bcc		bool	false	Filter emails with BCC recipients	mailos search --has-bcc
--has-cc		bool	false	Filter emails with CC recipients	mailos search --has-cc
--has-reply-to		bool	false	Filter emails with Reply-To header	mailos search --has-reply-to
--html-only		bool	false	Only search HTML emails	mailos search --html-only
--importance		string		Filter by email importance (high, normal, low)	mailos search --importance value
--in-reply-to		string		Search by In-Reply-To header	mailos search --in-reply-to value
--internal-only		bool	false	Only show emails from internal/same domain	mailos search --internal-only
--is-forward		bool	false	Filter forwarded emails	mailos search --is-forward
--is-reply		bool	false	Filter emails that are replies	mailos search --is-reply
--last		bool	false	Get the most recent email (sorts by date descending, limits to 1, shows full content)	mailos search --last
--latest		bool	false	Alias for --recent (sorts by date descending)	mailos search --latest
--line-count		int	0	Filter by minimum number of lines in body	mailos search --line-count value
--mailbox		string	Inbox	Mailbox to search when using Apple Mail source	mailos search --mailbox value
--max-size		string		Maximum email size (e.g., '10MB', '2GB')	mailos search --max-size value
--message-id		string		Search by Message-ID header	mailos search --message-id value
--min-size		string		Minimum email size (e.g., '1MB', '500KB')	mailos search --min-size value
--month		string		Filter by month (e.g., 'january', '01')	mailos search --month value
--newer-than-days		int	0	Filter emails newer than N days	mailos search --newer-than-days value
--no-attachments		bool	false	Filter emails without attachments	mailos search --no-attachments
--no-auto-sync		bool	false	Disable automatic sync when data is stale (over 1 day old)	mailos search --no-auto-sync
--no-fuzzy		bool	false	Disable fuzzy matching	mailos search --no-fuzzy
--no-spam		bool	false	Exclude emails marked as spam	mailos search --no-spam
--older-than-days		int	0	Filter emails older than N days	mailos search --older-than-days value
--phone		string		Search by phone number (format-insensitive: spaces, country code, punctuation)	mailos search --phone value
--priority		string		Filter by email priority (high, normal, low)	mailos search --priority value
--query	-q	string		Complex search query with boolean operators (AND, OR, NOT)	mailos search --query value
--range		string		time range (e.g., 'last hour', 'today', 'yesterday', 'this week')	mailos search --range value
--recent		bool	false	Show recent emails (sorts by date descending)	mailos search --recent
--resync		bool	false	Resync emails from server before searching	mailos search --resync
--signed		bool	false	Filter digitally signed emails	mailos search --signed
--sort-by		string	date	Sort results by (date, sender, subject, size, relevance)	mailos search --sort-by value
--sort-order		string	desc	Sort order (asc, desc)	mailos search --sort-order value
--source		string		Email source: 'imap' (default), 'applemail' (read from Mail.app)	mailos search --source value
--spam		bool	false	Include emails marked as spam	mailos search --spam
--spf-status		string		Filter by SPF verification status (pass, fail, neutral)	mailos search --spf-status value
--subject-length		string		Filter by subject length (e.g., '>50', '<20', '10-100')	mailos search --subject-length value
--suggestions		bool	false	Show smart query suggestions after results	mailos search --suggestions
--sync-from		string		Sync emails from specific date (e.g., '2023-01-01', 'last week', 'yesterday')	mailos search --sync-from value
--sync-range		string		Sync emails for date range (e.g., '2023-01-01 to 2023-12-31')	mailos search --sync-range value
--sync-until		string		Sync emails until specific date	mailos search --sync-until value
--text-only		bool	false	Only search plain text emails	mailos search --text-only
--thread		bool	false	Group results by inferred conversation thread	mailos search --thread
--thread-id		string		Search by thread/conversation ID	mailos search --thread-id value
--time-range		string		Filter by time of day (e.g., '09:00-17:00')	mailos search --time-range value
--to-domain		string		Filter by recipient domain	mailos search --to-domain value
--unique-senders		bool	false	Show only unique senders (deduplicate by sender)	mailos search --unique-senders
--unique-subjects		bool	false	Show only unique subjects (deduplicate by subject)	mailos search --unique-subjects
--view		string	normal	Output view profile (compact, normal, full)	mailos search --view value
--weekday		string		Filter by day of week (e.g., 'monday', 'weekend')	mailos search --weekday value
--word-count		int	0	Filter by minimum word count in body	mailos search --word-count value
--year		string		Filter by year (e.g., '2023')	mailos search --year value

Output Options

Flag	Short	Type	Default	Description	Example
--count-only	-c	bool	false	Show only count of matching emails	mailos search --count-only
--full-content		bool	false	Display full email content instead of snippets	mailos search --full-content
--include-headers		bool	false	Include full email headers in output	mailos search --include-headers
--output-dir		string	emails	directory to save markdown files	mailos search --output-dir value
--save-markdown		bool	false	save emails as markdown files	mailos search --save-markdown

Query Syntax Options

CLI Flags (Structured)

Use individual flags for structured searches:

# Structured approach using flags
mailos search --from "boss" --subject "urgent" --days 7
mailos search --has-attachments --min-size 1MB --type inbox

Direct Notmuch Query (Advanced)

For users familiar with Notmuch, you can use direct query syntax:

# Direct Notmuch query syntax
mailos search "from:boss AND subject:urgent AND date:7days.."
mailos search "date:yesterday.. AND from:[email protected]"
mailos search "tag:attachment AND date:2024-01-01.."

# Complex Notmuch queries
mailos search "(from:client1.com OR from:client2.com) AND date:this_month"
mailos search "subject:invoice AND NOT tag:spam"

Note: Direct Notmuch queries bypass CLI flag processing and use Notmuch's native syntax. This provides maximum flexibility for advanced users but requires knowledge of Notmuch query syntax.

Boolean Operators

• AND: All terms must match (default)

  mailos search -q "urgent AND project AND deadline"

• OR: Any term can match

  mailos search -q "invoice OR billing OR payment"

• NOT: Exclude terms

  mailos search -q "meeting NOT cancelled"

Field-Specific Search

Target specific email fields:

# Search in sender field
mailos search -q "from:support"

# Search in recipient field
mailos search -q "to:[email protected]"

# Search in subject line
mailos search -q "subject:urgent"

# Search in email body
mailos search -q "body:confidential"

Exact Phrase Matching

Using the --exact Flag

Use the --exact flag for precise phrase matching without fuzzy search:

# Find exact phrase "next day"
mailos search "next day" --exact

# Exact phrase in subject field
mailos search --subject "meeting tomorrow" --exact

# Compare fuzzy vs exact matching
mailos search "daily report"        # Fuzzy matching (finds "dayly report", "daily reports")
mailos search "daily report" --exact # Exact phrase only

# Exact search with other filters
mailos search "contract terms" --exact --has-attachments

Using Query Quotes

Alternatively, use quotes within queries for exact phrases:

# Exact phrase in query (disables fuzzy matching)
mailos search -q '"urgent: please reply immediately"'

# Mixed exact and fuzzy
mailos search -q '"project alpha" AND deadline'

Complex Query Examples

# Multiple conditions with field targeting
mailos search -q "from:manager AND (urgent OR important) AND NOT spam"

# Date range with boolean search
mailos search -q "invoice OR billing" --date-range "last month"

# Size and content filters combined
mailos search -q "contract OR agreement" --min-size 100KB --has-attachments

Fuzzy Search

Fuzzy search helps find emails even with typos or slight variations:

How It Works

• Uses Levenshtein distance algorithm
• Configurable similarity threshold (0.0 to 1.0)
• Default threshold: 0.7 (70% similarity)

Examples

# Find "support" even if typed as "supprt"
mailos search --from "supprt"

# Adjust fuzzy sensitivity
mailos search --fuzzy-threshold 0.5 --from "suport"

# Disable fuzzy matching for exact searches
mailos search --no-fuzzy --from "[email protected]"

Fuzzy Threshold Guide

• 0.9-1.0: Very strict (minor typos only)
• 0.7-0.8: Balanced (default, handles common typos)
• 0.5-0.6: Loose (more variations accepted)
• 0.0-0.4: Very loose (may match unrelated terms)

Date Range Examples

Natural Language Dates

mailos search --date-range "today"
mailos search --date-range "yesterday"
mailos search --date-range "last week"
mailos search --date-range "this month"
mailos search --date-range "last month"
mailos search --date-range "this year"

Specific Date Ranges

mailos search --date-range "2023-01-01 to 2023-12-31"
mailos search --date-range "2024-06-01 to 2024-06-30"

Relative Dates

mailos search --date-range "last 7 days"
mailos search --date-range "last 30 days"
mailos search --date-range "last 90 days"

Size Filter Examples

Email Size Filtering

# Large emails only
mailos search --min-size 1MB

# Small to medium emails
mailos search --max-size 500KB

# Specific size range
mailos search --min-size 100KB --max-size 5MB

Attachment Filtering

# Emails with any attachments
mailos search --has-attachments

# Emails with large attachments
mailos search --attachment-size 1MB

# Combined attachment and size filters
mailos search --has-attachments --min-size 2MB

Practical Use Cases

Finding Important Communications

# Urgent emails from management with alias authentication
mailos search --account [email protected] -q "from:manager AND (urgent OR important OR asap)"

# Contract-related emails with attachments from specific domains
mailos search -q "contract OR agreement" --has-attachments --min-size 50KB --from-domain client.com

# High-priority encrypted emails
mailos search --priority high --encrypted --importance high

# External communications only
mailos search --external-only --has-cc --business-hours

Email Cleanup and Management

# Large emails consuming storage (over 10MB)
mailos search --min-size 10MB --sort-by size --sort-order desc

# Old promotional emails with specific content
mailos search -q "unsubscribe OR newsletter" --date-range "last 6 months" --exclude-domains important.com

# Emails with large attachments for archival
mailos search --attachment-size 5MB --date-range "last year" --filetype pdf

# HTML-only emails with no attachments (potential spam)
mailos search --html-only --no-attachments --external-only

# Use suggestions to discover search patterns
mailos search --from "newsletter" --suggestions

Advanced Security and Compliance Analysis

# Failed email authentication checks
mailos search --spf-status fail --dkim-status fail

# Digitally signed emails from external sources
mailos search --signed --external-only --importance high

# Conversation threads with multiple participants
mailos search --conversation-length 5 --has-cc --has-bcc

Project and Work Tracking

# Project-related communications with threading analysis
mailos search -q "project:alpha OR alpha-project" --date-range "this month" --conversation-start

# Invoice and billing emails with verification
mailos search -q "invoice OR billing OR payment" --has-attachments --filetype pdf,docx

# Client communications during business hours
mailos search --from-domain client.com --business-hours --is-reply

# Extract contact information from emails
mailos search --extract-emails --extract-phones --body-contains "contact"

Content Analysis and Data Mining

# Long-form emails with substantial content
mailos search --word-count 500 --line-count 20 --body-length ">2000"

# Emails with specific file types and URLs
mailos search --filetypes pdf,xlsx,pptx --extract-urls

# Threaded conversations about specific topics
mailos search -q "budget OR financial" --is-reply --thread-id "specific-thread"

Smart Query Suggestions

Use the --suggestions flag to get intelligent query recommendations based on your email patterns:

# Get suggestions after search results
mailos search --from "work" --suggestions
mailos search --has-attachments --suggestions

# Get suggestions with verbose analysis
mailos search --suggestions --verbose

Suggestion Types:

• Sender patterns: Frequent email contacts
• Domain analysis: Common domains in your email
• Subject keywords: Frequent subject terms
• Date ranges: Common time-based searches
• Filter combinations: Suggested advanced filters

Performance Tips

1. Use specific filters to reduce search scope
2. Combine date ranges with other filters for faster results
3. Adjust fuzzy threshold based on your needs
4. Use field-specific searches when possible
5. Limit result count with -n flag
6. Use --exact for precise matching when you know exact terms
7. Try direct Notmuch queries for complex searches
8. Enable --verbose mode to see performance metrics and optimization hints

Troubleshooting

Search Returns No Results

1. Check query syntax with simple terms first
2. Try lowering fuzzy threshold: --fuzzy-threshold 0.5
3. Verify date ranges are correct
4. Remove filters one by one to isolate issues
5. Use --resync to ensure latest emails are cached

Content Not Displaying with --full-content

1. Verify email has actual body content (not header-only)
2. Try without other filters to isolate the issue
3. Check if email is multipart/mixed format requiring HTML parsing
4. Use --verbose mode to see extraction details
5. Ensure cache is updated with --resync if content was recently modified

Fuzzy Search Too Broad

1. Increase fuzzy threshold: --fuzzy-threshold 0.8
2. Use exact phrases with quotes or --exact flag
3. Enable case sensitivity: --case-sensitive
4. Disable fuzzy matching: --no-fuzzy
5. Try direct Notmuch query syntax for precise control

Size Filters Not Working

1. Verify size units (B, KB, MB, GB, TB)
2. Check that emails have been synced locally
3. Use broader size ranges initially

Boolean Queries Not Working

1. Ensure proper spacing around operators
2. Use quotes for phrases containing operators
3. Check parentheses for complex queries
4. Start with simple AND/OR queries

Integration with Other Commands

Combining with Read Command

# Search to find email IDs, then read specific emails
mailos search -q "important contract" --json | jq '.[].id'
mailos read 12345  # Read specific email by ID

Saving Search Results

# Save search results to files
mailos search -q "quarterly report" --save-markdown --output-dir ./reports

# Export search results as JSON
mailos search --date-range "last month" --json > last_month_emails.json

Content Display Options

Full Content Display

The --full-content flag provides comprehensive email content extraction:

# Display complete email content instead of snippets
mailos search --from "[email protected]" --full-content

# Full content with multipart HTML email support
mailos search --body-contains "contract" --full-content --html-only

# Complex invoice emails with nested HTML structure
mailos search --from "quickbooks" --full-content --has-attachments

Full Content Features:

• HTML Priority: Automatically extracts HTML content when available, falls back to plain text
• Multipart Support: Handles complex multipart/mixed emails (invoices, newsletters, etc.)
• Cache Differentiation: Full content searches use separate cache keys to ensure proper content display
• Performance: Content extraction adds minimal overhead compared to header-only searches

Content Parsing Capabilities

The search system now handles sophisticated email structures:

• Plain Text Emails: Direct content extraction
• HTML Emails: Full HTML content with proper parsing
• Multipart/Mixed: Complex nested structures common in business emails
• Invoice Emails: Specialized parsing for QuickBooks and similar invoice systems
• Newsletter Content: Rich HTML newsletters with embedded images and styling

Caching and Performance

The search command uses a local email cache for fast searching:

• Local Cache: Emails are cached locally in a global inbox for fast search
• Content-Aware Caching: Separate cache entries for header-only vs full-content searches
• Sync Status: Shows last sync time and warns if cache is stale (>1 hour old)
• Performance: Cache searches are 20-50x faster than IMAP searches
• Auto-sync: Use --resync to update cache with latest emails

Cache Management

# Check cache status
mailos search  # Shows last sync time

# Update cache with latest emails
mailos search --resync

# Sync specific date range
mailos search --sync-from "last week"
mailos search --sync-range "2023-01-01 to 2023-12-31"

Notes

• Search primarily uses cached emails for performance
• Use --resync to fetch latest emails from server
• Fuzzy matching works on all text fields (from, to, subject, body)
• Size calculations include email content and attachments
• Date ranges use your local timezone
• Boolean operators are case-insensitive (AND, and, And all work)
• Search results are sorted by date (newest first)
• Email IDs from search results can be used with mailos read command