Apple Mail MCP Server

Overview Schema Source Related Servers Discussions Admin

List Inbox Emails

list_inbox_emails

List inbox emails from all Apple Mail accounts or a chosen account, with filters for max results, read status, output format, and optional content preview.

Instructions

List all emails from inbox across all accounts or a specific account.

Replaces the former get_recent_emails tool — use account + max_emails to get recent emails from a single account.

Input Schema

Name	Required	Description	Default
`account`	No	Optional account name to filter (e.g., "Gmail", "Work"). If None, shows all accounts.
`max_emails`	No	Maximum number of emails to return per account (0 = all)
`include_read`	No	Whether to include read emails (default: True)
`output_format`	No	"text" (default, human-readable) or "json" (structured list of email dicts)	text
`include_content`	No	Whether to include a content preview for each email (slower, default: False)

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedv3.2.1Oct 20, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```
- addedInput schema / properties / account / description
```
Added value: +"Optional account name to filter (e.g., \"Gmail\", \"Work\"). If None, shows all accounts."
```
- removedInput schema / properties / account / title
```
Removed value: -"Account"
```
- addedInput schema / properties / include_content / description
```
Added value: +"Whether to include a content preview for each email (slower, default: False)"
```
- removedInput schema / properties / include_content / title
```
Removed value: -"Include Content"
```
- addedInput schema / properties / include_read / description
```
Added value: +"Whether to include read emails (default: True)"
```
- removedInput schema / properties / include_read / title
```
Removed value: -"Include Read"
```
- addedInput schema / properties / max_emails / description
```
Added value: +"Maximum number of emails to return per account (0 = all)"
```
- removedInput schema / properties / max_emails / title
```
Removed value: -"Max Emails"
```
- addedInput schema / properties / output_format / description
```
Added value: +"\"text\" (default, human-readable) or \"json\" (structured list of email dicts)"
```
- removedInput schema / properties / output_format / title
```
Removed value: -"Output Format"
```
- removedInput schema / title
```
Removed value: -"list_inbox_emailsArguments"
```
- removedOutput schema / properties / result / title
```
Removed value: -"Result"
```
- removedOutput schema / title
```
Removed value: -"list_inbox_emailsOutput"
```
- addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```
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?

With no annotations, the description carries the full behavioral burden, and it discloses little beyond the account+max_emails combination behavior. It omits ordering, pagination, whether spam/trash are included, and how read/unread filtering interacts, though as a pure read list the safety profile is at least self-evident and an output schema covers return shape.

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?

Two short, front-loaded sentences with no filler; the purpose leads and the usage hint follows. The deprecated-tool note is the least load-bearing element but is still useful for agents migrating from the old name.

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?

For a low-risk listing tool with full schema coverage and an output schema, the description covers what is needed to call it correctly. It stops short of routing among the many inbox-related siblings, which would make it fully complete.

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 all five parameters are already documented with defaults and formats. The description adds only the combined account+max_emails intent, which is marginal beyond the schema's per-field descriptions.

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 clear verb+resource ("List all emails from inbox") with scope ("across all accounts or a specific account"). It does not explicitly contrast with the live sibling search_emails, which is the closest alternative, so differentiation is only partial.

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?

Gives one concrete usage recipe ("use account + max_emails to get recent emails from a single account") and notes it replaces get_recent_emails, which is migration info rather than live-sibling guidance. It never states when to prefer search_emails or get_inbox_overview, nor any exclusion conditions.

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