add delete-sub-account tool

CLAUDE.md

@@ -230,5 +230,6 @@ Folders contain inboxes; inboxes receive messages, grouped into threads.
 
 - **list-sub-accounts**: List sub-accounts in the organization (requires `MAILTRAP_ORGANIZATION_ID`).
 - **create-sub-account**: Create a sub-account under the organization (requires `MAILTRAP_ORGANIZATION_ID`).
+- **delete-sub-account**: Permanently delete a sub-account by ID; deleting the last one deletes the organization (requires `MAILTRAP_ORGANIZATION_ID`).
 
 Tools use input schemas (JSON Schema format) for MCP; handlers may validate input with Zod. Response format follows the MCP protocol.

README.md

@@ -25,7 +25,7 @@ Before using this MCP server, you need to:
 - `DEFAULT_FROM_EMAIL` - Default sender email when `from` is not provided to send-email, send-sandbox-email, or the batch-send-\* tools (where it fills `base.from`). Enables switching sender per call via the `from` parameter.
 - `MAILTRAP_SANDBOX_ID` - Default sandbox ID for sandbox tools when `sandbox_id` is not provided. Enables switching between sandboxes per call via the `sandbox_id` parameter.
 - `MAILTRAP_TEST_INBOX_ID` - Default test inbox ID for sandbox tools when `test_inbox_id` is not provided. Enables switching between inboxes per call via the `test_inbox_id` parameter. Legacy alias for `MAILTRAP_SANDBOX_ID`, still honored as a fallback.
-- `MAILTRAP_ORGANIZATION_ID` - Required for organization tools (`list-sub-accounts`, `create-sub-account`).
+- `MAILTRAP_ORGANIZATION_ID` - Required for organization tools (`list-sub-accounts`, `create-sub-account`, `delete-sub-account`).
 - `MAILTRAP_ORGANIZATION_API_TOKEN` - Organization-scoped API token. Required for organization tools (separate from `MAILTRAP_API_TOKEN`).
 
 ## Quick Install
@@ -1184,6 +1184,14 @@ Create a new sub-account under the organization. Requires `MAILTRAP_ORGANIZATION
 
 - `name` (required): Display name for the new sub-account
 
+### delete-sub-account
+
+Permanently delete a sub-account by ID, removing all of its data. Deleting the last sub-account deletes the organization; a repeated call returns 404. Requires `MAILTRAP_ORGANIZATION_ID` env var and sub-account management permissions.
+
+**Parameters:**
+
+- `sub_account_id` (required): ID of the sub-account to delete
+
 ### list-inbound-folders
 
 List all inbound folders in the account. Returns a formatted summary.

src/server.ts

@@ -248,6 +248,8 @@ import {
   listSubAccountsSchema,
   createSubAccount,
   createSubAccountSchema,
+  deleteSubAccount,
+  deleteSubAccountSchema,
 } from "./tools/organizations";
 import {
   listInboundFolders,
@@ -1313,6 +1315,16 @@ const tools = [
       destructiveHint: false,
     },
   },
+  {
+    name: "delete-sub-account",
+    description:
+      "Permanently delete a sub-account by ID, removing all of its data. Deleting the last sub-account deletes the organization; a repeated call returns 404. Requires `MAILTRAP_ORGANIZATION_ID` and sub-account management permissions.",
+    inputSchema: deleteSubAccountSchema,
+    handler: deleteSubAccount,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
   {
     name: "list-inbound-folders",
     description: "List all inbound folders in the account.",

src/tools/organizations/__tests__/deleteSubAccount.test.ts

@@ -0,0 +1,59 @@
+import deleteSubAccount from "../deleteSubAccount";
+import { getOrganizationClient } from "../../../client";
+
+const mockClient = {
+  organizations: {
+    subAccounts: {
+      delete: jest.fn(),
+    },
+  },
+};
+
+jest.mock("../../../client", () => ({
+  getOrganizationClient: jest.fn(() => mockClient),
+}));
+
+describe("deleteSubAccount", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (getOrganizationClient as jest.Mock).mockReturnValue(mockClient);
+  });
+
+  it("deletes the sub-account via the organization client and confirms deletion", async () => {
+    mockClient.organizations.subAccounts.delete.mockResolvedValue(undefined);
+
+    const result = await deleteSubAccount({ sub_account_id: 99 });
+
+    expect(getOrganizationClient).toHaveBeenCalledWith();
+    expect(mockClient.organizations.subAccounts.delete).toHaveBeenCalledWith(
+      99
+    );
+    expect(result.content[0].text).toContain('"sub_account_id": 99');
+    expect(result.content[0].text).toContain('"deleted": true');
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("rejects invalid input before calling the SDK", async () => {
+    const result = await deleteSubAccount({ sub_account_id: "abc" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain(
+      "Failed to delete sub-account: Invalid input:"
+    );
+    expect(result.content[0].text).toContain("sub_account_id");
+    expect(mockClient.organizations.subAccounts.delete).not.toHaveBeenCalled();
+  });
+
+  it("surfaces API errors", async () => {
+    mockClient.organizations.subAccounts.delete.mockRejectedValue(
+      new Error("Not Found")
+    );
+
+    const result = await deleteSubAccount({ sub_account_id: 99 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe(
+      "Failed to delete sub-account: Not Found"
+    );
+  });
+});

src/tools/organizations/deleteSubAccount.ts

@@ -0,0 +1,41 @@
+import { getOrganizationClient } from "../../client";
+import { deleteSubAccountZod } from "./schemas/deleteSubAccount";
+import {
+  buildErrorResponse,
+  buildSuccessResponse,
+  ToolResponse,
+} from "../utils/responses";
+
+async function deleteSubAccount(raw: unknown): Promise<ToolResponse> {
+  const parsed = deleteSubAccountZod.safeParse(raw);
+  if (!parsed.success) {
+    const msg = parsed.error.errors
+      .map((e) => `${e.path.join(".")}: ${e.message}`)
+      .join("; ");
+    return buildErrorResponse(
+      "delete sub-account",
+      new Error(`Invalid input: ${msg}`)
+    );
+  }
+
+  const subAccountId = parsed.data.sub_account_id;
+
+  try {
+    const mailtrap = getOrganizationClient();
+
+    // TODO: drop the cast after bumping mailtrap to the release that ships subAccounts.delete
+    const subAccounts = mailtrap.organizations.subAccounts as unknown as {
+      delete(id: number): Promise<void>;
+    };
+
+    await subAccounts.delete(subAccountId);
+
+    return buildSuccessResponse(
+      JSON.stringify({ sub_account_id: subAccountId, deleted: true }, null, 2)
+    );
+  } catch (error) {
+    return buildErrorResponse("delete sub-account", error);
+  }
+}
+
+export default deleteSubAccount;

src/tools/organizations/index.ts

@@ -2,10 +2,14 @@ import listSubAccountsSchema from "./schemas/listSubAccounts";
 import listSubAccounts from "./listSubAccounts";
 import createSubAccountSchema from "./schemas/createSubAccount";
 import createSubAccount from "./createSubAccount";
+import deleteSubAccountSchema from "./schemas/deleteSubAccount";
+import deleteSubAccount from "./deleteSubAccount";
 
 export {
   listSubAccountsSchema,
   listSubAccounts,
   createSubAccountSchema,
   createSubAccount,
+  deleteSubAccountSchema,
+  deleteSubAccount,
 };

src/tools/organizations/schemas/deleteSubAccount.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+const deleteSubAccountSchema = {
+  type: "object",
+  properties: {
+    sub_account_id: {
+      type: "number",
+      description: "ID of the sub-account to delete.",
+    },
+  },
+  required: ["sub_account_id"],
+  additionalProperties: false,
+};
+
+export const deleteSubAccountZod = z
+  .object({
+    sub_account_id: z.number().int().positive(),
+  })
+  .strict();
+
+export default deleteSubAccountSchema;

src/types/mailtrap.ts

@@ -894,6 +894,10 @@ export interface CreateSubAccountRequest {
   name: string;
 }
 
+export interface DeleteSubAccountRequest {
+  sub_account_id: number;
+}
+
 // --- Sending domain types ---
 
 export interface UpdateSendingDomainParams {