mail-mcp-server

Overview Schema Source Related Servers Discussions Admin

getMessage

getMessage

Read-onlyIdempotent

Reads a locally stored email message, returning headers, a Markdown body chunk, and its attachment list; use the next offset to continue retrieving body text.

Instructions

Read one locally stored message: headers, a body chunk as Markdown, and an attachment list. nextOffset continues only the body; headers and the attachment list are returned on each call. If body is absent, saved body text is unavailable; inspect state and error rather than assuming the original message was empty.

To read an attachment, call getAttachment with the same connection and key, and file=attachments[].file. Use file, not name or path. The list includes files extracted from attached archives and messages; parent is the containing attachment's file. For the conversation, call getThread with the same connection and key.

Input Schema

Name	Required	Description
`key`	Yes	Local message key from listMessages, search or getThread in this connection; use key, not the Message-ID header
`offset`	No	Body character offset, default 0. To continue, keep the same connection and key and use nextOffset from this tool. Stop when there is no nextOffset
`maxChars`	No	Body characters per chunk: 1 to 100000, default 20000; larger values are capped at 100000
`connection`	Yes	Connection name from listConnections

Output Schema

Name	Required	Description
`cc`	No	Cc recipients as Name <address>.
`to`	No	To recipients as Name <address>.
`key`	Yes	Message key.
`body`	No	Chunk of the saved body as Markdown; [redacted:<kind>] marks a hidden secret. Absent when saved body text is unavailable; this does not prove the original body was empty.
`date`	No	Date from the message header; absent when missing.
`from`	No	Senders as Name <address>.
`read`	No	Read in the mailbox as of the last sync; absent when unknown.
`error`	No	Why the message failed; present when state is failed.
`state`	Yes	converted (complete), downloaded (saved, text not processed yet) or failed (see error).
`folder`	Yes	Folder path in the mailbox; not the folder key used by listMessages/search.
`labels`	No	Mailbox labels of this message as of the last sync, such as Gmail's Inbox, Sent or user labels; empty when it has none. Absent when unknown or when the mailbox has no labels.
`offset`	Yes	Character position of this chunk.
`flagged`	No	Flagged or starred in the mailbox as of the last sync (not sender importance); absent when unknown.
`subject`	No	Subject.
`inReplyTo`	No	In-Reply-To header.
`localPath`	Yes	Absolute message directory, readable directly: message.eml (original), body.md, attachments/.
`messageId`	No	Message-ID header.
`bodyLength`	Yes	Length of the whole body in characters; 0 without a body.
`nextOffset`	No	Pass as offset to get the next chunk; absent at the end.
`references`	No	References header message IDs.
`attachments`	Yes	Attachments, including files unpacked from attached archives and messages. Empty when none are found or the saved MIME cannot be read. Pass an entry's file to getAttachment with this message's key and connection.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds behavior the annotations can't: pagination continues only the body while headers and the attachment list are re-returned each call, and an absent body means saved body text is unavailable rather than the original being empty. That last point is a genuine anti-misinterpretation warning.

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 tight paragraphs with the return shape front-loaded and the escape hatches second. Minor redundancy with the offset/nextOffset schema text, but nothing is padding.

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?

Output schema exists so return values need no prose, and the description still covers the edge cases an agent would otherwise get wrong: body-only pagination, empty-body interpretation, archive-extracted attachments and the parent field. Nothing needed to call it correctly is missing.

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%, so key, offset, maxChars and connection are already documented, including the nextOffset continuation rule. The description restates that rule and adds only the `file` vs `name`/`path` disambiguation, which applies to the sibling tool rather than this one's parameters.

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?

Opens with a specific verb and resource plus the exact payload ('headers, a body chunk as Markdown, and an attachment list'), which no sibling tool claims. It also implicitly separates itself from getThread and getAttachment by naming them for those respective jobs.

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?

Explicitly routes adjacent needs: attachments go to getAttachment with the same connection/key and file=attachments[].file, the conversation goes to getThread. It also gives the continuation rule (keep connection and key, follow nextOffset, stop when absent), so an agent knows when to call again versus call elsewhere.

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

Deploy Server