mailtruss-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Mailtruss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# mailtruss-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [Mailtruss](https://mailtruss.com).
+
+Lets an AI assistant (Claude, Cursor, any MCP client) send email and manage domains, contacts, templates and broadcasts with **your** API key.
+
+```json
+{
+  "mcpServers": {
+    "mailtruss": {
+      "command": "npx",
+      "args": ["-y", "mailtruss-mcp"],
+      "env": { "MAILTRUSS_API_KEY": "ms_live_…", "MAILTRUSS_API_URL": "https://mailtruss.com" }
+    }
+  }
+}
+```
+
+- Create the key under **API keys** in the dashboard. Use a *full access* key for everything, or a *sending access* key to allow only `send_email`.
+- Set `MAILTRUSS_MCP_READONLY=1` to expose only tools that cannot change anything.
+- Tools that send, change or delete are annotated so your assistant's host can ask for confirmation first. `send_email` and `send_broadcast` deliver real mail.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { MailClient } from "mailtruss";
+import { createServer } from "./server.js";
+const apiKey = process.env.MAILTRUSS_API_KEY;
+if (!apiKey) {
+    console.error("Set MAILTRUSS_API_KEY to an API key from your dashboard (API keys).");
+    process.exit(1);
+}
+const client = new MailClient({ apiKey, baseUrl: process.env.MAILTRUSS_API_URL ?? "https://mailtruss.com" });
+const readOnly = process.env.MAILTRUSS_MCP_READONLY === "1";
+await createServer(client, { readOnly }).connect(new StdioServerTransport());
+console.error(`mailtruss MCP server running${readOnly ? " (read-only)" : ""}`); // stderr: stdout carries the protocol

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MailClient } from "mailtruss";
+export type ServerOptions = {
+    readOnly?: boolean;
+};
+/**
+ * MCP tools over the public API, using the caller's own API key. Every tool is annotated so an assistant's host can ask
+ * before anything that sends, changes or deletes. `readOnly` registers only the tools that cannot change anything.
+ */
+export declare function createServer(client: MailClient, opts?: ServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,61 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { MailError } from "mailtruss";
+/**
+ * MCP tools over the public API, using the caller's own API key. Every tool is annotated so an assistant's host can ask
+ * before anything that sends, changes or deletes. `readOnly` registers only the tools that cannot change anything.
+ */
+export function createServer(client, opts = {}) {
+    const server = new McpServer({ name: "mailtruss", version: "0.1.0" });
+    const text = (v) => ({ content: [{ type: "text", text: JSON.stringify(v, null, 2) }] });
+    const fail = (e) => ({ isError: true, content: [{ type: "text", text: e instanceof MailError ? `${e.message} (${e.statusCode} ${e.name_}${e.requestId ? `, request ${e.requestId}` : ""})` : e instanceof Error ? e.message : "Unexpected error" }] });
+    function tool(name, title, description, kind, shape, run) {
+        if (opts.readOnly && kind !== "read")
+            return;
+        server.registerTool(name, {
+            title, description, inputSchema: shape,
+            annotations: { readOnlyHint: kind === "read", destructiveHint: kind === "danger", idempotentHint: kind === "read", openWorldHint: name === "send_email" || name === "send_broadcast" },
+        }, (async (a) => { try {
+            return text(await run(a));
+        }
+        catch (e) {
+            return fail(e);
+        } }));
+    }
+    const id = { id: z.string().describe("The id") };
+    // ---- Email ----
+    tool("send_email", "Send an email", "Sends one email now, or at `scheduled_at`. The from address must be on a verified domain. This delivers real mail to real recipients.", "danger", { from: z.string().describe("Sender, e.g. 'Ada <ada@yourdomain.com>'"), to: z.union([z.string(), z.array(z.string())]), subject: z.string(), html: z.string().optional(), text: z.string().optional(), reply_to: z.string().optional(), scheduled_at: z.string().optional().describe("ISO 8601, up to 30 days ahead") }, (a) => client.emails.send(a));
+    tool("get_email", "Get an email", "Returns one sent email with its latest status.", "read", id, (a) => client.emails.get(a.id));
+    tool("list_emails", "List emails", "Lists recent emails, newest first.", "read", { limit: z.number().int().min(1).max(100).optional(), after: z.string().optional().describe("Email id to continue after") }, (a) => client.emails.list(a));
+    tool("cancel_email", "Cancel a scheduled email", "Cancels an email that has not been sent yet.", "danger", id, (a) => client.emails.cancel(a.id));
+    // ---- Domains ----
+    tool("list_domains", "List domains", "Lists sending domains and their verification status.", "read", {}, () => client.domains.list());
+    tool("get_domain", "Get a domain", "Returns a domain with the DNS records that must be published.", "read", id, (a) => client.domains.get(a.id));
+    tool("create_domain", "Add a domain", "Adds a sending domain and returns the DNS records to publish.", "write", { name: z.string().describe("e.g. mail.example.com") }, (a) => client.domains.create(a));
+    tool("verify_domain", "Re-check a domain", "Checks the domain's DNS now.", "write", id, (a) => client.domains.verify(a.id));
+    tool("set_domain_tracking", "Set click and open tracking", "Turns click and open tracking on or off for a domain. Both are off by default; recipients must be told.", "write", { id: z.string(), click_tracking: z.boolean().optional(), open_tracking: z.boolean().optional() }, ({ id: i, ...p }) => client.domains.setTracking(i, p));
+    // ---- Audience ----
+    tool("list_contacts", "List contacts", "Lists contacts, optionally filtered.", "read", { q: z.string().optional(), tag: z.string().optional(), status: z.enum(["subscribed", "unsubscribed"]).optional(), page: z.number().int().min(1).optional(), limit: z.number().int().min(1).max(200).optional() }, (a) => client.contacts.list(a));
+    tool("get_contact", "Get a contact", "Returns a contact by id or email address.", "read", { id: z.string().describe("Contact id or email") }, (a) => client.contacts.get(a.id));
+    tool("create_contact", "Create or update a contact", "Creates a contact, or updates it when the email already exists. Never re-subscribes someone who unsubscribed.", "write", { email: z.string(), first_name: z.string().optional(), last_name: z.string().optional(), tags: z.array(z.string()).optional() }, (a) => client.contacts.create(a));
+    tool("delete_contact", "Delete a contact", "Permanently deletes a contact.", "danger", { id: z.string().describe("Contact id or email") }, (a) => client.contacts.remove(a.id));
+    tool("list_segments", "List segments", "Lists saved audience filters with their sizes.", "read", {}, () => client.segments.list());
+    tool("list_topics", "List topics", "Lists topics people can subscribe to.", "read", {}, () => client.topics.list());
+    tool("list_suppressions", "List suppressed addresses", "Lists addresses that will not be sent to, with the reason.", "read", { q: z.string().optional(), reason: z.enum(["hard_bounce", "complaint", "unsubscribe", "manual"]).optional() }, (a) => client.suppressions.list(a));
+    tool("suppress_address", "Suppress an address", "Stops all sending to an address.", "write", { email: z.string() }, (a) => client.suppressions.add(a.email));
+    tool("remove_suppression", "Remove a suppression", "Allows sending to a bounced or manually added address again. Complaints and unsubscribes cannot be removed.", "danger", { id: z.string().describe("Suppression id or email") }, (a) => client.suppressions.remove(a.id));
+    // ---- Templates and broadcasts ----
+    tool("list_templates", "List templates", "Lists email templates.", "read", {}, () => client.templates.list());
+    tool("get_template", "Get a template", "Returns a template's latest HTML, text and variables.", "read", id, (a) => client.templates.get(a.id));
+    tool("create_template", "Create a template", "Creates a template; set `publish` to make it live for sends by id or alias.", "write", { name: z.string(), subject: z.string(), html: z.string(), text: z.string().optional(), alias: z.string().optional(), publish: z.boolean().optional() }, (a) => client.templates.create(a));
+    tool("update_template", "Update a template", "Saves a new, unpublished version.", "write", { id: z.string(), name: z.string().optional(), subject: z.string().optional(), html: z.string().optional(), text: z.string().optional() }, ({ id: i, ...p }) => client.templates.update(i, p));
+    tool("publish_template", "Publish a template version", "Makes a version live for sends. Defaults to the latest.", "write", { id: z.string(), version: z.number().int().optional() }, ({ id: i, version }) => client.templates.publish(i, { version }));
+    tool("list_broadcasts", "List broadcasts", "Lists broadcasts with their status.", "read", {}, () => client.broadcasts.list());
+    tool("get_broadcast", "Get a broadcast", "Returns a broadcast with delivery, open and click counts.", "read", id, (a) => client.broadcasts.get(a.id));
+    tool("create_broadcast", "Create a draft broadcast", "Creates a draft. Nothing is sent until send_broadcast.", "write", { name: z.string(), from: z.string(), subject: z.string(), html: z.string(), segment_id: z.string().optional(), topic_id: z.string().optional() }, (a) => client.broadcasts.create(a));
+    tool("send_broadcast", "Send a broadcast", "Sends a draft broadcast to its whole audience now, or at `scheduled_at`. This delivers real mail to many people.", "danger", { id: z.string(), scheduled_at: z.string().optional() }, ({ id: i, scheduled_at }) => client.broadcasts.send(i, { scheduled_at }));
+    // ---- Operations ----
+    tool("list_webhooks", "List webhook endpoints", "Lists webhook endpoints and their events.", "read", {}, () => client.webhooks.list());
+    tool("list_logs", "List API request logs", "Lists recent API requests with status and duration. Useful for debugging.", "read", { limit: z.number().int().min(1).max(100).optional() }, (a) => client.logs.list(a));
+    return server;
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "mailtruss-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "MCP server for Mailtruss: lets AI assistants send email and manage domains, contacts, templates and broadcasts with your API key",
+  "license": "MIT",
+  "author": "Mailtruss <hello@mailtruss.com>",
+  "homepage": "https://mailtruss.com/docs",
+  "type": "module",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "email",
+    "mailtruss",
+    "ai-agents"
+  ],
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "mailtruss-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "zod": "^4.1.0",
+    "mailtruss": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "start": "tsx src/cli.ts"
+  }
 }