apple-mail-mcp

Overview Schema Source Related Servers Discussions Admin

send-serial-email

Sends personalized mail-merge emails individually to up to 100 recipients, replacing {{Key}} placeholders per recipient and returning a sent/failed report.

Instructions

Use when: the user has confirmed a mail-merge — sending individually personalized copies to many recipients (max 100), with {{Key}} placeholders in subject/body replaced per-recipient from each recipient's variables. Recipients do not see each other. Returns: a per-recipient sent/failed report with counts. Do not use when: sending one message to a shared recipient list (use send-email) or saving for review (use create-draft). Safety: this SENDS many real emails immediately and they cannot be unsent — require explicit user confirmation of the recipient list, the subject/body template, and the placeholder substitutions before calling.

Input Schema

Name	Required	Description
`body`	Yes	Email body — use {{Key}} for placeholders
`account`	No	Account to send from. AppleScript transport: a Mail account name or an exact sender address, resolved to one address and verified before sending; if it matches no enabled account, or Mail would use a different sender, nothing is sent and an error is returned. Omitted → Mail's default sender (reported back in `from`). SMTP transport: an email-form From override (see README).
`delayMs`	No	Delay between sends in ms (default: 500, max: 10000)
`subject`	Yes	Subject line — use {{Key}} for placeholders
`transport`	No	Send transport for the whole batch. 'smtp' sends clean MIME without Mail.app quote wrapping and requires matching SMTP configuration; errors never fall back to AppleScript. SMTP accepts an allowed sender email address in account, not a Mail.app account label. 'applescript' explicitly uses Mail.app. If omitted, configured SMTP is used unless account is a Mail.app account label.
`recipients`	Yes	List of recipients with personalization variables (max 100)

Output Schema

Name	Required	Description
`ok`	No
`sent`	No
`failed`	No
`partial`	No
`results`	No
`unknown`	No	Submissions with an unknown outcome, excluded from sent and failed counts.
`transport`	No	Transport used for this batch
`deliveryUnknown`	No	SMTP returned no definitive submission result. Verify before retrying.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv2.20.52Nov 3, 2026

addedOutput schema / properties / deliveryUnknown

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

addedOutput schema / properties / partial
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / results / items / properties / accepted

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

addedOutput schema / properties / results / items / properties / deliveryUnknown

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

addedOutput schema / properties / results / items / properties / partial

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

addedOutput schema / properties / results / items / properties / rejected

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

addedOutput schema / properties / unknown

Added value: +{
+  "description": "Submissions with an unknown outcome, excluded from sent and failed counts.",
+  "type": "number"
+}

Changed2 schema fields changedv2.20.31Oct 25, 2026

addedInput schema / properties / transport

Added value: +{
+  "description": "Send transport for the whole batch. 'smtp' sends clean MIME without Mail.app quote wrapping and requires matching SMTP configuration; errors never fall back to AppleScript. SMTP accepts an allowed sender email address in account, not a Mail.app account label. 'applescript' explicitly uses Mail.app. If omitted, configured SMTP is used unless account is a Mail.app account label.",
+  "enum": [
+    "applescript",
+    "smtp"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / transport

Added value: +{
+  "description": "Transport used for this batch",
+  "enum": [
+    "smtp",
+    "applescript"
+  ],
+  "type": "string"
+}

Changed1 schema field changedv2.20.29Oct 24, 2026
- addedInput schema / properties / recipients / items / properties / variables / propertyNames
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedv2.20.16Oct 18, 2026

changedInput schema / properties / account / description

Previous value: -"Account to send from"New value: +"Account to send from. AppleScript transport: a Mail account name or an exact sender address, resolved to one address and verified before sending; if it matches no enabled account, or Mail would use a different sender, nothing is sent and an error is returned. Omitted → Mail's default sender (reported back in `from`). SMTP transport: an email-form From override (see README)."

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.9/5.0

Behavior5/5

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

With no annotations supplied, the description fully discloses the critical behavior: many real emails are sent immediately, they cannot be unsent, and explicit user confirmation is required. It also explains recipient privacy and per-recipient sent/failed reporting, which help the agent anticipate partial failures and communicate outcomes accurately.

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 labeled sections for usage, return behavior, exclusions, and safety make a dense description easy to scan. It front-loads selection guidance and the irreversible-sending warning, with no redundant or decorative wording.

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, high-impact bulk-send tool, the definition covers selection, alternatives, personalization behavior, scale, privacy, confirmation prerequisites, irreversibility, and outcome reporting. The rich input and output schemas supply the remaining invocation and response details, leaving no material gap for correct tool use.

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 already 100%, but the description adds useful relational semantics by explaining that each recipient's variables replace {{Key}} placeholders in both subject and body for that recipient's individual copy. Transport, account, and delay details remain in the schema, which is appropriate, though the description itself adds little about those parameters.

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 precisely defines a confirmed mail-merge: sending individually personalized copies to many recipients, with per-recipient {{Key}} substitution and a maximum of 100 recipients. It also distinguishes the privacy behavior—recipients do not see each other—and clearly separates this operation from ordinary sending and drafting.

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 gives an explicit 'Use when' condition and two 'Do not use when' cases with named alternatives: send-email for one message to a shared list and create-draft for saving reviewable content. Requiring confirmation of the recipient list, template, and substitutions provides an additional concrete invocation gate.

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

Deploy Server