Apple Mail MCP Server

by patrickfreyer

Overview Schema Source Related Servers Discussions Admin

Python

Local

Update Email Status

update_email_status

Mark Apple Mail messages as read/unread or flag/unflag them by exact IDs or by subject, sender, and age filters.

Instructions

Update email status - mark as read/unread or flag/unflag emails.

When message_ids is provided, uses exact ID matching (ignores other filters). Otherwise filters by subject, sender, and/or age.

Input Schema

Name	Required	Description	Default
`action`	Yes	Action to perform: "mark_read", "mark_unread", "flag", "unflag"
`sender`	No	Optional sender to filter emails by
`account`	Yes	Account name (e.g., "Gmail", "Work")
`mailbox`	No	Mailbox to search in (default: "INBOX")	INBOX
`flag_color`	No	Optional flag color for the "flag" action: "red", "orange", "yellow", "green", "blue", "purple", or "gray". Omit to flag without setting a color — Mail shows its default (red), or the message's previous color if one remains from an earlier flag. Re-colors messages that are already flagged.
`max_updates`	No	Maximum number of emails to update (safety limit, default: 10)
`message_ids`	No	Optional list of exact Mail message ids for precise targeting
`apply_to_all`	No	Must be True to allow updates without any filter
`older_than_days`	No	Optional age filter - only update emails older than N days
`subject_keyword`	No	Optional keyword to filter emails by subject
`subject_keywords`	No	Optional list of subject keywords; matches any keyword

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed27 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 / action / description

Added value: +"Action to perform: \"mark_read\", \"mark_unread\", \"flag\", \"unflag\""

removedInput schema / properties / action / title
```
Removed value: -"Action"
```

addedInput schema / properties / apply_to_all / description

Added value: +"Must be True to allow updates without any filter"

removedInput schema / properties / apply_to_all / title
```
Removed value: -"Apply To All"
```

addedInput schema / properties / flag_color / description

Added value: +"Optional flag color for the \"flag\" action: \"red\", \"orange\",\n\"yellow\", \"green\", \"blue\", \"purple\", or \"gray\". Omit to flag\nwithout setting a color — Mail shows its default (red), or the\nmessage's previous color if one remains from an earlier flag.\nRe-colors messages that are already flagged."

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

addedInput schema / properties / mailbox / description

Added value: +"Mailbox to search in (default: \"INBOX\")"

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

addedInput schema / properties / max_updates / description

Added value: +"Maximum number of emails to update (safety limit, default: 10)"

removedInput schema / properties / max_updates / title
```
Removed value: -"Max Updates"
```

addedInput schema / properties / message_ids / description

Added value: +"Optional list of exact Mail message ids for precise targeting"

removedInput schema / properties / message_ids / title
```
Removed value: -"Message Ids"
```

addedInput schema / properties / older_than_days / description

Added value: +"Optional age filter - only update emails older than N days"

removedInput schema / properties / older_than_days / title
```
Removed value: -"Older Than Days"
```

addedInput schema / properties / sender / description

Added value: +"Optional sender to filter emails by"

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

addedInput schema / properties / subject_keyword / description

Added value: +"Optional keyword to filter emails by 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: -"update_email_statusArguments"

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

removedOutput schema / title

Removed value: -"update_email_statusOutput"

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

Changed1 schema field changedv3.1.8Jun 26, 2026

addedInput schema / properties / flag_color

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

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 only partially delivers: it discloses the message_ids-vs-filters precedence rule. It says nothing about safety limits (max_updates, apply_to_all exist in the schema but their guardrail intent is unexplained), reversibility of the updates, or required permissions.

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 compact sentences, front-loaded with purpose and followed by the precedence behavior; nothing is padded. Slightly more guidance could have been added without waste, but it is efficiently structured.

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 and parameter coverage is complete, so the agent needs little more than purpose plus filter behavior, both of which are present. The absence of any note on the relationship to sibling mutation tools is the only meaningful gap.

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 schema already documents all 11 parameters in detail, making 3 the baseline. The description adds only the filter-precedence nuance and no further parameter-level meaning beyond what the schema 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?

States a specific verb and resource ('Update email status') and enumerates the concrete actions (mark as read/unread, flag/unflag), so an agent knows exactly what it does. It does not, however, differentiate itself from siblings that also mutate message state (e.g. move_email, manage_trash), 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 gives one useful routing rule — that supplying message_ids switches to exact-ID matching and ignores other filters — which is genuine conditional guidance. It offers no explanation of when to prefer this tool over its many siblings or when not to use it, leaving usage largely implied.

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