mail_search_emails
Search Apple Mail for emails by keyword and date range. Filter results by account, mailbox, or include system folders. Returns merged, deduplicated results sorted newest-first.
Instructions
Search Apple Mail for emails by keyword and/or date range.
Searches across all configured accounts in parallel, then merges, deduplicates and sorts the results newest-first. System/junk/duplicate-view mailboxes are excluded by default (see include_all_mailboxes). Returns matching emails with opaque email_id values for use with mail_read_email.
IMPORTANT — date range strategy (always follow this order): Large date windows (since_days > 90) are slow on big IMAP accounts and frequently timeout. Always start narrow and expand only if needed:
Step 1: since_days=7 → if results < needed, continue
Step 2: since_days=30 → if results < needed, continue
Step 3: since_days=90 → if results < needed, continue
Step 4: since_days=365 → last resort only
Never jump straight to since_days=365 for vague queries like
"recent emails" or "last few emails". Start with 7 days.
To page further back, keep since_days and add before_days instead of
re-reading overlapping results.Args: params (SearchEmailsInput): Input containing: - keyword (str): Optional search term matched against subject and sender. Omit when filtering by date only. - since_days (int): Optional. Restrict to emails received in the last N days (1–365). Use 1=today, 7=week, 30=month. - limit (int): Max results to return (default 20, max 100). - account (str): Optional. Restrict to one account (e.g. 'iCloud'). - mailbox_name (str): Optional. Restrict to one mailbox (e.g. 'INBOX'). - before_days (int): Optional. Exclude emails newer than N days ago; combine with since_days to page an older window (e.g. since_days=90, before_days=30 → 30–90 days ago) without re-fetching newer results. - include_all_mailboxes (bool): Optional. Also search normally-skipped mailboxes (Trash, Junk/Spam/Bulk, Deleted Items, Gmail All Mail/ Important/Starred, Outbox). Default false. - response_format (str): 'markdown' (default) or 'json'.
At least one of keyword or since_days must be provided.Returns: str: Results are merged across accounts, deduplicated by message id (Gmail label copies collapse to one), and sorted newest-first. System/junk/duplicate-view mailboxes (Trash, Deleted Items, Junk/Spam/Bulk, Gmail All Mail/Important/Starred, Outbox) are skipped unless include_all_mailboxes=true. Each result carries subject, sender, date, read-status and an opaque email_id. Timed-out accounts are listed as a warning (not a crash).
Markdown example:
# Search Results: "invoice" · last 30 days
Found 3 email(s) ...
JSON example:
[{"email_id": "...", "account": "iCloud", "mailbox": "INBOX",
"subject": "Invoice", "sender": "x@y.com",
"date": "Mon 3 Mar 2025", "read": true}]Examples: - "Most recent 3 emails" → since_days=7, limit=3 (expand to 30/90 if < 3 found) - "Emails this week" → since_days=7 - "Invoices in the past month" → keyword="invoice", since_days=30 - "Find emails from Alice" → keyword="Alice", since_days=30 - "Search only Yahoo INBOX" → account="Yahoo", mailbox_name="INBOX", since_days=7
Error Handling: - Returns an error string if Mail.app cannot be reached. - Returns "No emails found" with filter description if no matches. - Accounts that exceed the 45 s per-account timeout are listed as warnings; other accounts' results are still returned.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |