main

Search Workflow

Search emails using mu’s powerful query language.

Workflow Steps

1. Understand the Search Request

Parse the user’s request to identify:

  • Keywords: Subject, body content, or specific terms
  • People: Senders (from:) or recipients (to:, cc:, bcc:)
  • Timeframe: Date ranges or relative dates (today, this week, etc.)
  • Scope: Which account (personal/work) and folders
  • Flags: Read/unread, flagged, replied status
  • Attachments: Specific file types or names

2. Construct mu Query

Build the mu find command with appropriate filters:

# Basic structure
mu find [query] --format=[plain|json|links]

# Common patterns
mu find from:alice@example.com subject:report
mu find maildir:/redhat/* date:1w..
mu find flag:unread maildir:/icloud/Inbox
mu find attach:*.pdf date:2025

Key Query Operators:

  • from:, to:, cc:, bcc: - Email addresses (supports wildcards)
  • subject:, body: - Content search
  • date: - Date ranges (YYYYMMDD..YYYYMMDD, relative like 1w.., today)
  • maildir: - Folder path (supports wildcards like /redhat/*)
  • flag: - Message flags (unread, flagged, replied, passed)
  • attach: - Attachment search
  • size: - Message size ranges
  • AND, OR, NOT - Boolean operators (AND is default)

Run the mu find command:

# For human-readable output
mu find <query> --format=plain

# For structured processing
mu find <query> --format=json

# For file paths only
mu find <query> --format=links

4. Present Results

Format and present results to the user:

  • Show count of matching messages
  • Display relevant excerpts (subject, from, date)
  • Highlight key information
  • Offer to drill down or view specific messages

5. Follow-up Actions

Based on results, offer:

  • View specific email content (→ View workflow)
  • Extract attachments (→ Extract workflow)
  • Analyze patterns (→ Analyze workflow)
  • Refine search with additional filters

Best Practices

Account Scoping

  • Personal emails: maildir:/icloud/*
  • Work emails: maildir:/redhat/*
  • Specific work project: maildir:/redhat/knative/*

Date Queries

  • Relative: date:today, date:1w.. (last week to now), date:..1m (up to 1 month ago)
  • Absolute: date:20250101..20250131
  • Single day: date:20250115

Performance

  • Scope to specific maildirs when possible
  • Use specific queries rather than broad wildcards
  • Combine filters to narrow results early

Privacy

  • Keep personal and work searches separate
  • Be careful with sensitive search terms
  • Don’t expose personal info in work contexts

Examples

Search personal inbox for unread mail:

mu find maildir:/icloud/Inbox flag:unread

Search work emails about Knative from last month:

mu find maildir:/redhat/knative date:1m.. --format=json

Find emails with PDF attachments from specific sender:

mu find from:alice@example.com attach:*.pdf

Search across all work emails for specific subject:

mu find maildir:/redhat/* subject:"quarterly report"

Find flagged emails from this week:

mu find flag:flagged date:1w..

Concurrent Access

Good news: mu find is a read-only operation and works perfectly even while mu4e is running in Emacs.

  • No need to check for database locks when searching
  • Multiple mu find commands can run simultaneously
  • Scripts using only mu find have no concurrency issues

Note: Only write operations like mu index are blocked when mu4e is running. See reference/DatabaseLocking.md for details.

Error Handling

Common issues:

  • Empty results: Suggest broadening search criteria
  • mu database not initialized: Run mu index --maildir=/home/vincent/desktop/mails
  • Invalid date format: Check date syntax and provide examples
  • Maildir not found: Verify folder path exists
  • Database locked: Only affects mu index, not mu find (search operations)

Output Formats

plain (default)

Human-readable format with headers and preview

json

Structured JSON for programmatic processing:

{
  "from": "sender@example.com",
  "subject": "Meeting notes",
  "date": 1234567890,
  "maildir": "/icloud/Inbox",
  "flags": ["seen", "replied"]
}

File paths only - useful for piping to other tools:

/home/vincent/desktop/mails/icloud/Inbox/cur/1234.msg