Apple Mail MCP Server

Overview Schema Source Related Servers Discussions Admin

Get Email Thread

get_email_thread

Retrieve a full email conversation thread by linking messages through Message-ID, In-Reply-To, and References headers, so same-subject messages from other threads are not mixed in.

Instructions

Get an email conversation thread - messages linked by Message-ID, not just by subject.

Candidates are found by subject (fast, filtered inside Mail), then linked through their Message-ID / In-Reply-To / References headers. Messages that merely share the subject but belong to a different conversation are listed separately instead of being mixed into the thread.

Input Schema

Name	Required	Description	Default
`account`	Yes	Account name (e.g., "Gmail", "Work")
`mailbox`	No	Mailbox to search in (default: "INBOX", use "All" for all mailboxes)	INBOX
`max_messages`	No	Maximum number of candidate messages to inspect (default: 50). The cap applies before linking: only the first N subject matches that Mail returns are considered, so the thread is seeded from the newest of those N, not necessarily the newest message overall. Raise it for long-running subjects.
`subject_keyword`	Yes	Keyword to identify the thread (e.g., "Re: Project Update")

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv3.2.1Oct 20, 2026

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

addedInput schema / properties / account / description

Added value: +"Account name (e.g., \"Gmail\", \"Work\")"

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

addedInput schema / properties / mailbox / description

Added value: +"Mailbox to search in (default: \"INBOX\", use \"All\" for all mailboxes)"

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

addedInput schema / properties / max_messages / description

Added value: +"Maximum number of candidate messages to inspect (default: 50).\nThe cap applies before linking: only the first N subject matches\nthat Mail returns are considered, so the thread is seeded from the\nnewest of those N, not necessarily the newest message overall.\nRaise it for long-running subjects."

removedInput schema / properties / max_messages / title
```
Removed value: -"Max Messages"
```

addedInput schema / properties / subject_keyword / description

Added value: +"Keyword to identify the thread (e.g., \"Re: Project Update\")"

removedInput schema / properties / subject_keyword / title
```
Removed value: -"Subject Keyword"
```

removedInput schema / title

Removed value: -"get_email_threadArguments"

removedOutput schema / properties / result / title
```
Removed value: -"Result"
```

removedOutput schema / title

Removed value: -"get_email_threadOutput"

addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```

First observedv3.1.0Apr 2, 2026

TDQS

A3.7/5.0

Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the two-phase strategy (subject-filtered candidates, then header linking) and, importantly, that same-subject messages from other conversations are surfaced separately rather than merged. It omits read-only confirmation, permissions, and failure behavior, keeping it from a 5.

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

Conciseness4/5

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

Three sentences, front-loaded with the core definition and then the mechanics; no filler. It is slightly more verbose than strictly required, but every sentence conveys real information about how the thread is assembled.

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

Completeness4/5

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

An output schema exists, so return-value description is unnecessary, and the description compensates well for the absent annotations by explaining the linking heuristic and its edge case. Remaining gaps (auth requirements, behavior when no thread is found) are minor for a read-only getter.

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 coverage is 100%, so all four parameters are already documented in the schema. The description's note that candidates are 'found by subject' adds a little color to subject_keyword, but it does not explain the max_messages cap that the schema itself handles in depth. Baseline 3 is appropriate.

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?

States a specific verb+resource ('Get an email conversation thread') and goes further by defining what constitutes a thread (Message-ID linking, not subject sharing). This implicitly separates it from search_emails, though no sibling is named outright, so it stops short of a 5.

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?

The description conveys the scenario it fits (reconstructing a full conversation rather than finding messages by keyword), but it never states when to prefer it over search_emails or get_email_source, nor any prerequisites. Usage must be inferred from the algorithmic explanation.

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