List all mailboxes/folders available in Apple Mail, grouped by account.

Queries Apple Mail via AppleScript to retrieve every configured account and all mailboxes within each account (INBOX, Sent Messages, Drafts, custom folders, etc.). Strictly read-only — no emails are modified and no network calls are made.

Args: params (ListMailboxesInput): Input containing: - response_format (str): 'markdown' (default) or 'json'. - include_counts (bool): Add per-mailbox message counts to help choose search scope. Slower on many-mailbox setups. Default false.

Returns: str: Formatted list of all accounts and their mailboxes.

Markdown example:
    # Apple Mail Mailboxes

    ## iCloud
    - INBOX
    - Sent Messages
    - Drafts

JSON example:
    [
      {"account": "iCloud", "mailbox": "INBOX"},
      {"account": "iCloud", "mailbox": "Sent Messages"}
    ]

Examples: - Use when: "What mailboxes do I have?" → default params - Use when: "List my email folders as JSON" → response_format="json"

Error Handling: Returns an error string if Mail.app cannot be reached or there are no configured accounts. Prompts the user to open Mail.app if needed.

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.

Read the full content of a specific Apple Mail email by its ID.

Decodes the opaque email_id produced by mail_search_emails, locates the message in Apple Mail, and returns its complete content: subject, sender, recipients (To, CC), date received, read-status, and full body text.

Strictly read-only — the message read-status is NOT changed by this call.

Args: params (ReadEmailInput): Input containing: - email_id (str): Opaque ID from mail_search_emails. Required. - response_format (str): 'markdown' (default) or 'json'.

Returns: str: Full email content.

Markdown example:
    # Email: Invoice for March

    - **From**: billing@example.com
    - **To**: you@icloud.com
    - **CC**: (none)
    - **Date**: Monday, 3 March 2025 at 09:14:02
    - **Read**: Yes
    - **Mailbox**: iCloud / INBOX

    ## Body

    Hi there, please find your invoice attached...

JSON example:
    {
      "subject": "Invoice for March",
      "sender": "billing@example.com",
      "to": "you@icloud.com",
      "cc": "",
      "date": "Monday, 3 March 2025 at 09:14:02",
      "read": true,
      "account": "iCloud",
      "mailbox": "INBOX",
      "body": "Hi there, please find your invoice attached..."
    }

Examples: - Use when: "Read the email about invoices" (after searching) → pass the email_id from search results - Don't use when: You don't have an email_id yet → use mail_search_emails first

Error Handling: - Returns an error if the email_id is malformed or expired. - Returns an error if the message cannot be found (e.g. deleted since search). - Returns an error if Mail.app cannot be reached. - Reads on very large mailboxes (>30k messages) can take up to a minute; the mailbox is rescanned per read.