Apple Mail MCP Server

Overview Schema Source Related Servers Discussions Admin

Synchronize Account

synchronize_account

Force Apple Mail to sync a specific account or all accounts with IMAP/Exchange now. Use after moving, updating, or trashing emails so other clients see changes without waiting for automatic sync.

Instructions

Force Mail.app to synchronize an account (or every account) with its IMAP / Exchange server right now. Equivalent to clicking the refresh button next to the account or selecting Mailbox → Synchronize.

Use after move_email, update_email_status, or manage_trash when downstream clients (iPhone, web mail, etc.) need to see the change immediately. Mail.app's natural sync cadence is "automatic" which can be several minutes — this collapses that to one IMAP push.

Implementation note:

Uses the synchronize with <account> AppleScript verb (per Mail.sdef: "Command to trigger synchronizing of an IMAP account with the server") rather than check for new mail. The latter is receive-only — it pulls new messages but does NOT push pending IMAP commands like queued moves / archives / flag changes. With check for new mail, archives done via move_email could sit in Mail.app's local cache for several minutes before reaching the IMAP server, leaving iPhone Mail (which reads IMAP directly) showing already-archived messages still in INBOX. synchronize with is the bidirectional verb that drains pending IMAP commands AND fetches new mail.

Mail.app's synchronize is potentially long-running. We wrap each invocation in with timeout of N seconds so the AppleScript returns promptly. When the timeout fires (error -1712) Mail.app keeps the sync running in the background — exactly the fire-and-forget semantics callers expect.

Input Schema

Name	Required	Description	Default
`account`	No	Account name (e.g., "Gmail", "Work"). Omit to sync every configured account.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 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\"). Omit to sync every\n     configured account."
```
- removedInput schema / properties / account / title
```
Removed value: -"Account"
```
- removedInput schema / title
```
Removed value: -"synchronize_accountArguments"
```
- removedOutput schema / properties / result / title
```
Removed value: -"Result"
```
- removedOutput schema / title
```
Removed value: -"synchronize_accountOutput"
```
- addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```
Addedv3.1.4Jun 3, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so richly: it discloses bidirectional push semantics vs receive-only, long-running behavior, the AppleScript timeout wrapper (error -1712), and fire-and-forget semantics after timeout. This is far more behavioral context than annotations would normally supply.

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?

Front-loaded with purpose and usage before the implementation note, and the structure is clear. The implementation note is lengthy and somewhat beyond what an agent strictly needs to invoke the tool, but each part does carry real behavioral value.

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

Completeness5/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 values need not be explained. Given a single optional param and no annotations, the description supplies everything an agent needs: purpose, timing, push semantics, and timeout behavior.

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% and the single optional param is already documented ('Omit to sync every configured account'). The description's 'account (or every account)' framing mirrors the schema but adds no new syntax or format detail, so the baseline 3 is appropriate.

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

Purpose5/5

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

States a specific verb and resource: force Mail.app to synchronize an account (or all accounts) with its IMAP/Exchange server. It explicitly contrasts with the sibling-ish concept of 'check for new mail', so an agent can distinguish the action from passive polling without opening anything else.

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

Usage Guidelines5/5

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

Gives explicit when-to-use guidance ('Use after move_email, update_email_status, or manage_trash when downstream clients need to see the change immediately') and names the relevant sibling tools. It also explains the condition (natural cadence of several minutes) that motivates calling it at all.

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