mail_list_mailboxes
List all mailboxes and folders in Apple Mail, grouped by account. Returns results in markdown or JSON format with optional message counts.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |