docs: update README and CLAUDE.md for v1.1.0 features

Update documentation to reflect all 39 tools including new batch
operations, mailbox management, rules, contacts, templates, attachment
saving, date range search, HTML content, pagination, and multi-account
search. Fix outdated known limitations and default account description.

CLAUDE.md

@@ -12,15 +12,16 @@ This MCP server enables AI assistants to interact with Apple Mail on macOS via A
 
 The MCP protocol uses JSON for parameters. In JSON, `\` is an escape character. To include a literal backslash:
 
-| You want | Send in JSON parameter |
-|----------|------------------------|
-| `\` | `\\` |
-| `\\` | `\\\\` |
-| `C:\Users\` | `C:\\Users\\` |
+| You want    | Send in JSON parameter |
+|-------------|------------------------|
+| `\`         | `\\`                   |
+| `\\`        | `\\\\`                 |
+| `C:\Users\` | `C:\\Users\\`          |
 
 ### Why This Matters
 
 If you send a single backslash without escaping:
+
 - The JSON parser interprets `\` as an escape sequence
 - Invalid sequences like `\ ` (backslash-space) cause silent failures
 - The email send/draft may fail with no clear error
@@ -28,12 +29,14 @@ If you send a single backslash without escaping:
 ### Examples
 
 **Correct - Windows path in email:**
-```
+
+```text
 body: "The file is at C:\\Users\\Documents\\report.pdf"
 ```
 
 **Incorrect - Will fail:**
-```
+
+```text
 body: "The file is at C:\Users\Documents\report.pdf"
 ```
 
@@ -43,7 +46,7 @@ body: "The file is at C:\Users\Documents\report.pdf"
 
 All message operations require an `id` parameter. **Always get IDs first** using `list-messages` or `search-messages`:
 
-```
+```text
 # List messages returns IDs
 list-messages mailbox="INBOX"
 → Messages with IDs like "12345", "12346", etc.
@@ -60,6 +63,7 @@ reply-to-message id="12345" body="Thanks!"
 The `to`, `cc`, and `bcc` parameters must always be arrays:
 
 **Correct:**
+
 ```json
 {
   "to": ["bob@example.com"],
@@ -68,6 +72,7 @@ The `to`, `cc`, and `bcc` parameters must always be arrays:
 ```
 
 **Incorrect:**
+
 ```json
 {
   "to": "bob@example.com",
@@ -95,20 +100,21 @@ The `to`, `cc`, and `bcc` parameters must always be arrays:
 
 ### Multi-account
 
-- Default account is typically the first configured
+- Default account is Mail.app's configured default send account
+- `search-messages` searches all accounts when no `account` is specified
 - Use `list-accounts` to see available accounts
 - Pass `account` parameter to target specific account
 
 ## Error Handling
 
-| Error | Likely Cause |
-|-------|--------------|
-| "Mail.app not responding" | Mail.app frozen or not running |
-| "Message not found" | Message ID is invalid or message was deleted/moved |
-| "Permission denied" | macOS automation permission needed |
-| "Account not found" | Account name doesn't match exactly (case-sensitive) |
-| "Failed to send email" | Network issue or Mail.app configuration problem |
-| Silent failure | Backslash not escaped in content |
+| Error                    | Likely Cause                                  |
+|--------------------------|-----------------------------------------------|
+| "Mail.app not responding" | Mail.app frozen or not running               |
+| "Message not found"      | Message ID is invalid or message was deleted/moved |
+| "Permission denied"      | macOS automation permission needed            |
+| "Account not found"      | Account name doesn't match exactly (case-sensitive) |
+| "Failed to send email"   | Network issue or Mail.app configuration problem |
+| Silent failure           | Backslash not escaped in content              |
 
 ## Security Considerations
 
@@ -119,21 +125,24 @@ The `to`, `cc`, and `bcc` parameters must always be arrays:
 ## Example Workflows
 
 ### Check for important emails
-```
+
+```text
 1. list-accounts → get available accounts
 2. search-messages query="boss@company.com" → find emails from boss
 3. get-message id="..." → read the full content
 ```
 
 ### Send a reply safely
-```
+
+```text
 1. get-message id="..." → read original message
 2. reply-to-message id="..." body="..." send=false → save as draft
 3. Tell user to review in Mail.app before sending
 ```
 
 ### Compose and send
-```
+
+```text
 1. create-draft to=["recipient@example.com"] subject="..." body="..."
 2. Tell user: "I've created a draft. Review it in Mail.app and send when ready."
    OR if user confirms they want to send immediately:
@@ -141,35 +150,81 @@ The `to`, `cc`, and `bcc` parameters must always be arrays:
 ```
 
 ### Forward an email
-```
+
+```text
 1. get-message id="..." → read the message to forward
 2. forward-message id="..." to=["colleague@company.com"] body="FYI - see below"
 ```
 
 ### Organize inbox
-```
+
+```text
 1. search-messages query="newsletter" → find newsletters
 2. For each: move-message id="..." mailbox="Archive"
 ```
 
 ### Batch operations (efficient for multiple messages)
-```
+
+```text
 1. search-messages query="old" → find messages to clean up
 2. batch-delete-messages ids=["123", "456", "789"] → delete multiple
    OR
    batch-move-messages ids=["123", "456"] mailbox="Archive" → archive multiple
    OR
    batch-mark-as-read ids=["123", "456"] → mark multiple as read
+   OR
+   batch-mark-as-unread ids=["123", "456"] → mark multiple as unread
+   OR
+   batch-flag-messages ids=["123", "456"] → flag multiple
+   OR
+   batch-unflag-messages ids=["123", "456"] → unflag multiple
 ```
 
 ### Check for attachments
-```
+
+```text
 1. list-messages mailbox="INBOX" → get message IDs
 2. list-attachments id="..." → see attachments (name, MIME type, size)
+3. save-attachment id="..." attachmentName="report.pdf" savePath="/tmp" → save to disk
 ```
 
-### Check mail sync status
+### Manage mailboxes
+
+```text
+1. list-mailboxes → see all folders
+2. create-mailbox name="Projects" → create new folder
+3. rename-mailbox oldName="Projects" newName="Active Projects" → rename
+4. delete-mailbox name="Old Folder" → delete
+```
+
+### Work with mail rules
+
+```text
+1. list-rules → see all rules and their status
+2. disable-rule name="Newsletter Filter" → turn off a rule
+3. enable-rule name="Newsletter Filter" → turn it back on
 ```
+
+### Look up contacts
+
+```text
+1. search-contacts query="John" → find contacts by name
+   Returns names, email addresses, and phone numbers from Contacts.app
+```
+
+### Use email templates
+
+```text
+1. save-template name="Weekly Report" subject="Weekly Report" body="..." to=["team@..."]
+2. list-templates → see saved templates
+3. use-template id="tmpl_1" → create draft from template
+4. use-template id="tmpl_1" to=["other@..."] → override recipients
+   Note: templates are stored in memory and reset when the server restarts
+```
+
+### Check mail sync status
+
+```text
 1. get-sync-status → see if Mail.app is running and syncing
 2. get-mail-stats → see total/unread counts and recently received counts
 ```

README.md

@@ -77,24 +77,49 @@ On first use, macOS will ask for permission to automate Mail.app. Click "OK" to
 
 ## Features
 
+### Messages
+
 | Feature | Description |
 |---------|-------------|
-| **List Messages** | List messages in any mailbox |
-| **Search Messages** | Find emails by sender, subject, content |
-| **Read Messages** | Get full email content |
+| **List Messages** | List messages with pagination, sender filter, date display |
+| **Search Messages** | Search by sender, subject, content, date range, read/flagged status — across all accounts |
+| **Read Messages** | Get full email content (plain text or HTML) |
 | **Send Email** | Compose and send new emails |
 | **Create Draft** | Save emails to Drafts folder |
 | **Reply** | Reply to messages (with reply-all support) |
 | **Forward** | Forward messages to new recipients |
-| **Mark Read/Unread** | Change read status |
-| **Flag/Unflag** | Flag or unflag messages |
-| **Delete Messages** | Move messages to trash |
-| **Move Messages** | Organize into mailboxes |
-| **List Mailboxes** | Show all folders with counts |
+| **Mark Read/Unread** | Change read status (single or batch) |
+| **Flag/Unflag** | Flag or unflag messages (single or batch) |
+| **Delete Messages** | Move messages to trash (single or batch) |
+| **Move Messages** | Organize into mailboxes (single or batch) |
+| **List Attachments** | View attachment metadata (name, type, size) |
+| **Save Attachment** | Save attachments to disk |
+
+### Mailbox & Account Management
+
+| Feature | Description |
+|---------|-------------|
+| **List Mailboxes** | Show all folders with message/unread counts |
+| **Create/Delete/Rename Mailbox** | Full mailbox lifecycle management |
 | **List Accounts** | Show configured accounts |
 | **Unread Count** | Get unread counts per mailbox |
+
+### Rules, Contacts & Templates
+
+| Feature | Description |
+|---------|-------------|
+| **List Rules** | View all mail rules and their enabled status |
+| **Enable/Disable Rules** | Toggle mail rules on or off |
+| **Search Contacts** | Look up contacts from Contacts.app by name |
+| **Email Templates** | Save, list, use, and delete reusable email templates |
+
+### Diagnostics
+
+| Feature | Description |
+|---------|-------------|
 | **Health Check** | Verify Mail.app connectivity |
-| **Statistics** | Message and unread counts |
+| **Statistics** | Message and unread counts per account, recently received stats |
+| **Sync Status** | Check if Mail.app is actively syncing |
 
 ---
 
@@ -106,13 +131,19 @@ This section documents all available tools. AI agents should use these tool name
 
 #### `search-messages`
 
-Search for messages matching criteria.
+Search for messages matching criteria. Searches all accounts by default.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `query` | string | No | Text to search in subject/sender |
+| `from` | string | No | Filter by sender email address |
+| `subject` | string | No | Filter by subject line |
 | `mailbox` | string | No | Mailbox to search in (default: INBOX) |
-| `account` | string | No | Account to search in |
+| `account` | string | No | Account to search in (omit to search all accounts) |
+| `isRead` | boolean | No | Filter by read status |
+| `isFlagged` | boolean | No | Filter by flagged status |
+| `dateFrom` | string | No | Start date filter (e.g., "January 1, 2026") |
+| `dateTo` | string | No | End date filter (e.g., "March 1, 2026") |
 | `limit` | number | No | Max results (default: 50) |
 
 ---
@@ -124,8 +155,9 @@ Get the full content of a message.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
+| `preferHtml` | boolean | No | Return HTML source instead of plain text |
 
-**Returns:** Subject line and plain text body of the message.
+**Returns:** Subject line and message body (plain text by default, HTML if `preferHtml` is true and HTML content is available).
 
 ---
 
@@ -138,8 +170,11 @@ List messages in a mailbox.
 | `mailbox` | string | No | Mailbox name (default: INBOX) |
 | `account` | string | No | Account name |
 | `limit` | number | No | Max messages (default: 50) |
+| `offset` | number | No | Number of messages to skip (for pagination) |
+| `from` | string | No | Filter by sender email address or name |
+| `unreadOnly` | boolean | No | Only show unread messages |
 
-**Returns:** List of messages with ID, subject, sender, date, read status, and flagged status.
+**Returns:** List of messages with ID, date, subject, and sender.
 
 ---
 
@@ -271,6 +306,62 @@ Move a message to a different mailbox.
 
 ---
 
+#### `list-attachments`
+
+List attachments on a message.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Message ID |
+
+**Returns:** List of attachments with name, MIME type, and size.
+
+---
+
+#### `save-attachment`
+
+Save a message attachment to disk.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Message ID |
+| `attachmentName` | string | Yes | Filename of the attachment |
+| `savePath` | string | Yes | Directory to save to |
+
+---
+
+### Batch Operations
+
+All batch operations accept an array of message IDs and return per-item success/failure results.
+
+#### `batch-delete-messages`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | Message IDs to delete |
+
+#### `batch-move-messages`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | Message IDs to move |
+| `mailbox` | string | Yes | Destination mailbox |
+| `account` | string | No | Account containing mailbox |
+
+#### `batch-mark-as-read` / `batch-mark-as-unread`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | Message IDs |
+
+#### `batch-flag-messages` / `batch-unflag-messages`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ids` | string[] | Yes | Message IDs |
+
+---
+
 ### Mailbox Operations
 
 #### `list-mailboxes`
@@ -281,7 +372,7 @@ List all mailboxes for an account.
 |-----------|------|----------|-------------|
 | `account` | string | No | Account to list from |
 
-**Returns:** List of mailbox names with unread counts.
+**Returns:** List of mailbox names with message and unread counts.
 
 ---
 
@@ -296,6 +387,40 @@ Get unread message count.
 
 ---
 
+#### `create-mailbox`
+
+Create a new mailbox.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Mailbox name |
+| `account` | string | No | Account to create in |
+
+---
+
+#### `delete-mailbox`
+
+Delete a mailbox.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Mailbox name |
+| `account` | string | No | Account containing mailbox |
+
+---
+
+#### `rename-mailbox`
+
+Rename a mailbox (creates new, moves messages, deletes old).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `oldName` | string | Yes | Current mailbox name |
+| `newName` | string | Yes | New mailbox name |
+| `account` | string | No | Account containing mailbox |
+
+---
+
 ### Account Operations
 
 #### `list-accounts`
@@ -304,7 +429,105 @@ List all configured Mail accounts.
 
 **Parameters:** None
 
-**Returns:** List of account names (e.g., "iCloud", "Gmail", "Exchange").
+**Returns:** List of account names and email addresses.
+
+---
+
+### Rules
+
+#### `list-rules`
+
+List all mail rules.
+
+**Parameters:** None
+
+**Returns:** List of rule names and enabled status.
+
+---
+
+#### `enable-rule` / `disable-rule`
+
+Enable or disable a mail rule.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Rule name |
+
+---
+
+### Contacts
+
+#### `search-contacts`
+
+Search contacts in Contacts.app.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Name to search for |
+| `limit` | number | No | Max results (default: 10) |
+
+**Returns:** List of contacts with name, email addresses, and phone numbers.
+
+---
+
+### Templates
+
+Email templates are stored in memory for the duration of the server session.
+
+#### `save-template`
+
+Save or update an email template.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Template name |
+| `subject` | string | Yes | Default subject line |
+| `body` | string | Yes | Template body |
+| `to` | string[] | No | Default recipients |
+| `cc` | string[] | No | Default CC recipients |
+| `id` | string | No | Template ID (for updating) |
+
+---
+
+#### `list-templates`
+
+List all saved templates.
+
+**Parameters:** None
+
+---
+
+#### `get-template`
+
+Get a template by ID.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Template ID |
+
+---
+
+#### `delete-template`
+
+Delete a template.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Template ID |
+
+---
+
+#### `use-template`
+
+Create a draft from a template, with optional overrides.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Template ID |
+| `to` | string[] | No | Override recipients |
+| `cc` | string[] | No | Override CC |
+| `subject` | string | No | Override subject |
+| `body` | string | No | Override body |
 
 ---
 
@@ -322,11 +545,21 @@ Verify Mail.app connectivity and permissions.
 
 #### `get-mail-stats`
 
-Get mail statistics (total messages, unread counts per account).
+Get mail statistics.
+
+**Parameters:** None
+
+**Returns:** Total and per-account message/unread counts, plus recently received stats (24h, 7d, 30d).
+
+---
+
+#### `get-sync-status`
+
+Check Mail.app sync activity.
 
 **Parameters:** None
 
-**Returns:** Total counts and per-account breakdown.
+**Returns:** Whether sync is detected, pending uploads, recent activity, and seconds since last change.
 
 ---
 
@@ -350,7 +583,7 @@ AI: [calls get-message with id="..."]
 
 ### Working with Accounts
 
-By default, operations use the first configured account. To work with specific accounts:
+By default, operations use Mail.app's configured default send account. Search operations check all accounts when no account is specified. To work with specific accounts:
 
 ```
 User: "What email accounts do I have?"
@@ -429,10 +662,10 @@ If installed from source, use this configuration:
 | Limitation | Reason |
 |------------|--------|
 | macOS only | Apple Mail and AppleScript are macOS-specific |
-| Plain text only | Email body is plain text; HTML formatting not supported |
-| No attachments | Cannot add or read attachments via AppleScript |
-| Message ID scope | Message IDs are searched across all mailboxes (may be slow with large mailboxes) |
+| No sending HTML email | Emails are sent as plain text; reading HTML content is supported |
+| No adding attachments | Can list and save existing attachments, but cannot attach files to outgoing emails |
 | No smart mailboxes | Cannot access Smart Mailboxes via AppleScript |
+| In-memory templates | Email templates are not persisted across server restarts |
 
 ### Backslash Escaping (Important for AI Agents)