groundmail-mcp 0.14.5 → 0.15.0

package/README.md

@@ -55,7 +55,7 @@ When you connect, you choose the access: **Full**, **Send only** or **Read only*
 >
 > "How is my deliverability over the last 7 days?"
 
-Tools cover emails (send, list, look up), domains (add, apply DNS through Cloudflare, Vercel or GoDaddy, verify), templates, webhooks, suppressions, address validation, deliverability, DMARC monitoring, imports from other providers and tenants (one per customer you send for: create, update, pause, resume, stats; `tenant` on sends, domains and suppressions). Each tool carries read-only and destructive annotations and an output schema. Full list: [docs.groundmail.dev/ai/mcp](https://docs.groundmail.dev/ai/mcp).
+Tools cover emails (send, list, look up), domains (add, apply DNS through Cloudflare, Vercel or GoDaddy, verify), templates, webhooks, suppressions, address validation, deliverability, DMARC monitoring, email testing (a test address per run, then wait for the email and read its code and links), imports from other providers and tenants (one per customer you send for: create, update, pause, resume, stats; `tenant` on sends, domains and suppressions). Each tool carries read-only and destructive annotations and an output schema. Full list: [docs.groundmail.dev/ai/mcp](https://docs.groundmail.dev/ai/mcp).
 
 ## Transports
 

package/dist/index.js

@@ -559,6 +559,58 @@ var tenantStatsOutput = object(
   },
   ["tenant", "stats"]
 );
+var testInboxOutput = object(
+  {
+    test_inbox: described(
+      object(
+        {
+          object: string("Always test_inbox"),
+          domain: string("The team's test domain. Mail to any address at it is caught and never delivered"),
+          address: string("A fresh unique address on the test domain. Use a new one for each test"),
+          addon: anyObject("Email testing add-on: active (boolean) and status"),
+          usage: anyObject("This month: received, rejected, included (100 free, 5,000 with the add-on), overage, resets_at"),
+          retention_days: number("Days caught emails are kept")
+        },
+        ["domain", "address"]
+      ),
+      "The team's test inbox"
+    )
+  },
+  ["test_inbox"]
+);
+var testEmailFields = {
+  object: string("Always test_inbox_email"),
+  id: string("Test email id (tie_\u2026)"),
+  source: string("inbound (received at the test domain, from any provider) or test_key (sent with a gm_test_ key)"),
+  email_id: nullableString("With test_key: the sent email id (msg_\u2026)"),
+  from: string("Sender"),
+  to: stringArray("Recipients"),
+  cc: stringArray("Cc addresses"),
+  subject: string("Subject line"),
+  code: nullableString("The one-time code found in the email (4 to 8 digits), or null"),
+  links: stringArray("http(s) links in the email, in order"),
+  received_at: string("When it arrived (ISO 8601)"),
+  expires_at: string("When it is deleted (ISO 8601)")
+};
+var testEmailItem = object(testEmailFields, ["id", "subject"]);
+var testEmailOutput = object(
+  {
+    email: described(
+      object(
+        {
+          ...testEmailFields,
+          text_body: nullableString("Plain-text body"),
+          html_body: nullableString("HTML body"),
+          headers: arrayOf(anyObject("A header: name and value"), "Message headers in order"),
+          raw_source: nullableString("Raw message source, when available")
+        },
+        ["id", "subject"]
+      ),
+      "The test email"
+    )
+  },
+  ["email"]
+);
 
 // src/tools.ts
 function textResult(value, isError = false) {
@@ -979,6 +1031,32 @@ async function callMcpTool(client, name, args) {
         }
         return textResult(await client.migrations.get(id));
       }
+      case "get_test_inbox_address": {
+        return textResult({ test_inbox: await client.testInbox.info() });
+      }
+      case "list_test_emails": {
+        return textResult(
+          await client.testInbox.list({
+            limit: optNumber(args, "limit"),
+            cursor: optString(args, "cursor"),
+            to: optString(args, "to"),
+            since: optString(args, "since")
+          })
+        );
+      }
+      case "get_test_email": {
+        const id = optString(args, "id");
+        if (!id) return textResult("Missing required argument: id", true);
+        return textResult({ email: await client.testInbox.get(id) });
+      }
+      case "wait_for_test_email": {
+        const to = optString(args, "to");
+        if (!to) return textResult("Missing required argument: to", true);
+        const seconds = Math.min(60, Math.max(0, optNumber(args, "timeout") ?? 30));
+        return textResult({
+          email: await client.testInbox.waitFor({ to, timeout: seconds * 1e3, since: optString(args, "since") })
+        });
+      }
       default:
         return textResult(`Unknown tool: ${name}`, true);
     }
@@ -1301,7 +1379,7 @@ var MCP_TOOLS = [
     annotations: {
       title: "Add suppression",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: false
     }
@@ -1436,7 +1514,7 @@ var MCP_TOOLS = [
     annotations: {
       title: "Publish template",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: false,
       openWorldHint: false
     }
@@ -1529,7 +1607,7 @@ var MCP_TOOLS = [
     annotations: {
       title: "Update tenant",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: false
     }
@@ -1549,7 +1627,7 @@ var MCP_TOOLS = [
     annotations: {
       title: "Pause tenant",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: false
     }
@@ -1617,7 +1695,7 @@ var MCP_TOOLS = [
     annotations: {
       title: "Enable DMARC monitoring",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     }
@@ -1678,6 +1756,53 @@ var MCP_TOOLS = [
     },
     outputSchema: migrationOutput,
     annotations: readOnly("Get an import report")
+  },
+  {
+    name: "get_test_inbox_address",
+    description: "Get a fresh unique address on the team's test domain (<team>.test.groundmail.dev), plus this month's test email usage. Mail sent to it from any email provider (SendGrid, SES, Groundmail or anything else) is caught in the test inbox and never delivered. Use a new address per test, have the app send to it, then call wait_for_test_email.",
+    inputSchema: { type: "object", properties: {} },
+    outputSchema: testInboxOutput,
+    annotations: readOnly("Get a test inbox address")
+  },
+  {
+    name: "list_test_emails",
+    description: "List emails caught in the test inbox (and emails sent with a gm_test_ key), newest first, with the extracted one-time code and links. Kept 14 days.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...paginationProps,
+        to: { type: "string", description: "Only emails to this exact address" },
+        since: { type: "string", description: "Only emails received at or after this time (ISO 8601)" }
+      }
+    },
+    outputSchema: pagedOutput("emails", testEmailItem, "Caught test emails, newest first"),
+    annotations: readOnly("List test emails")
+  },
+  {
+    name: "get_test_email",
+    description: "Get one caught test email with its text and HTML bodies, headers, source, code and links.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "Test email id (tie_\u2026)" } },
+      required: ["id"]
+    },
+    outputSchema: testEmailOutput,
+    annotations: readOnly("Get test email")
+  },
+  {
+    name: "wait_for_test_email",
+    description: "Wait for an email to a test inbox address and return it, with the one-time code and links extracted. An email that already arrived is returned at once. Waits up to timeout seconds (default 30, at most 60); on timeout, check that the app sent to the exact address and call again.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        to: { type: "string", description: "The exact test address the app sent to" },
+        timeout: { type: "number", description: "Seconds to wait, at most 60 (default 30)" },
+        since: { type: "string", description: "Only emails received at or after this time (ISO 8601)" }
+      },
+      required: ["to"]
+    },
+    outputSchema: testEmailOutput,
+    annotations: readOnly("Wait for a test email")
   }
 ];
 function resolveApiKey() {
@@ -1692,7 +1817,7 @@ function resolveApiKey() {
 }
 
 // src/server.ts
-var MCP_SERVER_VERSION = "0.14.5";
+var MCP_SERVER_VERSION = "0.15.0";
 var MCP_SERVER_INSTRUCTIONS = [
   "Groundmail sends transactional email from domains the user has verified.",
   'To test before a domain is verified, call send_email with from "noreply@mail.groundmail.dev" and to set to the Groundmail account email; sandbox sends to any other address are rejected.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-mcp",
-  "version": "0.14.5",
+  "version": "0.15.0",
   "mcpName": "io.github.Groundmail/groundmail",
   "description": "Groundmail MCP server: send transactional email, manage domains, templates, webhooks and suppressions from Claude, Cursor, ChatGPT and other MCP clients",
   "license": "MIT",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "groundmail": "0.25.1"
+    "groundmail": "0.26.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",