Merge pull request #95 from mailtrap/add-missing-contact-import-export-tools

Add missing contact import export tools

Author: IgorDobryn

CLAUDE.md

@@ -155,4 +155,12 @@ Schema files define a JSON Schema–shaped object for MCP; optional Zod schemas
 - **update-contact-field**: Update name, merge_tag, or data_type of an existing contact field.
 - **delete-contact-field**: Permanently delete a contact field by ID.
 
+
+#### Contact Imports & Exports
+
+- **create-contact-import**: Bulk import contacts (array of `{ email, fields?, list_ids_included?, list_ids_excluded? }`). Returns an import job.
+- **get-contact-import**: Get the status of a contact import job (`created`/`started`/`finished`/`failed`) and counts.
+- **create-contact-export**: Export contacts matching AND-combined filters (`name`/`operator`/`value`). Returns an export job; poll for download URL.
+- **get-contact-export**: Get the status of a contact export job. `url` is populated when `status: finished`.
+
 Tools use input schemas (JSON Schema format) for MCP; handlers may validate input with Zod. Response format follows the MCP protocol.

README.md

@@ -788,6 +788,45 @@ Permanently delete a contact field definition by ID.
 
 - `field_id` (required): ID of the contact field to delete
 
+### create-contact-import
+
+Bulk import contacts. Returns an import job record; poll its status with `get-contact-import`.
+
+**Parameters:**
+
+- `contacts` (required): Array of contact entries. Each entry needs:
+  - `email` (required): Contact email address
+  - `fields` (optional): Custom field values keyed by merge tag (string or number values)
+  - `list_ids_included` (optional): List IDs to add the contact to
+  - `list_ids_excluded` (optional): List IDs to remove the contact from
+
+### get-contact-import
+
+Get the status of a contact import job (created/started/finished/failed) with created/updated/over-limit counts.
+
+**Parameters:**
+
+- `import_id` (required): ID of the contact import job
+
+### create-contact-export
+
+Export contacts matching a set of AND-combined filters. Returns an export job record; poll status with `get-contact-export` to retrieve the download URL once `status` is `finished`.
+
+**Parameters:**
+
+- `filters` (required): Array of filter objects. Each has:
+  - `name` (required): Field to filter on (`list_id`, `subscription_status`, `email`, etc.)
+  - `operator` (required): One of `equal`, `not_equal`, `contains`, `not_contains`, `is_empty`, `is_not_empty`
+  - `value` (required): Comparison value (string, number, boolean, or array)
+
+### get-contact-export
+
+Get the status of a contact export job. Once `status` is `finished`, the `url` field holds the CSV download link.
+
+**Parameters:**
+
+- `export_id` (required): ID of the contact export job
+
 ## Development
 
 1. Clone the repository:

src/server.ts

@@ -152,6 +152,18 @@ import {
   deleteContactField,
   deleteContactFieldSchema,
 } from "./tools/contactFields";
+import {
+  createContactImport,
+  createContactImportSchema,
+  getContactImport,
+  getContactImportSchema,
+} from "./tools/contactImports";
+import {
+  createContactExport,
+  createContactExportSchema,
+  getContactExport,
+  getContactExportSchema,
+} from "./tools/contactExports";
 
 // Define the tools registry
 const tools = [
@@ -789,6 +801,46 @@ const tools = [
       destructiveHint: true,
     },
   },
+  {
+    name: "create-contact-import",
+    description:
+      "Bulk import contacts. Returns an import job record; poll status via `get-contact-import`.",
+    inputSchema: createContactImportSchema,
+    handler: createContactImport,
+    annotations: {
+      destructiveHint: true,
+    },
+  },
+  {
+    name: "get-contact-import",
+    description:
+      "Get the status of a contact import job, including created/updated/over-limit counts.",
+    inputSchema: getContactImportSchema,
+    handler: getContactImport,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
+  {
+    name: "create-contact-export",
+    description:
+      "Export contacts matching a set of AND-combined filters. Returns an export job; poll status with `get-contact-export` to retrieve the download URL.",
+    inputSchema: createContactExportSchema,
+    handler: createContactExport,
+    annotations: {
+      destructiveHint: false,
+    },
+  },
+  {
+    name: "get-contact-export",
+    description:
+      "Get the status of a contact export job. Once `status` is `finished`, the `url` field holds the download link.",
+    inputSchema: getContactExportSchema,
+    handler: getContactExport,
+    annotations: {
+      readOnlyHint: true,
+    },
+  },
 ];
 
 export function createServer(): Server {

src/tools/contactExports/__tests__/createContactExport.test.ts

@@ -0,0 +1,71 @@
+import createContactExport from "../createContactExport";
+import { requireClient } from "../../../client";
+
+const mockClient = {
+  contactExports: {
+    create: jest.fn(),
+  },
+};
+
+jest.mock("../../../client", () => ({
+  requireClient: jest.fn(() => mockClient),
+}));
+
+describe("createContactExport", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (requireClient as jest.Mock).mockReturnValue(mockClient);
+  });
+
+  it("submits the export and returns the response as JSON", async () => {
+    mockClient.contactExports.create.mockResolvedValue({
+      id: 42,
+      status: "started",
+      created_at: "2026-05-20T10:00:00Z",
+      updated_at: "2026-05-20T10:00:00Z",
+      url: null,
+    });
+
+    const result = await createContactExport({
+      filters: [{ name: "list_id", operator: "equal", value: 10 }],
+    });
+
+    expect(requireClient).toHaveBeenCalledWith("contact exports");
+    expect(mockClient.contactExports.create).toHaveBeenCalledWith({
+      filters: [{ name: "list_id", operator: "equal", value: 10 }],
+    });
+    expect(result.content[0].text).toContain('"id": 42');
+    expect(result.content[0].text).toContain('"status": "started"');
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("submits filters without a value for is_empty / is_not_empty operators", async () => {
+    mockClient.contactExports.create.mockResolvedValue({
+      id: 43,
+      status: "started",
+    });
+
+    await createContactExport({
+      filters: [{ name: "email", operator: "is_empty" }],
+    });
+
+    expect(mockClient.contactExports.create).toHaveBeenCalledWith({
+      filters: [{ name: "email", operator: "is_empty" }],
+    });
+  });
+
+  it("surfaces API errors", async () => {
+    mockClient.contactExports.create.mockRejectedValue(
+      new Error("invalid filter")
+    );
+
+    const result = await createContactExport({
+      filters: [{ name: "bad", operator: "equal", value: "x" }],
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe(
+      "Failed to create contact export: invalid filter"
+    );
+  });
+});

src/tools/contactExports/__tests__/getContactExport.test.ts

@@ -0,0 +1,65 @@
+import getContactExport from "../getContactExport";
+import { requireClient } from "../../../client";
+
+const mockClient = {
+  contactExports: {
+    get: jest.fn(),
+  },
+};
+
+jest.mock("../../../client", () => ({
+  requireClient: jest.fn(() => mockClient),
+}));
+
+describe("getContactExport", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (requireClient as jest.Mock).mockReturnValue(mockClient);
+  });
+
+  it("returns the export job as JSON", async () => {
+    mockClient.contactExports.get.mockResolvedValue({
+      id: 42,
+      status: "finished",
+      created_at: "2026-05-20T10:00:00Z",
+      updated_at: "2026-05-20T10:01:30Z",
+      url: "https://example.com/exports/42.csv",
+    });
+
+    const result = await getContactExport({ export_id: 42 });
+
+    expect(requireClient).toHaveBeenCalledWith("contact exports");
+    expect(mockClient.contactExports.get).toHaveBeenCalledWith(42);
+    expect(result.content[0].text).toContain('"id": 42');
+    expect(result.content[0].text).toContain('"status": "finished"');
+    expect(result.content[0].text).toContain(
+      '"url": "https://example.com/exports/42.csv"'
+    );
+    expect(result.isError).toBeUndefined();
+  });
+
+  it("handles a started export with null url", async () => {
+    mockClient.contactExports.get.mockResolvedValue({
+      id: 42,
+      status: "started",
+      created_at: "2026-05-20T10:00:00Z",
+      updated_at: "2026-05-20T10:00:00Z",
+      url: null,
+    });
+
+    const result = await getContactExport({ export_id: 42 });
+
+    expect(result.content[0].text).toContain('"url": null');
+  });
+
+  it("surfaces API errors", async () => {
+    mockClient.contactExports.get.mockRejectedValue(new Error("not found"));
+
+    const result = await getContactExport({ export_id: 99 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toBe(
+      "Failed to get contact export: not found"
+    );
+  });
+});

src/tools/contactExports/createContactExport.ts

@@ -0,0 +1,28 @@
+import { requireClient } from "../../client";
+import {
+  ContactExport,
+  CreateContactExportRequest,
+} from "../../types/mailtrap";
+import {
+  buildErrorResponse,
+  buildSuccessResponse,
+  ToolResponse,
+} from "../utils/responses";
+
+async function createContactExport(
+  params: CreateContactExportRequest
+): Promise<ToolResponse> {
+  try {
+    const mailtrap = requireClient("contact exports");
+
+    const response = (await mailtrap.contactExports.create(
+      params as Parameters<typeof mailtrap.contactExports.create>[0]
+    )) as ContactExport;
+
+    return buildSuccessResponse(JSON.stringify(response, null, 2));
+  } catch (error) {
+    return buildErrorResponse("create contact export", error);
+  }
+}
+
+export default createContactExport;

src/tools/contactExports/getContactExport.ts

@@ -0,0 +1,25 @@
+import { requireClient } from "../../client";
+import { ContactExport, GetContactExportRequest } from "../../types/mailtrap";
+import {
+  buildErrorResponse,
+  buildSuccessResponse,
+  ToolResponse,
+} from "../utils/responses";
+
+async function getContactExport({
+  export_id,
+}: GetContactExportRequest): Promise<ToolResponse> {
+  try {
+    const mailtrap = requireClient("contact exports");
+
+    const response = (await mailtrap.contactExports.get(
+      export_id
+    )) as ContactExport;
+
+    return buildSuccessResponse(JSON.stringify(response, null, 2));
+  } catch (error) {
+    return buildErrorResponse("get contact export", error);
+  }
+}
+
+export default getContactExport;

src/tools/contactExports/index.ts

@@ -0,0 +1,11 @@
+import createContactExportSchema from "./schemas/createContactExport";
+import createContactExport from "./createContactExport";
+import getContactExportSchema from "./schemas/getContactExport";
+import getContactExport from "./getContactExport";
+
+export {
+  createContactExportSchema,
+  createContactExport,
+  getContactExportSchema,
+  getContactExport,
+};

src/tools/contactExports/schemas/createContactExport.ts

@@ -0,0 +1,58 @@
+const createContactExportSchema = {
+  type: "object",
+  properties: {
+    filters: {
+      type: "array",
+      description:
+        "Filters that select which contacts to include in the export. AND-combined.",
+      items: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description:
+              "Field to filter on (e.g. `list_id`, `subscription_status`, `email`).",
+          },
+          operator: {
+            type: "string",
+            enum: [
+              "equal",
+              "not_equal",
+              "contains",
+              "not_contains",
+              "is_empty",
+              "is_not_empty",
+            ],
+            description: "Comparison operator.",
+          },
+          value: {
+            description:
+              "Comparison value. Type depends on the field — string, number, boolean, or array.",
+          },
+        },
+        required: ["name", "operator"],
+        allOf: [
+          {
+            if: {
+              properties: {
+                operator: { enum: ["is_empty", "is_not_empty"] },
+              },
+              required: ["operator"],
+            },
+            then: {
+              not: { required: ["value"] },
+            },
+            else: {
+              required: ["value"],
+            },
+          },
+        ],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["filters"],
+  additionalProperties: false,
+};
+
+export default createContactExportSchema;