Merge pull request #63 from mailtrap/sending-domains

Add sending-domains tools

Author: mklocek

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 * Add **list-email-logs** and **get-email-log-message** tools: query sent-mail delivery history with filters and pagination; inspect a single log by UUID (summary, event timeline, optional body via `include_content`).
 * Add **get-sending-stats** tool: check delivery, bounce, open, click, and spam rates for a date range; optional breakdown by domain, category, email service provider, or date.
+* Add **sending domains** tools: **list-sending-domains**, **get-sending-domain**, **create-sending-domain**, **delete-sending-domain**. **get-sending-domain** accepts optional `include_setup_instructions: true` to append DNS setup instructions to the response.
 
 ## [0.1.0] - 2025-12-09
 

CLAUDE.md

@@ -52,7 +52,7 @@ Schema files define a JSON Schema–shaped object for MCP; optional Zod schemas
 
 - `MAILTRAP_API_TOKEN`: Required API token from Mailtrap
 - `DEFAULT_FROM_EMAIL`: Default sender email address
-- `MAILTRAP_ACCOUNT_ID`: Required for almost all tools (templates, stats, email logs, sandbox list/show). Optional only for send-email and send-sandbox-email.
+- `MAILTRAP_ACCOUNT_ID`: Required for templates, stats, email logs, sandbox list/show, and sending domains. Optional only for send-email and send-sandbox-email.
 - `MAILTRAP_TEST_INBOX_ID`: Required for sandbox tools - test inbox ID for sandbox mode operations
 
 ### Testing Setup
@@ -96,4 +96,12 @@ Schema files define a JSON Schema–shaped object for MCP; optional Zod schemas
 - **get-sandbox-messages**: Get list of messages from the sandbox test inbox.
 - **show-sandbox-email-message**: Show sandbox email message details and content from the sandbox test inbox.
 
+
+#### Sending Domains
+
+- **list-sending-domains**: List sending domains and their DNS verification status.
+- **get-sending-domain**: Get a sending domain by ID and its verification status. With `include_setup_instructions: true`, append DNS setup instructions to the response.
+- **create-sending-domain**: Create a new sending domain.
+- **delete-sending-domain**: Delete a sending domain.
+
 Tools use input schemas (JSON Schema format) for MCP; handlers may validate input with Zod. Response format follows the MCP protocol.

README.md

@@ -19,7 +19,7 @@ Before using this MCP server, you need to:
 
 - `MAILTRAP_API_TOKEN` - Required for all functionality
 - `DEFAULT_FROM_EMAIL` - Required for all email sending operations
-- `MAILTRAP_ACCOUNT_ID` - Required for almost all tools (templates, stats, email logs, sandbox list/show). Optional only for send-email and send-sandbox-email.
+- `MAILTRAP_ACCOUNT_ID` - Required for templates, stats, email logs, sandbox list/show, and sending domains. Optional only for send-email and send-sandbox-email.
 - `MAILTRAP_TEST_INBOX_ID` - Required for sandbox tools (send, list messages, show message)
 
 ## Quick Install
@@ -188,6 +188,14 @@ Once configured, you can ask agent to send emails and manage templates, for exam
 - "Update the template with ID 12345 to change the subject to 'Updated Welcome Message'"
 - "Delete the template with ID 67890"
 
+**Sending Domains:**
+
+- "List my sending domains"
+- "Get sending domain with ID 3938"
+- "Create a sending domain for example.com"
+- "Delete sending domain 3938"
+- "Get sending domain 3938 with DNS setup instructions"
+
 ## Available Tools
 
 ### send-email
@@ -340,6 +348,39 @@ Shows detailed information and content of a specific email message from your Mai
 > Use `get-sandbox-messages` first to get the list of messages and their IDs, then use this tool to view the full content of a specific message.
 
 
+### list-sending-domains
+
+List sending domains and their DNS verification status.
+
+**Parameters:**
+
+- No parameters required
+
+### get-sending-domain
+
+Get a sending domain by ID and its verification status (including DNS records). Optionally include DNS setup instructions by setting `include_setup_instructions` to `true`.
+
+**Parameters:**
+
+- `sending_domain_id` (required): Sending domain ID
+- `include_setup_instructions` (optional): If `true`, append DNS setup instructions to the response. Default: `false`
+
+### create-sending-domain
+
+Create a new sending domain. After creation, add DNS records to verify the domain (use get-sending-domain with `include_setup_instructions: true` to see the records).
+
+**Parameters:**
+
+- `domain_name` (required): Domain name (e.g. example.com)
+
+### delete-sending-domain
+
+Delete a sending domain.
+
+**Parameters:**
+
+- `sending_domain_id` (required): Sending domain ID to delete
+
 ## Development
 
 1. Clone the repository:

src/server.ts

@@ -37,6 +37,16 @@ import {
   getEmailLogMessage,
   getEmailLogMessageSchema,
 } from "./tools/emailLogs";
+import {
+  listSendingDomains,
+  listSendingDomainsSchema,
+  getSendingDomain,
+  getSendingDomainSchema,
+  createSendingDomain,
+  createSendingDomainSchema,
+  deleteSendingDomain,
+  deleteSendingDomainSchema,
+} from "./tools/sendingDomains";
 
 // Define the tools registry
 const tools = [
@@ -139,6 +149,43 @@ const tools = [
       readOnlyHint: true,
     },
   },
+  {
+    name: "list-sending-domains",
+    description: "List sending domains and their DNS verification status",
+    inputSchema: listSendingDomainsSchema,
+    handler: listSendingDomains,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "get-sending-domain",
+    description:
+      "Get a sending domain by ID and its verification status. Optionally include DNS setup instructions via include_setup_instructions.",
+    inputSchema: getSendingDomainSchema,
+    handler: getSendingDomain,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "create-sending-domain",
+    description: "Create a new sending domain",
+    inputSchema: createSendingDomainSchema,
+    handler: createSendingDomain,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
+  {
+    name: "delete-sending-domain",
+    description: "Delete a sending domain",
+    inputSchema: deleteSendingDomainSchema,
+    handler: deleteSendingDomain,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
 ];
 
 export function createServer(): Server {

src/tools/sendingDomains/__tests__/createSendingDomain.test.ts

@@ -0,0 +1,73 @@
+import createSendingDomain from "../createSendingDomain";
+import { client } from "../../../client";
+
+jest.mock("../../../client", () => ({
+  client: {
+    sendingDomains: {
+      create: jest.fn(),
+    },
+  },
+}));
+
+const originalEnv = { ...process.env };
+
+describe("createSendingDomain", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    Object.assign(process.env, { MAILTRAP_ACCOUNT_ID: "12345" });
+    (client.sendingDomains.create as jest.Mock).mockResolvedValue({
+      id: 3938,
+      domain_name: "example.com",
+      dns_records: [
+        {
+          key: "verification",
+          type: "CNAME",
+          name: "verify123",
+          value: "smtp.mailtrap.live",
+          status: "pending",
+        },
+      ],
+    });
+  });
+
+  afterEach(() => {
+    Object.assign(process.env, originalEnv);
+  });
+
+  it("should create sending domain successfully and show DNS setup instructions", async () => {
+    const result = await createSendingDomain({ domain_name: "example.com" });
+
+    expect(client.sendingDomains.create).toHaveBeenCalledWith({
+      domain_name: "example.com",
+    });
+    expect(result.content[0].text).toContain("example.com");
+    expect(result.content[0].text).toContain("created successfully");
+    expect(result.content[0].text).toContain("3938");
+    expect(result.content[0].text).toContain("Add DNS records for example.com");
+    expect(result.content[0].text).toContain("DNS records to add:");
+    expect(result.content[0].text).toContain("verification");
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("should require MAILTRAP_ACCOUNT_ID", async () => {
+    delete process.env.MAILTRAP_ACCOUNT_ID;
+
+    const result = await createSendingDomain({ domain_name: "example.com" });
+
+    expect(client.sendingDomains.create).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+  });
+
+  it("should handle API failure", async () => {
+    (client.sendingDomains.create as jest.Mock).mockRejectedValue(
+      new Error("Domain already exists")
+    );
+
+    const result = await createSendingDomain({ domain_name: "example.com" });
+
+    expect(result.content[0].text).toEqual(
+      "Failed to create sending domain: Domain already exists"
+    );
+    expect(result.isError).toBe(true);
+  });
+});

src/tools/sendingDomains/__tests__/deleteSendingDomain.test.ts

@@ -0,0 +1,53 @@
+import deleteSendingDomain from "../deleteSendingDomain";
+import { client } from "../../../client";
+
+jest.mock("../../../client", () => ({
+  client: {
+    sendingDomains: {
+      delete: jest.fn(),
+    },
+  },
+}));
+
+const originalEnv = { ...process.env };
+
+describe("deleteSendingDomain", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    Object.assign(process.env, { MAILTRAP_ACCOUNT_ID: "12345" });
+    (client.sendingDomains.delete as jest.Mock).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    Object.assign(process.env, originalEnv);
+  });
+
+  it("should delete sending domain successfully", async () => {
+    const result = await deleteSendingDomain({ sending_domain_id: 3938 });
+
+    expect(client.sendingDomains.delete).toHaveBeenCalledWith(3938);
+    expect(result.content[0].text).toContain("deleted successfully");
+    expect(result.content[0].text).toContain("3938");
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("should require MAILTRAP_ACCOUNT_ID", async () => {
+    delete process.env.MAILTRAP_ACCOUNT_ID;
+
+    const result = await deleteSendingDomain({ sending_domain_id: 3938 });
+
+    expect(client.sendingDomains.delete).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+  });
+
+  it("should handle API failure", async () => {
+    (client.sendingDomains.delete as jest.Mock).mockRejectedValue(
+      new Error("Not found")
+    );
+
+    const result = await deleteSendingDomain({ sending_domain_id: 999 });
+
+    expect(result.content[0].text).toContain("Failed to delete sending domain");
+    expect(result.isError).toBe(true);
+  });
+});

src/tools/sendingDomains/__tests__/getSendingDomain.test.ts

@@ -0,0 +1,101 @@
+import getSendingDomain from "../getSendingDomain";
+import { client } from "../../../client";
+
+jest.mock("../../../client", () => ({
+  client: {
+    sendingDomains: {
+      get: jest.fn(),
+    },
+  },
+}));
+
+const originalEnv = { ...process.env };
+
+describe("getSendingDomain", () => {
+  const mockDomain = {
+    id: 3938,
+    domain_name: "example.com",
+    demo: false,
+    compliance_status: "compliant",
+    dns_verified: true,
+    dns_verified_at: "2024-12-26T09:40:44.161Z",
+    dns_records: [
+      {
+        key: "spf",
+        type: "TXT",
+        name: "",
+        value: "v=spf1 include:_spf.smtp.mailtrap.live ~all",
+        status: "pass",
+        domain: "example.com",
+      },
+    ],
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    Object.assign(process.env, { MAILTRAP_ACCOUNT_ID: "12345" });
+    (client.sendingDomains.get as jest.Mock).mockResolvedValue(mockDomain);
+  });
+
+  afterEach(() => {
+    Object.assign(process.env, originalEnv);
+  });
+
+  it("should get sending domain successfully", async () => {
+    const result = await getSendingDomain({ sending_domain_id: 3938 });
+
+    expect(client.sendingDomains.get).toHaveBeenCalledWith(3938);
+    expect(result.content[0].text).toContain("example.com");
+    expect(result.content[0].text).toContain("ID: 3938");
+    expect(result.content[0].text).toContain("DNS verified: true");
+    expect(result.content[0].text).toContain("spf");
+    expect(result.content[0].text).toContain("pass");
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("should include setup instructions when include_setup_instructions is true", async () => {
+    const result = await getSendingDomain({
+      sending_domain_id: 3938,
+      include_setup_instructions: true,
+    });
+
+    expect(client.sendingDomains.get).toHaveBeenCalledWith(3938);
+    expect(result.content[0].text).toContain("Domain: example.com");
+    expect(result.content[0].text).toContain("Add DNS records for example.com");
+    expect(result.content[0].text).toContain("What?");
+    expect(result.content[0].text).toContain("Why?");
+    expect(result.content[0].text).toContain("DNS records to add");
+    expect(result.content[0].text).toContain("docs.mailtrap.io");
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("should not include setup instructions when include_setup_instructions is false or omitted", async () => {
+    const result = await getSendingDomain({
+      sending_domain_id: 3938,
+      include_setup_instructions: false,
+    });
+
+    expect(result.content[0].text).not.toContain("Add DNS records for");
+    expect(result.content[0].text).not.toContain("What?");
+  });
+
+  it("should require MAILTRAP_ACCOUNT_ID", async () => {
+    delete process.env.MAILTRAP_ACCOUNT_ID;
+
+    const result = await getSendingDomain({ sending_domain_id: 3938 });
+
+    expect(client.sendingDomains.get).not.toHaveBeenCalled();
+    expect(result.isError).toBe(true);
+  });
+
+  it("should handle API failure", async () => {
+    (client.sendingDomains.get as jest.Mock).mockRejectedValue(
+      new Error("Not found")
+    );
+
+    const result = await getSendingDomain({ sending_domain_id: 999 });
+
+    expect(result.content[0].text).toContain("Failed to get sending domain");
+    expect(result.isError).toBe(true);
+  });
+});