Groundmail

Send email

send_email

Send a transactional email via Groundmail. Provide subject + html/text, or a published template_id / template_alias with optional variables. To test without delivering anything, send to a simulator address: delivered@, bounce@, block@, complaint@, suppressed@ or delayed@simulator.groundmail.dev (plus addressing like bounce+test1@ works); the result has test: true and webhooks fire as for real mail. Do not put payment card numbers, government ID numbers, health information or passwords in the content.

Input Schema

Name	Required	Description
`to`	Yes	Recipient email address. A …@simulator.groundmail.dev address simulates an outcome and never delivers
`from`	No	Sender address (on a verified domain, or the sandbox sender). Optional when sender is set, the template has a sender, or the team has a default sender (list_senders); when set it wins
`html`	No	HTML body. Do not combine with template_id or template_alias
`text`	No	Plain-text body. Do not combine with template_id or template_alias
`sender`	No	A saved sender's handle or id from list_senders (for example billing): sends as its name and address, and replies go to its reply-to unless reply_to is set. Ignored when from is set
`tenant`	No	Send as this tenant: the send uses its domains, suppression list, pause switch and daily limit. Omit to send from the account as a whole. The tenant's external id (your id for that customer) or its Groundmail id
`subject`	No	Subject line. Optional when using a published template
`category`	No	transactional (default): sign-in codes, receipts, alerts. product: onboarding, lifecycle and notification email, with one-click unsubscribe. newsletter: opt-in newsletters, for approved accounts only (otherwise the send fails with newsletter_not_enabled), sent from separate IPs with one-click unsubscribe
`reply_to`	No	Address that replies should go to
`variables`	No	Template variables when using template_id or template_alias
`template_id`	No	Published template UUID
`template_alias`	No	Published template alias

Output Schema

Name	Required	Description
`id`	Yes	Email id (msg_…)
`test`	No	Present and true on a test send (test key or simulator addresses): nothing was delivered
`status`	Yes	Status after the request, for example queued or scheduled
`held_back`	No	Present when Groundmail validation held some recipients back; the email went to the rest

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 4, 2026

changedOutput schema / properties / held_back / items / properties / reason / description

Previous value: -"Why: invalid_address (cannot exist), no_mail_server (domain takes no email), previously_bounced (hard-bounced for a Groundmail sender in the last 90 days) or mailbox_not_found"New value: +"Why: invalid_address (cannot exist), no_mail_server (domain takes no email), previously_bounced (hard-bounced for a Groundmail sender in the last 90 days), mailbox_not_found, or likely_bot_signup (looks like a bot sign-up; only when the send opted in)"

Changed3 schema fields changedNov 2, 2026

changedInput schema / properties / from / description

Previous value: -"Sender address (must match a verified domain or sandbox sender)"New value: +"Sender address (on a verified domain, or the sandbox sender). Optional when sender is set, the template has a sender, or the team has a default sender (list_senders); when set it wins"

addedInput schema / properties / sender

Added value: +{
+  "description": "A saved sender's handle or id from list_senders (for example billing): sends as its name and address, and replies go to its reply-to unless reply_to is set. Ignored when from is set",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "from",
-  "to"
-]New value: +[
+  "to"
+]

Changed1 schema field changedOct 19, 2026

addedInput schema / properties / category

Added value: +{
+  "description": "transactional (default): sign-in codes, receipts, alerts. product: onboarding, lifecycle and notification email, with one-click unsubscribe. newsletter: opt-in newsletters, for approved accounts only (otherwise the send fails with newsletter_not_enabled), sent from separate IPs with one-click unsubscribe",
+  "enum": [
+    "transactional",
+    "product",
+    "newsletter"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 18, 2026

addedInput schema / properties / tenant

Added value: +{
+  "description": "Send as this tenant: the send uses its domains, suppression list, pause switch and daily limit. Omit to send from the account as a whole. The tenant's external id (your id for that customer) or its Groundmail id",
+  "type": "string"
+}

Changed2 schema fields changedOct 18, 2026

changedInput schema / properties / to / description

Previous value: -"Recipient email address"New value: +"Recipient email address. A …@simulator.groundmail.dev address simulates an outcome and never delivers"

addedOutput schema / properties / test

Added value: +{
+  "description": "Present and true on a test send (test key or simulator addresses): nothing was delivered",
+  "type": "boolean"
+}

Changed1 schema field changedOct 18, 2026

addedOutput schema / properties / held_back

Added value: +{
+  "description": "Present when Groundmail validation held some recipients back; the email went to the rest",
+  "items": {
+    "properties": {
+      "email": {
+        "description": "The held-back address",
+        "type": "string"
+      },
+      "reason": {
+        "description": "Why: invalid_address (cannot exist), no_mail_server (domain takes no email), previously_bounced (hard-bounced for a Groundmail sender in the last 90 days) or mailbox_not_found",
+        "type": "string"
+      }
+    },
+    "required": [
+      "email",
+      "reason"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

First observedOct 16, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With annotations only covering the generic safety profile (non-read-only, non-idempotent, open-world), the description adds substantial behavior: simulator sends return test: true yet still fire webhooks, category-level consequences (newsletter fails with newsletter_not_enabled for unapproved accounts and sends from separate IPs), and a PII prohibition on content. That is real operational context an agent cannot infer from the annotations.

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-loads the action, then testing, then compliance, in three sentences with no filler. The simulator address enumeration is a dense clause but each token is functionally necessary for choosing an outcome.

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 12-parameter mutation tool with an output schema and full annotation coverage, the description supplies the non-obvious parts an agent needs: content-mode exclusivity, test delivery semantics, tenant scoping effects, and data-handling restrictions, leaving return shape to the output schema.

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 100%, so baseline is 3; the description still adds meaning by explaining the from/sender/template-default precedence chain and the simulator-address trick with plus addressing, and by framing variables as template-only. It largely mirrors the schema's own wording on precedence rather than extending it much further.

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?

States a specific verb and resource ('Send a transactional email via Groundmail') and immediately enumerates the two content modes (subject + html/text vs. published template_id/template_alias with variables), which lets an agent distinguish it from template-management siblings like create_template or publish_template.

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 concrete guidance for the testing scenario: use a simulator address from a listed set instead of sending real mail, and notes plus-addressing works. Missing is an explicit 'when not to use' or routing to siblings (e.g., validate_email before sending, list_senders for sender resolution), so it is clear but not fully alternative-aware.

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

All Groundmail tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?