Fetch a mail thread
mail_fetch_threadFetch an entire email reply chain in one call, folding repeated quoted text into markers so you can summarize threads, find decisions, and reconstruct who asked what.
Instructions
Reads a whole reply chain in one call and folds away the text the messages repeat at each other. Use it instead of looping mail_get_message whenever you want two or more messages of one conversation — summarising a thread, finding when something was decided, reconstructing who asked what. Pass fromMessageId (any message id from the thread, and the server finds the rest) or ids (an explicit list, which also works across conversations). Messages come back oldest-first as messages, each with an n you can cite. Where a message quotes text an earlier one already carried, the quote is replaced by a marker like [quoted from #3] or [quoted from #2-#5]; every index named is a message in this same response and always lower than the one citing it, so nothing points outside what you were given. On a measured 24-message Outlook thread this returned 92,000 characters where 24 separate mail_get_message calls returned 381,000, with no unique sentence lost. Read meta.fold to see how much was folded and meta.budget to see whether bodies were cut. reason is "complete" when you have the whole conversation, "maxMessages" when only the newest maxMessages of a longer thread came back, and "maxPages" when the conversation is longer than this tool will page — there is no cursor, because a pointer on page 2 could not name a message on page 1, so narrow with mail_search_messages and pass ids instead. A message tagged bodyRendering:"stripped-html" reached us as HTML and lost every link on the way through the tag stripper; linksLost counts them. Nothing here is marked read, and attachment contents are never included.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Explicit message ids, 1-50, fetched in one $batch. Use this to fold across messages that are NOT one conversation — notification mail from one service shares a footer but not a conversationId. Order does not matter: the result is always sorted oldest-first before folding, so the same ids in any order return the same bytes. Ids that fail are listed in meta.missing rather than failing the call. | |
| fold | No | How to handle text that repeats across the returned messages. "pointers" (the default) replaces a repeat with a marker naming the message that carried it first, such as [quoted from #3]. "off" returns every message whole and is typically four times larger; use it only if you must read a quoted copy verbatim. | pointers |
| foldLinks | No | As in mail_get_message: replace click-tracking URLs over 200 characters. | |
| maxMessages | No | fromMessageId mode only. How many messages of the conversation to return, newest-first from the mailbox and then re-sorted oldest-first. Defaults to 20. There is no cursor: a pointer in page 2 could not name a message in page 1, so a longer thread is reported with reason:"maxMessages" and narrowed with ids instead. | |
| maxBodyChars | No | Optional hard ceiling on any single message body, applied AFTER folding. There is no default on purpose: the one message in a chain that matters is often the long one, and a per-message cap cuts exactly that. Leave it unset and let totalBodyChars bind, which shares the budget fairly instead of clipping every message to the same length. | |
| fromMessageId | No | Any message id from the thread you want — typically one a search returned. The server reads its conversationId and fetches the rest, so you never have to hold a conversationId yourself. Pass this OR ids, not both. | |
| totalBodyChars | No | Ceiling on all bodies in this response together, default 30000 and clamped to the server's own output cap. This is the limit that actually binds — raise it, not maxBodyChars, when you want more text. Budget is shared fairly: a short message is never truncated to make room for a long one. |