apple-mail-mcp

Overview Schema Source Related Servers Discussions Admin

reply-to-message

Reply to an existing email by ID while preserving threading and quoting the original; optionally reply to all, attach files, or save as a draft for review before sending.

Instructions

Use when: replying to an existing message by id, preserving its threading headers and quoting the original, optionally with attachments (same rules as send-email). Set replyAll for all recipients; set send=false to save as a draft instead of sending. Returns: a confirmation that the reply was sent or saved as a draft, with the attachment count; over SMTP, also whether a Sent-folder copy was filed (sentCopy). Do not use when: composing a brand-new message (use send-email / create-draft) or forwarding to new recipients (use forward-message). Safety: with the default send=true this SENDS real email immediately and cannot be unsent — require explicit user confirmation of the recipients and body, or pass send=false to let the user review.

Input Schema

Name	Required	Description
`id`	Yes
`body`	Yes	Reply body (plain text; HTML tags such as <br> are not rendered)
`send`	No	Send immediately (false = save as draft)
`account`	No	For a numeric id, the account it was listed from; pair with mailbox. Omit for an imap: id.
`mailbox`	No	For a numeric id, the exact source mailbox path; pair with account. A miss never searches elsewhere.
`replyAll`	No	Reply to all recipients
`transport`	No	SMTP sends clean MIME and preserves reply threading; requires SMTP configuration. AppleScript uses Mail.app and may quote-wrap the new body on macOS 15+. Omit to prefer configured SMTP when sending; drafts use AppleScript. A selected SMTP transport never silently falls back. SMTP with send=false is rejected.
`attachments`	No	Files to attach: absolute paths in the configured attachment read roots (e.g. '/Users/me/Documents/report.pdf') and/or inline {filename, contentBase64} objects up to 25 MiB decoded each.
`composition`	No	Opt in to Mail's visible native editor: inserts only new prose, preserving its signature, HTML quotation and reply ancestry without the AppleScript content setter. Requires an unlocked desktop and existing Accessibility and Automation permissions. Uses Mail.app even when SMTP is configured; cannot be combined with transport=smtp or caller-built threading headers. New messages require an explicit account. Do not interact with Mail or the clipboard while it runs. Failure never falls back to another composition method or sends an unverified message.

Output Schema

Name	Required	Description
`id`	No
`ok`	No
`sent`	No
`partial`	No	SMTP accepted some recipients and rejected others; do not resend to accepted recipients.
`accepted`	No	Recipients accepted by the SMTP server, not final inbox delivery.
`rejected`	No	Recipients rejected by the SMTP server.
`sentCopy`	No	SMTP only: whether a best-effort copy was filed to the account's Sent mailbox over IMAP (issue #220). Absent when no configured IMAP account matches the SMTP identity — not a failure, the feature simply wasn't engaged.
`messageId`	No
`transport`	No
`sentCopyError`	No	Present only when sentCopy is false: why the Sent-folder copy failed.
`attachmentCount`	No
`deliveryUnknown`	No	SMTP returned no definitive submission result. Verify before retrying.
`sentCopyAlreadyFiled`	No	Present (true) only when sentCopy is true because the Sent mailbox already held this Message-ID (e.g. Gmail's SMTP files its own copy), so none was appended.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv2.20.52Nov 3, 2026

addedOutput schema / properties / accepted

Added value: +{
+  "description": "Recipients accepted by the SMTP server, not final inbox delivery.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / deliveryUnknown

Added value: +{
+  "description": "SMTP returned no definitive submission result. Verify before retrying.",
+  "type": "boolean"
+}

addedOutput schema / properties / partial

Added value: +{
+  "description": "SMTP accepted some recipients and rejected others; do not resend to accepted recipients.",
+  "type": "boolean"
+}

addedOutput schema / properties / rejected

Added value: +{
+  "description": "Recipients rejected by the SMTP server.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed2 schema fields changedv2.20.45Oct 30, 2026

addedInput schema / properties / account

Added value: +{
+  "description": "For a numeric id, the account it was listed from; pair with mailbox. Omit for an imap: id.",
+  "type": "string"
+}

addedInput schema / properties / mailbox

Added value: +{
+  "description": "For a numeric id, the exact source mailbox path; pair with account. A miss never searches elsewhere.",
+  "type": "string"
+}

Changed1 schema field changedv2.20.39Oct 28, 2026

addedInput schema / properties / composition

Added value: +{
+  "const": "native-editor",
+  "description": "Opt in to Mail's visible native editor: inserts only new prose, preserving its signature, HTML quotation and reply ancestry without the AppleScript content setter. Requires an unlocked desktop and existing Accessibility and Automation permissions. Uses Mail.app even when SMTP is configured; cannot be combined with transport=smtp or caller-built threading headers. New messages require an explicit account. Do not interact with Mail or the clipboard while it runs. Failure never falls back to another composition method or sends an unverified message.",
+  "type": "string"
+}

Changed1 schema field changedv2.20.29Oct 24, 2026

addedOutput schema / properties / sentCopyAlreadyFiled

Added value: +{
+  "description": "Present (true) only when sentCopy is true because the Sent mailbox already held this Message-ID (e.g. Gmail's SMTP files its own copy), so none was appended.",
+  "type": "boolean"
+}

Changed2 schema fields changedv2.20.11Oct 14, 2026

addedInput schema / properties / attachments

Added value: +{
+  "description": "Files to attach: absolute paths in the configured attachment read roots (e.g. '/Users/me/Documents/report.pdf') and/or inline {filename, contentBase64} objects up to 25 MiB decoded each.",
+  "items": {
+    "anyOf": [
+      {
+        "description": "Absolute path to an existing file in an allowed read root",
+        "type": "string"
+      },
+      {
+        "additionalProperties": false,
+        "properties": {
+          "contentBase64": {
+            "description": "Base64-encoded file content (maximum 25 MiB decoded)",
+            "maxLength": 69905072,
+            "minLength": 1,
+            "type": "string"
+          },
+          "filename": {
+            "description": "Filename to give the attachment",
+            "maxLength": 255,
+            "minLength": 1,
+            "type": "string"
+          }
+        },
+        "required": [
+          "filename",
+          "contentBase64"
+        ],
+        "type": "object"
+      }
+    ]
+  },
+  "maxItems": 20,
+  "type": "array"
+}

addedOutput schema / properties / attachmentCount
```
Added value: +{
+  "type": "number"
+}
```

Changed1 schema field changedv2.19.12Sep 22, 2026
- addedInput schema / properties / body / description
```
Added value: +"Reply body (plain text; HTML tags such as <br> are not rendered)"
```

Changed2 schema fields changedv2.18.0Sep 10, 2026

addedOutput schema / properties / sentCopy

Added value: +{
+  "description": "SMTP only: whether a best-effort copy was filed to the account's Sent mailbox over IMAP (issue #220). Absent when no configured IMAP account matches the SMTP identity — not a failure, the feature simply wasn't engaged.",
+  "type": "boolean"
+}

addedOutput schema / properties / sentCopyError

Added value: +{
+  "description": "Present only when sentCopy is false: why the Sent-folder copy failed.",
+  "type": "string"
+}

Changed3 schema fields changedv2.17.8Sep 5, 2026

addedInput schema / properties / transport

Added value: +{
+  "description": "SMTP sends clean MIME and preserves reply threading; requires SMTP configuration. AppleScript uses Mail.app and may quote-wrap the new body on macOS 15+. Omit to prefer configured SMTP when sending; drafts use AppleScript. A selected SMTP transport never silently falls back. SMTP with send=false is rejected.",
+  "enum": [
+    "applescript",
+    "smtp"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / messageId
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / transport

Added value: +{
+  "enum": [
+    "smtp",
+    "applescript"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedv2.10.24Aug 14, 2026

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"

Changed1 schema field changedv2.10.8Aug 7, 2026
- changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```
Addedv2.8.14Jul 22, 2026
Removedv2.8.10Jul 18, 2026
First observedv2.6.1Jun 29, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries the safety burden well: default send=true immediately sends real, irreversible email and requires explicit confirmation of recipients and body, while send=false permits review as a draft. It also discloses threading and quoting behavior, sent-versus-draft confirmation, attachment counts, and the SMTP-specific sentCopy result.

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?

Four compact, labeled segments front-load the use case, then cover results, exclusions, and the critical safety warning. There is essentially no filler, and the brief return-value note earns its place by identifying the transport-specific sentCopy detail.

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 nine-parameter tool, the rich input and output schemas cover detailed transport, attachment, composition, and return mechanics, while the description supplies the selection criteria and operational risks. Together they give an agent enough context to choose the correct sibling and avoid an accidental irreversible send.

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 89%, so the schema already documents nearly all parameters and constraints. The description adds useful context that id identifies the message being answered and that send=false supports a review workflow, but replyAll and send largely restate the schema, while 'same rules as send-email' supplies no attachment rules itself.

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 opening line specifies replying to an existing message by id, preserving threading, quoting the original, and optionally attaching files. The exclusions clearly distinguish it from send-email, create-draft, and forward-message.

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?

It provides explicit 'Use when' and 'Do not use when' conditions with named alternatives for new compositions and forwarding. It also explains when to use replyAll and when send=false is preferable for draft review.

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

Deploy Server