Skip to main content
Glama

Read Email

read-email
Read-onlyIdempotent

Retrieve a single Outlook email by ID to view its subject, sender, recipients, date and plain-text body, or return forensic headers (DKIM, SPF, DMARC) for security analysis.

Instructions

Read a single email by id (read-only). Returns subject, from/to/cc, date and the body as plain text (HTML tags removed, so formatting and link addresses are lost): up to 2,000 characters by default, up to 40,000 with outputVerbosity: full; a cut body ends with a note on how to get the rest. With headersMode: true: returns RFC-822 forensic headers in place of the body (DKIM, SPF, DMARC, Received chain, Message-ID, Authentication-Results) — importantOnly: true for the security-relevant subset, groupByType: true for a category-bucketed view, raw: true for JSON. With includeHeaders: true (non-headers-mode): adds basic headers alongside the body. If the id came from a shared/delegated mailbox (e.g. via search-emails or access-shared-mailbox with sharedMailbox set), you MUST pass the same sharedMailbox (or alias email) here — message IDs are mailbox-scoped, and reading a shared-mailbox id without it fails with 404 ErrorInvalidMailboxItemId.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "read-email"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesID of the email to read
rawNoReturn the headers as raw JSON, not Markdown (headersMode only, default: false)
emailNoAlias for `sharedMailbox`.
groupByTypeNoGroup headers by category (headersMode only, default: false)
headersModeNoReturn forensic headers in place of the email content (default: false)
importantOnlyNoShow only important headers (headersMode only, default: false)
sharedMailboxNoEmail address of the shared/delegated mailbox the id belongs to. Required when the id was obtained from a shared mailbox — message IDs are mailbox-scoped and reading without it returns 404 ErrorInvalidMailboxItemId. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).
includeHeadersNoInclude basic headers alongside email content (default: false)
outputVerbosityNoOutput detail level (default: standard). minimal: body preview only; standard: body up to 2,000 characters; full: adds IDs, body up to 40,000 characters. For a longer body, export it with `export` target=message.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv3.14.1
    • addedInput schema / properties / email
      Added value: +{
      +  "description": "Alias for `sharedMailbox`.",
      +  "type": "string"
      +}
    • changedInput schema / properties / headersMode / description
      Previous value: -"Return forensic headers instead of email content (default: false)"New value: +"Return forensic headers in place of the email content (default: false)"
    • changedInput schema / properties / outputVerbosity / description
      Previous value: -"Output detail level (default: standard)"New value: +"Output detail level (default: standard). minimal: body preview only; standard: body up to 2,000 characters; full: adds IDs, body up to 40,000 characters. For a longer body, export it with `export` target=message."
    • changedInput schema / properties / raw / description
      Previous value: -"Return raw JSON instead of Markdown (headersMode only, default: false)"New value: +"Return the headers as raw JSON, not Markdown (headersMode only, default: false)"
    • addedInput schema / properties / sharedMailbox
      Added value: +{
      +  "description": "Email address of the shared/delegated mailbox the id belongs to. Required when the id was obtained from a shared mailbox — message IDs are mailbox-scoped and reading without it returns 404 ErrorInvalidMailboxItemId. Requires delegate access + Mail.Read.Shared. Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).",
      +  "type": "string"
      +}
  2. Changed1 schema field changedv3.7.4
    • addedInput schema / additionalProperties
      Added value: +false
  3. First observedv3.4.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds genuinely new behavior: body truncation at 2,000 chars (40,000 with full), a trailing note explaining how to retrieve the remainder, and the fact that HTML stripping loses formatting and link addresses. It also discloses a concrete failure mode (404 ErrorInvalidMailboxItemId) and its cause (mailbox-scoped IDs), which is more useful than any annotation here.

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, then progressively discloses modes, then ends on the high-risk shared-mailbox constraint in bold — a sensible ordering. It is dense and clause-heavy in the middle section, but nearly every clause carries distinct operational information, so the length is largely earned.

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 9-parameter tool with no output schema, the description fully specifies the return shape: subject, from/to/cc, date, and plain-text body, plus what headersMode substitutes. Combined with the truncation limits and the shared-mailbox prerequisite, an agent has everything needed to call it correctly and interpret the result.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3, but the description adds interaction semantics the schema states only per-parameter: it makes clear `importantOnly`, `groupByType`, and `raw` are only meaningful inside headersMode, and that `includeHeaders` applies in non-headers-mode. It also ties `outputVerbosity: full` to the 40,000-character limit rather than leaving the enum opaque.

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 a scope qualifier: 'Read a single email by id (read-only)'. That immediately separates it from the sibling `search-emails`, which is clearly a multi-result lookup, and the later mention of `export` target=message reinforces the single-message boundary.

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 conditional routing: use `headersMode: true` for forensic headers, `importantOnly`/`groupByType`/`raw` as sub-modes, `includeHeaders` for basic headers alongside the body, and `export` when the body exceeds 40,000 characters. It also states a hard prerequisite workflow — if the id came from `search-emails` or `access-shared-mailbox` with `sharedMailbox`, the same value MUST be passed here — which is exactly the when-to-use guidance an agent needs.

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