groundmail-mcp 0.20.2 → 0.21.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.
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), 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), 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).
59
59
 
60
60
  ## Transports
61
61
 
package/dist/index.js CHANGED
@@ -305,6 +305,7 @@ var templateItem = object(
305
305
  unsubscribe_enabled: boolean("Whether managed unsubscribe is on for sends using this template"),
306
306
  category: string("transactional or product"),
307
307
  folder: nullableString("Folder the template is filed in, or null"),
308
+ sender_id: nullableString("Sender the template goes out as when a send sets neither from nor sender; null uses the default sender"),
308
309
  published_version_id: nullableString("Id of the version sends currently use"),
309
310
  published_at: nullableString("When the template was last published (ISO 8601)"),
310
311
  created_at: string("When the template was created (ISO 8601)"),
@@ -555,6 +556,32 @@ var tenantItem = object(
555
556
  },
556
557
  ["id", "external_id", "status"]
557
558
  );
559
+ var senderItem = object(
560
+ {
561
+ id: string("Sender id"),
562
+ name: string("The name people see in their inbox"),
563
+ address: string("The address it sends from, on a verified domain"),
564
+ from: string("Name and address as the inbox shows them"),
565
+ reply_to: nullableString("Where replies go; null means replies go to address"),
566
+ handle: string('What sends use to name it (sender: "billing")'),
567
+ is_default: boolean("Sends with no from, sender or template sender go out as the default"),
568
+ used_by: described(
569
+ object({
570
+ automations: number("Automations that send as it"),
571
+ templates: number("Templates that send as it")
572
+ }),
573
+ "How many automations and templates send as it"
574
+ ),
575
+ created_at: string("When the sender was created (ISO 8601)"),
576
+ updated_at: string("When the sender was last changed (ISO 8601)")
577
+ },
578
+ ["id", "name", "address", "handle", "is_default"]
579
+ );
580
+ var senderOutput = object({ sender: described(senderItem, "The sender") }, ["sender"]);
581
+ var listSendersOutput = object(
582
+ { data: arrayOf(senderItem, "Every sender, the default first") },
583
+ ["data"]
584
+ );
558
585
  var tenantOutput = object({ tenant: described(tenantItem, "The tenant") }, ["tenant"]);
559
586
  var streamCounts = (description) => ({
560
587
  ...object({
@@ -776,10 +803,10 @@ async function callMcpTool(client, name, args) {
776
803
  switch (name) {
777
804
  case "send_email": {
778
805
  const from = optString(args, "from");
806
+ const sender = optString(args, "sender");
779
807
  const to = optString(args, "to");
780
808
  const subject = optString(args, "subject");
781
809
  const templateId = optString(args, "template_id") || optString(args, "template_alias");
782
- if (!from) return textResult("Missing required argument: from", true);
783
810
  if (!to) return textResult("Missing required argument: to", true);
784
811
  if (!templateId && !subject) {
785
812
  return textResult("Provide subject, or template_id / template_alias", true);
@@ -791,7 +818,8 @@ async function callMcpTool(client, name, args) {
791
818
  const category = categoryRaw;
792
819
  const variables = args.variables && typeof args.variables === "object" && !Array.isArray(args.variables) ? args.variables : void 0;
793
820
  const result = await client.emails.send({
794
- from,
821
+ ...from ? { from } : {},
822
+ ...sender ? { sender } : {},
795
823
  to,
796
824
  ...subject ? { subject } : {},
797
825
  html: optString(args, "html"),
@@ -994,7 +1022,27 @@ async function callMcpTool(client, name, args) {
994
1022
  html: optString(args, "html"),
995
1023
  text: optString(args, "text"),
996
1024
  alias: optString(args, "alias"),
997
- ...optString(args, "folder") ? { folder: optString(args, "folder") } : {}
1025
+ ...optString(args, "folder") ? { folder: optString(args, "folder") } : {},
1026
+ ...optString(args, "sender") ? { sender_id: optString(args, "sender") } : {}
1027
+ })
1028
+ );
1029
+ }
1030
+ case "list_senders": {
1031
+ return textResult(await client.senders.list());
1032
+ }
1033
+ case "create_sender": {
1034
+ const senderName = optString(args, "name");
1035
+ const address = optString(args, "address");
1036
+ if (!senderName) return textResult("Missing required argument: name", true);
1037
+ if (!address) return textResult("Missing required argument: address", true);
1038
+ const isDefault = optBoolean(args, "is_default");
1039
+ return textResult(
1040
+ await client.senders.create({
1041
+ name: senderName,
1042
+ address,
1043
+ ...optString(args, "reply_to") ? { reply_to: optString(args, "reply_to") } : {},
1044
+ ...optString(args, "handle") ? { handle: optString(args, "handle") } : {},
1045
+ ...isDefault !== void 0 ? { is_default: isDefault } : {}
998
1046
  })
999
1047
  );
1000
1048
  }
@@ -1251,7 +1299,14 @@ var MCP_TOOLS = [
1251
1299
  inputSchema: {
1252
1300
  type: "object",
1253
1301
  properties: {
1254
- from: { type: "string", description: "Sender address (must match a verified domain or sandbox sender)" },
1302
+ from: {
1303
+ type: "string",
1304
+ description: "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"
1305
+ },
1306
+ sender: {
1307
+ type: "string",
1308
+ 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"
1309
+ },
1255
1310
  to: {
1256
1311
  type: "string",
1257
1312
  description: "Recipient email address. A \u2026@simulator.groundmail.dev address simulates an outcome and never delivers"
@@ -1276,7 +1331,7 @@ var MCP_TOOLS = [
1276
1331
  "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"
1277
1332
  )
1278
1333
  },
1279
- required: ["from", "to"]
1334
+ required: ["to"]
1280
1335
  },
1281
1336
  outputSchema: sendEmailOutput,
1282
1337
  annotations: {
@@ -1622,7 +1677,8 @@ var MCP_TOOLS = [
1622
1677
  html: { type: "string", description: "HTML body" },
1623
1678
  text: { type: "string", description: "Plain-text body" },
1624
1679
  alias: { type: "string", description: "Optional short alias to reference the template by instead of its id" },
1625
- folder: { type: "string", description: "Optional folder to file the template in; created if it does not exist" }
1680
+ folder: { type: "string", description: "Optional folder to file the template in; created if it does not exist" },
1681
+ sender: { type: "string", description: "Sender handle or id (list_senders) the template goes out as when a send sets neither from nor sender" }
1626
1682
  },
1627
1683
  required: ["name", "subject"]
1628
1684
  },
@@ -1655,6 +1711,36 @@ var MCP_TOOLS = [
1655
1711
  openWorldHint: false
1656
1712
  }
1657
1713
  },
1714
+ {
1715
+ name: "list_senders",
1716
+ 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.",
1717
+ inputSchema: { type: "object", properties: {} },
1718
+ outputSchema: listSendersOutput,
1719
+ annotations: readOnly("List senders")
1720
+ },
1721
+ {
1722
+ name: "create_sender",
1723
+ description: 'Save a sender: the name people see, an address on a verified domain (list_domains), an optional reply-to, and a handle sends use (sender: "billing"). The first sender becomes the default unless is_default is false.',
1724
+ inputSchema: {
1725
+ type: "object",
1726
+ properties: {
1727
+ name: { type: "string", description: "The name people see, for example Acme Billing" },
1728
+ address: { type: "string", description: "Address on one of the team's verified domains, for example billing@mail.acme.com" },
1729
+ reply_to: { type: "string", description: "Where replies go. Leave it out to get replies at address" },
1730
+ handle: { type: "string", description: "Lowercase letters, digits and hyphens. Made from name when left out" },
1731
+ is_default: { type: "boolean", description: "Make it the default sender for sends with no from" }
1732
+ },
1733
+ required: ["name", "address"]
1734
+ },
1735
+ outputSchema: senderOutput,
1736
+ annotations: {
1737
+ title: "Create sender",
1738
+ readOnlyHint: false,
1739
+ destructiveHint: false,
1740
+ idempotentHint: false,
1741
+ openWorldHint: false
1742
+ }
1743
+ },
1658
1744
  {
1659
1745
  name: "send_test_webhook_event",
1660
1746
  description: "Simulate a webhook event (POST /emails/test) for CI or local webhook testing. Optionally deliver to subscribed endpoints.",
@@ -1957,7 +2043,7 @@ function resolveApiKey() {
1957
2043
  }
1958
2044
 
1959
2045
  // src/server.ts
1960
- var MCP_SERVER_VERSION = "0.20.2";
2046
+ var MCP_SERVER_VERSION = "0.21.0";
1961
2047
  var MCP_SERVER_INSTRUCTIONS = [
1962
2048
  "Groundmail sends transactional email from domains the user has verified.",
1963
2049
  '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.20.2",
3
+ "version": "0.21.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",
@@ -40,8 +40,8 @@
40
40
  "prepublishOnly": "npm run build"
41
41
  },
42
42
  "dependencies": {
43
- "@modelcontextprotocol/sdk": "^1.32.1",
44
- "groundmail": "0.33.0"
43
+ "@modelcontextprotocol/sdk": "^1.32.2",
44
+ "groundmail": "0.34.0"
45
45
  },
46
46
  "devDependencies": {
47
47
  "tsup": "^8.5.0",