groundmail-mcp 0.22.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +1 -1
  2. package/dist/index.js +146 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -55,7 +55,7 @@ When you connect, you choose the access: **Full**, **Send only** or **Read only*
55
55
  >
56
56
  > "How is my deliverability over the last 7 days?"
57
57
 
58
- Tools cover emails (send, list, look up), received emails (with replies linked to the email you sent), domains (add, apply DNS through Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple, verify), senders (saved names and addresses to send as), 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).
58
+ Tools cover emails (send, list, look up), batch sends (status counts, cancel the scheduled emails in one call), received emails (with replies linked to the email you sent), domains (add, apply DNS through Cloudflare, Vercel, GoDaddy, Netlify, DigitalOcean or DNSimple, verify), senders (saved names and addresses to send as), your brand (logo, colors and footer every template follows), 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).
59
59
 
60
60
  ## Transports
61
61
 
package/dist/index.js CHANGED
@@ -181,6 +181,7 @@ var emailItem = object(
181
181
  bounced_at: nullableString("When the email bounced (ISO 8601)"),
182
182
  opened_at: nullableString("First open (ISO 8601); needs open tracking on the sending domain"),
183
183
  clicked_at: nullableString("First tracked-link click (ISO 8601); needs click tracking on the sending domain"),
184
+ batch_id: nullableString("The batch send it came from (batch_\u2026), for get_batch and cancel_batch; null for a single send"),
184
185
  tenant: nullableString("External id of the tenant the email was sent as. Present only when it was sent as a tenant"),
185
186
  stream: string("Mail stream it went out on: transactional, product or newsletter (each sends from its own IPs)")
186
187
  },
@@ -366,6 +367,28 @@ var validateEmailOutput = object(
366
367
  ["email", "verdict", "reasons", "suggestion", "disposable", "role"]
367
368
  );
368
369
  var getEmailOutput = object({ email: described(emailItem, "The email") }, ["email"]);
370
+ var batchOutput = object(
371
+ {
372
+ batch_id: string("Batch id (batch_\u2026)"),
373
+ created_at: string("When the batch's first email was created (ISO 8601)"),
374
+ total: number("Emails in the batch"),
375
+ counts: {
376
+ type: "object",
377
+ additionalProperties: { type: "number" },
378
+ description: 'Emails by current status, for example { "scheduled": 98, "sent": 2 }. Only statuses with an email appear'
379
+ }
380
+ },
381
+ ["batch_id", "created_at", "total", "counts"]
382
+ );
383
+ var cancelBatchOutput = object(
384
+ {
385
+ batch_id: string("Batch id (batch_\u2026)"),
386
+ cancelled: number("Scheduled emails this call cancelled"),
387
+ already_cancelled: number("Emails that were already cancelled before this call"),
388
+ not_cancellable: number("Emails already queued, sent or finished, which can no longer be cancelled")
389
+ },
390
+ ["batch_id", "cancelled", "already_cancelled", "not_cancellable"]
391
+ );
369
392
  var domainWithRecordsOutput = object(
370
393
  {
371
394
  domain: described(domainItem, "The domain"),
@@ -582,6 +605,30 @@ var listSendersOutput = object(
582
605
  { data: arrayOf(senderItem, "Every sender, the default first") },
583
606
  ["data"]
584
607
  );
608
+ var brandOutput = object(
609
+ {
610
+ brand: described(
611
+ object(
612
+ {
613
+ is_set: boolean("False until anything is set"),
614
+ settings: described(object({}), "The look templates follow: any of a template design's settings (colors, fonts, button style, globalCss)"),
615
+ logo: described(
616
+ object({ url: string("https image URL"), width: { type: ["number", "null"], description: "Width in px" }, align: string("left or center") }, ["url", "align"]),
617
+ "The logo on top of every branded email, or null"
618
+ ),
619
+ accent_color: nullableString("The line across the top of every email"),
620
+ company_name: nullableString("Company name for the footer"),
621
+ address: nullableString("Mailing address for the footer"),
622
+ website: nullableString("Website, linked from the logo and the footer"),
623
+ updated_at: nullableString("When the brand was last changed (ISO 8601)")
624
+ },
625
+ ["is_set", "settings"]
626
+ ),
627
+ "The workspace brand"
628
+ )
629
+ },
630
+ ["brand"]
631
+ );
585
632
  var tenantOutput = object({ tenant: described(tenantItem, "The tenant") }, ["tenant"]);
586
633
  var streamCounts = (description) => ({
587
634
  ...object({
@@ -851,6 +898,16 @@ async function callMcpTool(client, name, args) {
851
898
  if (!id) return textResult("Missing required argument: id", true);
852
899
  return textResult(await client.emails.get(id));
853
900
  }
901
+ case "get_batch": {
902
+ const id = optString(args, "batch_id");
903
+ if (!id) return textResult("Missing required argument: batch_id", true);
904
+ return textResult(await client.batches.get(id));
905
+ }
906
+ case "cancel_batch": {
907
+ const id = optString(args, "batch_id");
908
+ if (!id) return textResult("Missing required argument: batch_id", true);
909
+ return textResult(await client.batches.cancel(id));
910
+ }
854
911
  case "list_received_emails": {
855
912
  const inReplyToEmail = optString(args, "in_reply_to_email");
856
913
  return textResult(
@@ -1027,6 +1084,21 @@ async function callMcpTool(client, name, args) {
1027
1084
  })
1028
1085
  );
1029
1086
  }
1087
+ case "get_brand": {
1088
+ return textResult(await client.brand.get());
1089
+ }
1090
+ case "update_brand": {
1091
+ const params = {};
1092
+ for (const key of ["accent_color", "company_name", "address", "website"]) {
1093
+ if (key in args) params[key] = args[key] === null ? null : optString(args, key);
1094
+ }
1095
+ if ("logo" in args) params.logo = args.logo ?? null;
1096
+ if (args.settings && typeof args.settings === "object" && !Array.isArray(args.settings)) params.settings = args.settings;
1097
+ if (!Object.keys(params).length) {
1098
+ return textResult("Nothing to update: pass settings, logo, accent_color, company_name, address or website", true);
1099
+ }
1100
+ return textResult(await client.brand.update(params));
1101
+ }
1030
1102
  case "list_senders": {
1031
1103
  return textResult(await client.senders.list());
1032
1104
  }
@@ -1374,6 +1446,38 @@ var MCP_TOOLS = [
1374
1446
  outputSchema: getEmailOutput,
1375
1447
  annotations: readOnly("Get email")
1376
1448
  },
1449
+ {
1450
+ name: "get_batch",
1451
+ description: "Get a batch send (the batch_id a batch send returned, also on each of its emails as batch_id): how many emails it has and how many are in each status now.",
1452
+ inputSchema: {
1453
+ type: "object",
1454
+ properties: {
1455
+ batch_id: { type: "string", description: "Batch id (batch_\u2026)" }
1456
+ },
1457
+ required: ["batch_id"]
1458
+ },
1459
+ outputSchema: batchOutput,
1460
+ annotations: readOnly("Get batch")
1461
+ },
1462
+ {
1463
+ name: "cancel_batch",
1464
+ description: "Cancel every email in a batch send that is still scheduled. Emails already queued or sent are left alone and counted in not_cancellable. Safe to repeat: a second call cancels nothing more. Confirm with the user before cancelling.",
1465
+ inputSchema: {
1466
+ type: "object",
1467
+ properties: {
1468
+ batch_id: { type: "string", description: "Batch id (batch_\u2026)" }
1469
+ },
1470
+ required: ["batch_id"]
1471
+ },
1472
+ outputSchema: cancelBatchOutput,
1473
+ annotations: {
1474
+ title: "Cancel batch",
1475
+ readOnlyHint: false,
1476
+ destructiveHint: true,
1477
+ idempotentHint: true,
1478
+ openWorldHint: false
1479
+ }
1480
+ },
1377
1481
  {
1378
1482
  name: "list_received_emails",
1379
1483
  description: "List emails received on domains with inbound enabled, newest first (bodies left out). A reply to an email you sent through Groundmail has in_reply_to_email: the sent email it answers. Pass in_reply_to_email: msg_\u2026 to list the replies to one sent email.",
@@ -1711,6 +1815,47 @@ var MCP_TOOLS = [
1711
1815
  openWorldHint: false
1712
1816
  }
1713
1817
  },
1818
+ {
1819
+ name: "get_brand",
1820
+ description: "Get the workspace brand: the look every template follows unless it overrides a setting (settings: the same keys as a template design's settings), the logo on top, the accent line, and the company name, mailing address and website in the footer.",
1821
+ inputSchema: { type: "object", properties: {} },
1822
+ outputSchema: brandOutput,
1823
+ annotations: readOnly("Get brand")
1824
+ },
1825
+ {
1826
+ name: "update_brand",
1827
+ description: "Update the workspace brand. Fields left out keep their value; null clears one. settings replaces the brand's look (read it with get_brand first and change what you need). Templates that follow the brand pick it up from their next send.",
1828
+ inputSchema: {
1829
+ type: "object",
1830
+ properties: {
1831
+ settings: {
1832
+ type: "object",
1833
+ description: "The look, as a template design's settings: backgroundColor, contentBackgroundColor, textColor, linkColor, fontFamily, contentWidth, darkMode, globalCss, and theme { buttonBackground, buttonTextColor, buttonRadius, bodyFontSize, lineHeight, headingFontSize }"
1834
+ },
1835
+ logo: {
1836
+ type: ["object", "null"],
1837
+ description: "The logo: { url: https image URL, align: left | center, width?: px }. null removes it",
1838
+ properties: {
1839
+ url: { type: "string", description: "https image URL (PNG or JPEG show in every mail app)" },
1840
+ align: { type: "string", enum: ["left", "center"], description: "Where the logo sits" },
1841
+ width: { type: "number", description: "Width in px, 24 to 552. Default 120" }
1842
+ }
1843
+ },
1844
+ accent_color: { type: ["string", "null"], description: "Hex colour of the line across the top, for example #2f6feb" },
1845
+ company_name: { type: ["string", "null"], description: "Company name for the footer" },
1846
+ address: { type: ["string", "null"], description: "Mailing address for the footer (a PO box is fine)" },
1847
+ website: { type: ["string", "null"], description: "Website, for example acme.com" }
1848
+ }
1849
+ },
1850
+ outputSchema: brandOutput,
1851
+ annotations: {
1852
+ title: "Update brand",
1853
+ readOnlyHint: false,
1854
+ destructiveHint: false,
1855
+ idempotentHint: true,
1856
+ openWorldHint: false
1857
+ }
1858
+ },
1714
1859
  {
1715
1860
  name: "list_senders",
1716
1861
  description: "List saved senders: name, address, reply-to and handle, the default first, with how many automations and templates use each. Send as one with send_email sender instead of typing from.",
@@ -2043,7 +2188,7 @@ function resolveApiKey() {
2043
2188
  }
2044
2189
 
2045
2190
  // src/server.ts
2046
- var MCP_SERVER_VERSION = "0.22.0";
2191
+ var MCP_SERVER_VERSION = "0.24.0";
2047
2192
  var MCP_SERVER_INSTRUCTIONS = [
2048
2193
  "Groundmail sends transactional email from domains the user has verified.",
2049
2194
  '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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "groundmail-mcp",
3
- "version": "0.22.0",
3
+ "version": "0.24.0",
4
4
  "mcpName": "io.github.Groundmail/groundmail",
5
5
  "description": "Groundmail MCP server: send transactional email, manage domains, templates, webhooks and suppressions from Claude, Cursor, ChatGPT and other MCP clients",
6
6
  "license": "MIT",
@@ -41,7 +41,7 @@
41
41
  },
42
42
  "dependencies": {
43
43
  "@modelcontextprotocol/sdk": "^1.32.2",
44
- "groundmail": "0.36.0"
44
+ "groundmail": "0.38.0"
45
45
  },
46
46
  "devDependencies": {
47
47
  "tsup": "^8.5.0",