groundmail-mcp 0.6.4 → 0.8.0

package/dist/index.js

@@ -118,6 +118,17 @@ function pagedOutput(key, item, description) {
     [key]
   );
 }
+function heldBackItem() {
+  return object(
+    {
+      email: string("The held-back address"),
+      reason: string(
+        "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"
+      )
+    },
+    ["email", "reason"]
+  );
+}
 var emailItem = object(
   {
     id: string("Email id (msg_\u2026)"),
@@ -135,6 +146,10 @@ var emailItem = object(
       enum: ["hard", "block", null],
       description: "Why it bounced: hard (address cannot receive; suppressed) or block (the receiving server refused the sender for reputation or policy; address not suppressed, safe to retry later). Null if it did not bounce"
     },
+    held_back: arrayOf(
+      heldBackItem(),
+      "Recipients Groundmail validation held back before sending, with why; empty when none were"
+    ),
     tags: { description: "Tags attached to the email" },
     scheduled_at: nullableString("When the email is scheduled to send (ISO 8601)"),
     cancelled_at: nullableString("When the scheduled email was cancelled (ISO 8601)"),
@@ -248,10 +263,32 @@ var bucketProperties = {
 var sendEmailOutput = object(
   {
     id: string("Email id (msg_\u2026)"),
-    status: string("Status after the request, for example queued or scheduled")
+    status: string("Status after the request, for example queued or scheduled"),
+    held_back: arrayOf(
+      heldBackItem(),
+      "Present when Groundmail validation held some recipients back; the email went to the rest"
+    )
   },
   ["id", "status"]
 );
+var validateEmailOutput = object(
+  {
+    email: string("The address as checked (trimmed, lowercased)"),
+    domain: nullableString("Domain part of the address; null when there is none"),
+    verdict: {
+      type: "string",
+      enum: ["valid", "risky", "invalid"],
+      description: "valid: safe to send; risky: deliverable but worth a second look; invalid: cannot receive email"
+    },
+    reasons: stringArray(
+      "What was found: syntax, no_mail_server, mailbox_not_found, previously_bounced (invalid); disposable, catch_all, possible_typo (risky); role (informational)"
+    ),
+    suggestion: nullableString("The address with a likely-mistyped domain corrected, for example ada@gmail.com for ada@gmial.com"),
+    disposable: boolean("A throwaway-inbox service"),
+    role: boolean("A team or queue mailbox such as info@ or support@")
+  },
+  ["email", "verdict", "reasons", "suggestion", "disposable", "role"]
+);
 var getEmailOutput = object({ email: described(emailItem, "The email") }, ["email"]);
 var domainWithRecordsOutput = object(
   {
@@ -366,10 +403,14 @@ var migrationOutput = object(
           has_more: boolean("True if the import stopped early; call the tool again with `cursor` to continue"),
           next_cursor: nullableString("Pass as `cursor` to continue an import that stopped early"),
           retry_after_seconds: { type: ["number", "null"], description: "Wait this long before continuing" },
-          domains: anyObject("Totals and one item per domain, with the DNS records to publish"),
+          domains: anyObject(
+            "Totals and one item per domain, with the DNS records and `dns_plan`: each record compared with what the domain publishes today (add, update an existing SPF record, keep the existing DMARC record, or already published), and which old-provider records to keep until the cutover"
+          ),
           webhooks: anyObject("Totals and one item per webhook (created disabled), with mapped events and the signing secret"),
           templates: anyObject("Totals and one item per template, with its alias and conversion notes"),
-          suppressions: anyObject("Totals by type (bounce, complaint, unsubscribe, manual) and skip reasons"),
+          suppressions: anyObject(
+            "Totals by type (bounce, complaint, unsubscribe, manual, product_opt_out) and skip reasons (for example bounces caused by a block on the old provider, which are not suppressed)"
+          ),
           errors: arrayOf(anyObject("A resource that could not be read"), "Resources that could not be read at all"),
           notes: stringArray("What was left out on purpose, and why"),
           attention: stringArray("What the user still needs to do"),
@@ -544,6 +585,11 @@ async function callMcpTool(client, name, args) {
           })
         );
       }
+      case "validate_email": {
+        const email = optString(args, "email");
+        if (!email) return textResult("Missing required argument: email", true);
+        return textResult(await client.validate(email));
+      }
       case "add_suppression": {
         const email = optString(args, "email");
         if (!email) return textResult("Missing required argument: email", true);
@@ -640,6 +686,15 @@ async function callMcpTool(client, name, args) {
         };
         return textResult({ migration: await client.migrations.run(params) });
       }
+      case "get_import_report": {
+        let id = optString(args, "id");
+        if (!id) {
+          const { data } = await client.migrations.list({ limit: 1 });
+          if (!data[0]) return textResult("No imports yet. Run import_from_provider first; previews are not stored.", true);
+          id = data[0].id;
+        }
+        return textResult(await client.migrations.get(id));
+      }
       default:
         return textResult(`Unknown tool: ${name}`, true);
     }
@@ -886,6 +941,19 @@ var MCP_TOOLS = [
     outputSchema: pagedOutput("data", suppressionItem, "Suppressed addresses on this page"),
     annotations: readOnly("List suppressions")
   },
+  {
+    name: "validate_email",
+    description: "Check one email address with Groundmail validation before accepting it (for example at signup): verdict valid | risky | invalid, reasons, a typo suggestion, and disposable / role flags. Free; sends nothing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "Email address to check" }
+      },
+      required: ["email"]
+    },
+    outputSchema: validateEmailOutput,
+    annotations: readOnly("Validate email address")
+  },
   {
     name: "add_suppression",
     description: "Add an address to the suppression list.",
@@ -1068,6 +1136,18 @@ var MCP_TOOLS = [
       idempotentHint: true,
       openWorldHint: true
     }
+  },
+  {
+    name: "get_import_report",
+    description: "Beta. The stored report of an import from SendGrid, Postmark or Mailgun: what was imported, skipped and failed, the DNS changes per domain, what still needs doing, the code change and a prompt for it. Pass the import id, or omit it for the latest import. Previews are not stored.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Import id (the `id` from import_from_provider). Omit for the latest import." }
+      }
+    },
+    outputSchema: migrationOutput,
+    annotations: readOnly("Get an import report")
   }
 ];
 function resolveApiKey() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-mcp",
-  "version": "0.6.4",
+  "version": "0.8.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.30.0",
-    "groundmail": "0.14.8"
+    "groundmail": "0.16.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",