search_emails
Search across Apple Mail accounts using filters for subject, sender, date, attachments, flags, and body content. Returns paginated results in text or JSON format.
Instructions
Unified search tool with JSON output, pagination, and real date filtering.
Consolidates subject search, sender search, body content search, and cross-account search into a single tool.
Args: account: Account name to search in (e.g., "Gmail", "Work"). If None, searches ALL accounts (slower). mailbox: Mailbox to search (default: "INBOX", use "All" for all mailboxes, or specific folder name) subject_keyword: Optional keyword to search in subject subject_keywords: Optional list of subject keywords; matches any keyword sender: Optional sender email or name to filter by has_attachments: Optional filter for emails with attachments (True/False/None) flagged: Optional filter for flagged emails (True/False/None) flag_color: Optional filter for a specific flag color: "red", "orange", "yellow", "green", "blue", "purple", or "gray". Implies flagged=True. read_status: Filter by read status: "all", "read", "unread" (default: "all") date_from: Optional start date filter (format: "YYYY-MM-DD") date_to: Optional end date filter (format: "YYYY-MM-DD") include_content: Whether to include email content preview (slower) max_content_length: Maximum content length in characters when include_content=True (default: 500, 0 = unlimited) body_text: Optional text to search for in email body content (case-insensitive). WARNING: body search is significantly slower as it reads each message body. max_results: Backward-compatible alias for limit output_format: Output format: "text" or "json" (default: "text") offset: Number of matching results to skip before returning data limit: Maximum number of results to return per page sort: Result sort order: "date_desc" or "date_asc"
Returns: Formatted list of matching emails or JSON payload with stable message metadata
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | date_desc | |
| limit | No | ||
| offset | No | ||
| sender | No | ||
| account | No | ||
| date_to | No | ||
| flagged | No | ||
| mailbox | No | INBOX | |
| body_text | No | ||
| date_from | No | ||
| flag_color | No | ||
| max_results | No | ||
| read_status | No | all | |
| output_format | No | text | |
| has_attachments | No | ||
| include_content | No | ||
| subject_keyword | No | ||
| subject_keywords | No | ||
| max_content_length | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |