Skip to main content
Glama
sweetrb

apple-mail-mcp

by sweetrb
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

get-message

Read a specific email's full body by its ID, choosing plain text or HTML, and retrieve subject, sender, and received dates for deduplication or threading.

Instructions

Use when: reading the full body of one message whose id you already have (numeric or imap:…); set preferHtml to get the HTML body instead of plain text. Returns: the message subject, body (plain text by default, HTML when preferHtml is true), its stable RFC Message-ID (rfcMessageId) for dedup/threading, and two dates: dateSent (the author's Date: header — survives a migration/re-import) and dateReceived (arrival in the mailbox; this is the one a migration resets). Tip: pass the mailbox+account you got the id from (e.g. from search-messages) to fetch it directly — required for reliable reads of large folders like "Sent Items", which otherwise time out. Do not use when: you don't yet have an id (use search-messages or list-messages first), you want the whole conversation (use get-thread), or you need the raw headers / Received: trace (use get-message-headers).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYes
accountNoAccount that holds the message. Pair with `mailbox` for a direct, scan-free fetch.
mailboxNoMailbox that holds the message (e.g. "Sent Items"). Numeric ids are unique per mailbox; supplying this (with account) opens that mailbox directly instead of scanning every mailbox, which is required to read large folders like Sent Items without timing out.
preferHtmlNoReturn the HTML body (extracted from the message source) instead of plain text

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNo
bodyNo
isHtmlNo
subjectNo
dateSentNoISO 8601 send time from the message's Date: header (Mail's `date sent`). Absent when the message carries no parseable Date: header, or when the value is more than 7 days later than dateReceived — a send time after arrival is not a real one.
dateReceivedNoISO 8601 arrival time in the mailbox (IMAP INTERNALDATE / Mail's `date received`). A migration or re-import resets this; compare with dateSent.
rfcMessageIdNoStable RFC 5322 Message-ID (angle brackets stripped); empty when the message has none

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.19.7
    • changedOutput schema / properties / dateSent / description
      Previous value: -"ISO 8601 send time from the message's Date: header (Mail's `date sent`). Absent when the message carries no parseable Date: header."New value: +"ISO 8601 send time from the message's Date: header (Mail's `date sent`). Absent when the message carries no parseable Date: header, or when the value is more than 7 days later than dateReceived — a send time after arrival is not a real one."
  2. Changed2 schema fields changedv2.19.2
    • addedOutput schema / properties / dateReceived
      Added value: +{
+  "description": "ISO 8601 arrival time in the mailbox (IMAP INTERNALDATE / Mail's `date received`). A migration or re-import resets this; compare with dateSent.",
+  "type": "string"
+}
    • addedOutput schema / properties / dateSent
      Added value: +{
+  "description": "ISO 8601 send time from the message's Date: header (Mail's `date sent`). Absent when the message carries no parseable Date: header.",
+  "type": "string"
+}
  3. Changed2 schema fields changedv2.10.24
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  4. Changed1 schema field changedv2.10.8
    • changedOutput schema / additionalProperties
      Previous value: -falseNew value: +true
  5. Addedv2.8.14
  6. Removedv2.8.10
  7. First observedv2.6.1

TDQS

A5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral disclosure burden. It covers what the operation does (reads, does not mutate), the return fields (subject, body, rfcMessageId, dateSent, dateReceived), the meaning of the two dates, migration effects on dateReceived, and even a timeout behavior for large folders. This is rich, honest behavioral context.

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

Conciseness5/5

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

The description is structured into clear, purposeful sections: use-when, return contract, operational tip, and exclusions. Each sentence adds decision-relevant information, and the most important qualifier (id required) is front-loaded. Though a bit long, nothing is wasted.

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?

For a tool of this complexity, the description is complete: it states prerequisites, tells the agent exactly what it will receive, informs about a non-obvious migration behavior, warns about a timeout risk, and routes to siblings for related but different needs. The presence of an output schema further reduces the burden, yet the description still goes beyond it.

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 75%, but the description substantially supplements it: it clarifies the two valid id forms (numeric or imap:...), explains when preferHtml changes the body format, and explains why pairing mailbox+account is valuable beyond the schema's descriptions. It even documents the otherwise undescribed 'id' parameter.

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?

The description opens with a specific verb-resource pair ('reading the full body of one message') and clearly identifies the required prerequisite (an id you already have). It also explicitly contrasts itself with sibling tools like get-thread and get-message-headers, making the tool's purpose unambiguous.

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?

The description provides explicit 'Use when' and 'Do not use when' sections, naming concrete alternatives such as search-messages, list-messages, get-thread, and get-message-headers. It also gives a practical tip about passing mailbox and account for reliable reads of large folders, which is actionable routing guidance.

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

Deploy Server

Other Tools