Apple Mail MCP Server

Overview Schema Source Related Servers Discussions Admin

Get Email Source

get_email_source

Retrieve the raw RFC 822 source of one email, keeping every header, MIME part, and href that rendered message bodies drop. Use it to inspect URLs, custom headers, or attachments.

Instructions

Return the raw RFC 822 source of a single message.

The MCP's other body-extraction paths return Mail.app's rendered content (HTML collapsed to display text, hrefs dropped, embedded objects replaced with U+FFFC). This tool returns the raw source instead — all headers, all MIME parts, all hrefs intact.

Implementation note:

Wraps the source property of message defined in Mail.sdef (the AppleScript dictionary for Mail.app). That property returns the same RFC 822 text Mail.app writes to the on-disk .partial.emlx file, so the consumer does not need filesystem access or knowledge of the Mail directory layout to recover MIME parts / hrefs / custom headers.

Identifier resolution: message_id is preferred when both are provided (exact match on the RFC 822 Message-Id header via AppleScript's message id property — distinct from id, which is Mail.app's internal numeric id). subject_keyword matches the first message in mailbox whose subject contains the substring.

Output sizing: messages can be large (a plain note is ~200 KB; with attachments far larger). max_bytes caps the returned payload and appends a truncation marker when exceeded. headers_only=True returns only the RFC 822 header block (everything up to and including the first blank line) — usually sufficient for URL/header inspection and avoids returning base64 bodies. Cap applies after the headers_only filter.

Input Schema

Name	Required	Description	Default
`account`	Yes	Account name (e.g., ``"Gmail"``, ``"Work"``).
`mailbox`	No	Mailbox name (default: ``"INBOX"``). Resolved via the shared ``build_mailbox_ref`` helper so non-English / Exchange inboxes (Posteingang, Bandeja de entrada, etc.) are found.	INBOX
`max_bytes`	No	Byte cap on the returned payload (default 256 KB).
`message_id`	No	RFC 822 Message-Id for exact match (preferred when known).
`headers_only`	No	When ``True``, return only the header block.
`subject_keyword`	No	Substring to match against subject (first hit).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv3.2.1Oct 20, 2026

TDQS

A4.7/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: output sizing (200 KB notes, larger with attachments), the max_bytes cap with an appended truncation marker, that the cap applies after the headers_only filter, and identifier precedence. It also discloses the underlying AppleScript mechanism, which is useful operational context.

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 the core purpose in the first sentence, and the sizing/identifier sections are well organized. The 'Implementation note' about Mail.sdef and .partial.emlx is somewhat more internal detail than an agent needs for selection, so it is not maximally tight.

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-value description is not required, and the description still covers payload sizing, truncation behavior, and identifier resolution. Nothing an agent needs to call this correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds meaning well beyond it: message_id is preferred when both ids are given and is the RFC 822 Message-Id (distinct from Mail.app's internal numeric id), and subject_keyword matches the first message in mailbox whose subject contains the substring. These precedence and matching semantics are not in the schema.

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 ('Return the raw RFC 822 source of a single message') and explicitly distinguishes itself from sibling body-extraction paths that return rendered content. An agent can tell exactly what this produces without opening the schema.

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

Usage Guidelines4/5

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

It gives clear context for when this is the right tool (recovering MIME parts, hrefs, custom headers) and steers toward headers_only for header/URL inspection. It does not name a specific sibling tool as an alternative, but the contrast with rendered-content paths is strong enough to route selection correctly.

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