apple-mail-mcp

Overview Schema Source Related Servers Discussions Admin

send-email

Send a single email now to specified recipients, with optional attachments and a chosen transport. Requires explicit user confirmation before sending.

Instructions

Use when: the user has explicitly confirmed they want to send a single email now to the given recipients (to/cc/bcc are arrays), optionally with attachments and a chosen transport. Returns: a confirmation naming the recipients and attachment count; over SMTP, also whether a Sent-folder copy was filed (sentCopy). Do not use when: the user wants to review first (use create-draft), is replying to or forwarding an existing message (use reply-to-message / forward-message), or wants per-recipient personalized copies (use send-serial-email). Safety: this SENDS real email immediately and it cannot be unsent — require explicit user confirmation of the exact recipients, subject, and body before calling. Prefer create-draft when there is any doubt.

Input Schema

TableJSON Schema

Name	Required	Description
`cc`	No	CC recipients
`to`	Yes
`bcc`	No	BCC recipients
`body`	Yes
`account`	No	Account to send from
`replyTo`	No	SMTP only (issue #220): sets the Reply-To header when replies should go somewhere other than the From/login address, e.g. a domain-alias setup where APPLE_MAIL_MCP_SMTP_FROM differs from APPLE_MAIL_MCP_SMTP_USER. Ignored on the AppleScript transport.
`subject`	Yes
`transport`	No	Send transport. 'smtp' submits clean MIME directly via SMTP, avoiding the macOS 15+ Mail.app <blockquote> wrapping (issue #12); requires APPLE_MAIL_MCP_SMTP_* env config. 'applescript' sends through Mail.app. If omitted, SMTP is used automatically when APPLE_MAIL_MCP_SMTP_* is configured, otherwise AppleScript.
`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.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	No
`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.
`transport`	No
`recipients`	No
`sentCopyError`	No	Present only when sentCopy is false: why the Sent-folder copy failed.
`attachmentCount`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.18.0Sep 10, 2026

addedInput schema / properties / replyTo

Added value: +{
+  "description": "SMTP only (issue #220): sets the Reply-To header when replies should go somewhere other than the From/login address, e.g. a domain-alias setup where APPLE_MAIL_MCP_SMTP_FROM differs from APPLE_MAIL_MCP_SMTP_USER. Ignored on the AppleScript transport.",
+  "type": "string"
+}

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"
+}

Changed2 schema fields changedv2.16.1Aug 19, 2026

changedInput schema / properties / attachments / description

Previous value: -"Files to attach: absolute paths (e.g. '/Users/me/report.pdf') and/or inline {filename, contentBase64} objects up to 25 MiB decoded each."New value: +"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."

changedInput schema / properties / attachments / items / anyOf

Previous value: -[
-  {
-    "description": "Absolute path to an existing file",
-    "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"
-  }
-]New value: +[
+  {
+    "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"
+  }
+]

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 provided, the description carries the full burden of behavioral disclosure. It clearly states that this tool sends real email immediately, is irreversible, and requires explicit user confirmation, which is essential safety-critical information. It also discloses what the return value contains, including transport-specific behavior for SMTP Sent-folder copies.

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?

The description is organized into clear labeled sections (when to use, return value, when not to use, safety) and front-loads the most important operational facts first. Every sentence adds distinct value, and the length is justified by the irreversible nature of the operation.

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 complex 9-parameter mutation tool with no annotations, the description covers what the tool does, when to use it, what not to use it for, safety requirements, and the expected return value. The schema and output schema handle the remaining structural details, so nothing critical is missing for correct invocation.

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?

The schema already provides rich descriptions for most parameters (transport, replyTo, attachments, cc, bcc, account), and the description adds only lightweight confirmation that recipients are arrays and that attachments/transport are optional. It does not meaningfully document the required parameters (to, subject, body) beyond emphasizing that the user must explicitly confirm them, so baseline scoring is appropriate given 67% schema coverage.

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 description states the exact action ('send a single email now') and clearly identifies the resource: recipients, attachments, and transport. It is strongly differentiated from siblings by naming what it is not (create-draft, reply-to-message, forward-message, send-serial-email), so an agent can distinguish it without opening the schema.

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?

The description provides both explicit when-to-use conditions and explicit when-not-to-use conditions with named alternatives. It instructs the agent to require explicit user confirmation and to prefer create-draft if there is any doubt, leaving no ambiguity about the decision boundary.

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

Deploy Server