Apple Mail MCP Server

Overview Schema Source Related Servers Discussions Admin

Search Emails

search_emails

Search emails across accounts by subject, sender, body, dates, and flags. Get paginated JSON or text results for unified email management.

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.

Input Schema

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

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed43 schema fields changedv3.2.1Oct 20, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / account / description

Added value: +"Account name to search in (e.g., \"Gmail\", \"Work\").\nIf None, searches ALL accounts (slower)."

removedInput schema / properties / account / title
```
Removed value: -"Account"
```

addedInput schema / properties / body_text / description

Added value: +"Optional text to search for in email body content (case-insensitive).\nWARNING: body search is significantly slower as it reads each message body."

removedInput schema / properties / body_text / title
```
Removed value: -"Body Text"
```

addedInput schema / properties / date_from / description

Added value: +"Optional start date filter (format: \"YYYY-MM-DD\")"

removedInput schema / properties / date_from / title
```
Removed value: -"Date From"
```

addedInput schema / properties / date_to / description

Added value: +"Optional end date filter (format: \"YYYY-MM-DD\")"

removedInput schema / properties / date_to / title
```
Removed value: -"Date To"
```

addedInput schema / properties / flag_color / description

Added value: +"Optional filter for a specific flag color: \"red\", \"orange\",\n\"yellow\", \"green\", \"blue\", \"purple\", or \"gray\". Implies flagged=True."

removedInput schema / properties / flag_color / title
```
Removed value: -"Flag Color"
```

addedInput schema / properties / flagged / description

Added value: +"Optional filter for flagged emails (True/False/None)"

removedInput schema / properties / flagged / title
```
Removed value: -"Flagged"
```

addedInput schema / properties / has_attachments / description

Added value: +"Optional filter for emails with attachments (True/False/None)"

removedInput schema / properties / has_attachments / title
```
Removed value: -"Has Attachments"
```

addedInput schema / properties / include_content / description

Added value: +"Whether to include email content preview (slower)"

removedInput schema / properties / include_content / title
```
Removed value: -"Include Content"
```

addedInput schema / properties / limit / description

Added value: +"Maximum number of results to return per page"

removedInput schema / properties / limit / title
```
Removed value: -"Limit"
```

addedInput schema / properties / mailbox / description

Added value: +"Mailbox to search (default: \"INBOX\", use \"All\" for all mailboxes, or specific folder name)"

removedInput schema / properties / mailbox / title
```
Removed value: -"Mailbox"
```

addedInput schema / properties / max_content_length / description

Added value: +"Maximum content length in characters when include_content=True (default: 500, 0 = unlimited)"

removedInput schema / properties / max_content_length / title
```
Removed value: -"Max Content Length"
```
addedInput schema / properties / max_results / description
```
Added value: +"Backward-compatible alias for limit"
```
removedInput schema / properties / max_results / title
```
Removed value: -"Max Results"
```

addedInput schema / properties / offset / description

Added value: +"Number of matching results to skip before returning data"

removedInput schema / properties / offset / title
```
Removed value: -"Offset"
```

addedInput schema / properties / output_format / description

Added value: +"Output format: \"text\" or \"json\" (default: \"text\")"

removedInput schema / properties / output_format / title
```
Removed value: -"Output Format"
```

addedInput schema / properties / read_status / description

Added value: +"Filter by read status: \"all\", \"read\", \"unread\" (default: \"all\")"

removedInput schema / properties / read_status / title
```
Removed value: -"Read Status"
```

addedInput schema / properties / sender / description

Added value: +"Optional sender email or name to filter by"

removedInput schema / properties / sender / title
```
Removed value: -"Sender"
```

addedInput schema / properties / sort / description

Added value: +"Result sort order: \"date_desc\" or \"date_asc\""

removedInput schema / properties / sort / title
```
Removed value: -"Sort"
```
addedInput schema / properties / subject_keyword / description
```
Added value: +"Optional keyword to search in subject"
```
removedInput schema / properties / subject_keyword / title
```
Removed value: -"Subject Keyword"
```

addedInput schema / properties / subject_keywords / description

Added value: +"Optional list of subject keywords; matches any keyword"

removedInput schema / properties / subject_keywords / title
```
Removed value: -"Subject Keywords"
```

removedInput schema / title

Removed value: -"search_emailsArguments"

removedOutput schema / properties / result / title
```
Removed value: -"Result"
```
removedOutput schema / title
```
Removed value: -"search_emailsOutput"
```
addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```

Changed2 schema fields changedv3.1.8Jun 26, 2026

addedInput schema / properties / flag_color

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Flag Color"
+}

addedInput schema / properties / flagged

Added value: +{
+  "anyOf": [
+    {
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Flagged"
+}

First observedv3.1.0Apr 2, 2026

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It mentions JSON output, pagination, and real date filtering, but omits read-only nature, authorization requirements, and performance implications beyond what individual schema fields already say.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with scope and capabilities. Every sentence contributes either purpose or differentiation, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The schema and output schema cover parameters and return values, so the description need not restate them. However, with 19 parameters and no annotations, the description is thin on when to choose this over list_inbox_emails and on behavioral caveats, leaving notable gaps for a complex search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds only a high-level mapping to subject, sender, body, cross-account, and date filtering, without parameter-specific detail beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('search tool' for emails) and lists the search modes it consolidates: subject, sender, body, and cross-account. This distinguishes it from simple listing tools like list_inbox_emails, though it does not name those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies use for subject, sender, body, and cross-account searches by saying it consolidates them, but gives no explicit when-to-use or when-not guidance. It also does not name alternatives such as list_inbox_emails, so selection guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.