Skip to main content
Glama

Export Emails

export
Destructive

Save individual Outlook emails, message batches, conversations, or raw MIME to files, with format selection, search-based batches, and overwrite control.

Instructions

Export emails to files. target=message (default) exports one email by id (mime/eml/markdown/json/csv) to savePath: a directory (or a path ending in /, created if missing) gets a new, unique file name; a file path is created new and an existing file is replaced only with overwrite: true. target=messages batch-exports emailIds, or matches for searchQuery/query, into outputDir, at most 100 messages per call. target=conversation exports a thread (up to 1000 messages) by conversationId into outputDir (eml/mbox/markdown/json/html/csv; order: "reverse" for newest first). target=mime returns raw RFC-822 MIME for id (headersOnly, base64, maxSize, default 1MB). Files are written only inside the system temp directory (the default), ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR, never to dot-prefixed names. Pass sharedMailbox (alias email) when the ids come from a shared mailbox. includeAttachments defaults to true for one message, false for batch.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "export"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoEmail ID (target=message/mime, required)
emailNoAlias for `sharedMailbox`.
orderNoMessage order (target=conversation, default: chronological)
queryNoFree-text search shortcut (target=messages). Equivalent to passing searchQuery: { subject: <query> }. Convenience alias for callers used to search-emails.
base64NoReturn base64 encoded (target=mime)
formatNoExport format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts mime/eml/markdown/json (one file per message) or csv (one file). mime is an alias for eml (same RFC822 bytes, .eml extension on disk).
targetNoExport target (default: message)
maxSizeNoMax content size in bytes (target=mime, default: 1MB)
emailIdsNoEmail IDs to export (target=messages). At most 100 per call: any beyond the first 100 are left out, and the result says how many.
savePathNoAbsolute file path or directory, or one starting with ~/ (target=message). Relative paths are refused. Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR. An existing file is not replaced unless overwrite is true.
outputDirNoAbsolute output directory, or one starting with ~/ (target=messages, required; target=message/conversation, default: system temp directory). Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR.
overwriteNoReplace an existing file at savePath (target=message, default: false). Never replaces a symlink, a hard-linked file, a dotfile, or a file in a dot-directory below the allowed folder.
headersOnlyNoMIME headers only, no body (target=mime)
searchQueryNoSearch to find emails (target=messages, alternative to emailIds)
sharedMailboxNoEmail address of a shared/delegated mailbox to export from (default: the signed-in account). Applies to all targets (message/messages/conversation/mime) — pass it whenever the id(s)/conversationId/searchQuery belong to a shared mailbox. 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).
conversationIdNoConversation ID (target=conversation, required)
includeAttachmentsNoInclude attachments (default: true for single, false for batch)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv3.14.2
    • changedInput schema / properties / searchQuery / properties / from / description
      Previous value: -"Sender address or name to match (Graph `$search`)"New value: +"Sender to match: a full address (exact), a domain such as `example.com`, or a name or other text matched against the sender name and address"
    • changedInput schema / properties / searchQuery / properties / maxResults / description
      Previous value: -"Most messages to export (default: 25, max: 100 per call). Newest first, or by relevance when `from`/`subject` is set."New value: +"Most messages to export (default: 25, max: 100 per call), newest first."
    • changedInput schema / properties / searchQuery / properties / subject / description
      Previous value: -"Subject text to match (Graph `$search`)"New value: +"Text the subject must contain"
  2. Changed14 schema fields changedv3.14.1
    • addedInput schema / properties / email
      Added value: +{
      +  "description": "Alias for `sharedMailbox`.",
      +  "type": "string"
      +}
    • changedInput schema / properties / emailIds / description
      Previous value: -"Email IDs to export (target=messages)"New value: +"Email IDs to export (target=messages). At most 100 per call: any beyond the first 100 are left out, and the result says how many."
    • changedInput schema / properties / format / description
      Previous value: -"Export format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts markdown/json/csv. mime is an alias for eml (same RFC822 bytes, .eml extension on disk)."New value: +"Export format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts mime/eml/markdown/json (one file per message) or csv (one file). mime is an alias for eml (same RFC822 bytes, .eml extension on disk)."
    • changedInput schema / properties / outputDir / description
      Previous value: -"Output directory (target=messages/conversation, required)"New value: +"Absolute output directory, or one starting with ~/ (target=messages, required; target=message/conversation, default: system temp directory). Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR."
    • addedInput schema / properties / overwrite
      Added value: +{
      +  "description": "Replace an existing file at savePath (target=message, default: false). Never replaces a symlink, a hard-linked file, a dotfile, or a file in a dot-directory below the allowed folder.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / savePath / description
      Previous value: -"File path or directory (target=message)"New value: +"Absolute file path or directory, or one starting with ~/ (target=message). Relative paths are refused. Must be inside the system temp directory, ~/Downloads, ~/Documents or OUTLOOK_EXPORT_DIR. An existing file is not replaced unless overwrite is true."
    • changedInput schema / properties / searchQuery / description
      Previous value: -"Search query to find emails (target=messages, alternative to emailIds)"New value: +"Search to find emails (target=messages, alternative to emailIds)"
    • addedInput schema / properties / searchQuery / properties / folder / description
      Added value: +"Folder to search (default: inbox): a well-known name, display name, `Parent/Child` path or folder ID"
    • addedInput schema / properties / searchQuery / properties / from / description
      Added value: +"Sender address or name to match (Graph `$search`)"
    • addedInput schema / properties / searchQuery / properties / maxResults / description
      Added value: +"Most messages to export (default: 25, max: 100 per call). Newest first, or by relevance when `from`/`subject` is set."
    • addedInput schema / properties / searchQuery / properties / receivedAfter / description
      Added value: +"Only messages received at or after this date/time (ISO 8601)"
    • addedInput schema / properties / searchQuery / properties / receivedBefore / description
      Added value: +"Only messages received at or before this date/time (ISO 8601)"
    • addedInput schema / properties / searchQuery / properties / subject / description
      Added value: +"Subject text to match (Graph `$search`)"
    • addedInput schema / properties / sharedMailbox
      Added value: +{
      +  "description": "Email address of a shared/delegated mailbox to export from (default: the signed-in account). Applies to all targets (message/messages/conversation/mime) — pass it whenever the id(s)/conversationId/searchQuery belong to a shared mailbox. 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"
      +}
  3. Changed3 schema fields changedv3.7.4
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / format / description
      Previous value: -"Export format (target=message: mime/eml/markdown/json/csv, target=conversation: eml/mbox/markdown/json/html/csv)"New value: +"Export format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts markdown/json/csv. mime is an alias for eml (same RFC822 bytes, .eml extension on disk)."
    • addedInput schema / properties / query
      Added value: +{
      +  "description": "Free-text search shortcut (target=messages). Equivalent to passing searchQuery: { subject: <query> }. Convenience alias for callers used to search-emails.",
      +  "type": "string"
      +}
  4. First observedv3.4.1

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: writes are confined to temp/Downloads/Documents/OUTLOOK_EXPORT_DIR, a unique filename is generated for directory targets, existing files are replaced only with `overwrite: true`, dotfiles/symlinks are never replaced, and shared mailbox use requires delegate access plus the OUTLOOK_SHARED_MAILBOX server opt-in. These are exactly the side-effect and permission details an agent needs before invoking a destructive write tool.

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 before drilling into per-target behavior, and there is no filler — every clause carries a constraint. The trade-off is that it is one very dense paragraph that is harder to scan than a bulleted target breakdown, which caps it below 5.

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 17-parameter tool with a nested searchQuery object and no output schema, the description covers target selection, per-target required ids, format validity, file-path restrictions, overwrite safety, batch limits, and shared-mailbox prerequisites. Nothing an agent needs 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 already 100%, so the schema documents every parameter including nested searchQuery fields. The description mostly restates those facts (defaults, caps, format lists, path rules) rather than adding new meaning, so the baseline 3 applies; the target-to-parameter mapping it reinforces is useful but duplicative.

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 ("Export emails to files") and then enumerates the four distinct modes — single message by id, batch by emailIds/searchQuery, whole conversation, and raw MIME. The reader can immediately tell this apart from search-emails or read-email because export writes files with format and path semantics.

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?

Gives clear selection guidance between the targets: `message` for one email, `messages` for batch/search matches with a 100-message cap, `conversation` for a thread, `mime` for raw RFC-822. It also states which formats each target accepts and that `query` is a shortcut for `searchQuery`. It stops short of explicit when-not guidance (e.g. use read-email to view rather than export), so it is not quite a 5.

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