### Example usage of sending domain functions with setup instructions

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-sendingDomains.md

Shows how to create, update, and get sending domains using the Mailtrap API. Includes Zod validation error handling when updating with no settings, and demonstrates retrieving setup instructions with `include_setup_instructions: true`.

```typescript
import createSendingDomain from "./createSendingDomain.js";
import updateSendingDomain from "./updateSendingDomain.js";

// Create (response includes DNS setup instructions):
await createSendingDomain({ domain_name: "example.com" });

// Update with Zod validation error handling:
const res = await updateSendingDomain({ sending_domain_id: 5 });
console.log(res.isError); // true — "Provide at least one setting to update."

await updateSendingDomain({
  sending_domain_id: 5,
  open_tracking_enabled: true,
  click_tracking_enabled: true,
});

// Get with instructions:
await getSendingDomain({ sending_domain_id: 5, include_setup_instructions: true });
```

--------------------------------

### MCP server bootstrap example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/server.md

Standard MCP server bootstrap equivalent to src/index.ts. It creates the server, starts it, and handles fatal errors by logging and exiting with code 1.

```ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { createServer, startServer } from "./server.js";

// Standard MCP server bootstrap (equivalent to src/index.ts):
async function main() {
  const server: Server = createServer();
  await startServer(server); // blocks serving stdio JSON-RPC
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});
```

--------------------------------

### Example usage of address normalizers

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/utils-mailtrapAddresses.md

Example demonstrating the usage of buildFromAddress, normalizeToRecipients, normalizeAddressList, and parseSandboxTo with sample inputs and expected outputs.

```typescript
import {
  buildFromAddress,
  normalizeToRecipients,
  normalizeAddressList,
  parseSandboxTo,
} from "../utils/mailtrapAddresses.js";

buildFromAddress(undefined, process.env.DEFAULT_FROM_EMAIL);
// → { email: "default@example.com" }  or  throws if no env var

normalizeToRecipients(["a@b.com", { email: "c@d.com", name: "C D" }]);
// → [{ email: "a@b.com" }, { email: "c@d.com", name: "C D" }]

normalizeAddressList('"[{\"email\":\"a@b.com\"}]"'); // JSON-stringified array
// → [{ email: "a@b.com" }]

parseSandboxTo("a@b.com, c@d.com");
// → [{ email: "a@b.com" }, { email: "c@d.com" }]
```

--------------------------------

### Install Mailtrap MCP server with Smithery CLI

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Install the Mailtrap MCP server using the Smithery CLI. Smithery automatically handles client configuration and provides an interactive setup process, making it the easiest way to get started with MCP servers locally.

```bash
npx @smithery/cli install mailtrap
```

--------------------------------

### Install dependencies with npm

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Install project dependencies.

```bash
npm install
```

--------------------------------

### Example usage of companyInfo tools

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-companyInfo.md

Shows how to read, create, and update company info. Includes error handling for invalid update input and a partial update example.

```typescript
import getCompanyInfo from "./getCompanyInfo.js";
import createCompanyInfo from "./createCompanyInfo.js";
import updateCompanyInfo from "./updateCompanyInfo.js";

// Read current compliance info:
const res = await getCompanyInfo({ sending_domain_id: 5 });
const info = JSON.parse(res.content[0].text); // CompanyInfo | null-ish

// Set compliance info:
await createCompanyInfo({
  sending_domain_id: 5,
  name: "Acme Inc.",
  address: "1 Main St",
  city: "Springfield",
  country: "US",
  zip_code: "12345",
  website_url: "https://acme.example",
  info_level: "business",
});

// Error handling — update with no fields is rejected by the Zod refine:
const bad = await updateCompanyInfo({ sending_domain_id: 5 });
console.log(bad.isError); // true — "Invalid input: Provide at least one field to update."

// Partial update:
await updateCompanyInfo({ sending_domain_id: 5, phone: "+1-555-0100" });
```

--------------------------------

### requireClient usage example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/client.md

Example usage of requireClient with a feature label. It retrieves the default client and then lists testing projects.

```ts
const mailtrap = requireClient("sandbox projects");
const projects = await mailtrap.testing.projects.getList();
```

--------------------------------

### Template tool usage example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-templates.md

Example showing how to use createTemplate, getTemplate, and updateTemplate. Demonstrates basic creation, validation error handling (returns isError instead of throwing), and updating a template.

```typescript
import createTemplate from "./createTemplate.js";
import getTemplate from "./getTemplate.js";

// Basic:
const created = await createTemplate({
  name: "Order confirmation",
  subject: "Your order #123",
  html: "<h1>Thanks!</h1>",
  category: "Transactional",
});

// Error handling (validation error is reported, not thrown):
const bad = await createTemplate({ name: "x", subject: "y" }); // no body
console.log(bad.isError); // true — "At least one of 'html' or 'text' ..."

// Get and update:
await getTemplate({ template_id: created_result_id });
await updateTemplate({ template_id: 1, subject: "New subject", text: "Hello" });
```

--------------------------------

### Example usage of buildUserAgent and formatClientInfo

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/utils-userAgent.md

Shows how to import and use the exported functions. Demonstrates the output for a client with name and version, and for undefined client info.

```typescript
import { buildUserAgent, formatClientInfo, McpClientInfo } from "./userAgent.js";

const info: McpClientInfo = { name: "Claude Desktop", version: "1.5.3" };
formatClientInfo(info);       // "Claude Desktop/1.5.3"
buildUserAgent(info);
// "mailtrap-mcp/0.9.0 (+https://github.com/mailtrap/mailtrap-mcp) (client: Claude Desktop/1.5.3)"
buildUserAgent(undefined);    // "mailtrap-mcp/0.9.0 (+https://github.com/mailtrap/mailtrap-mcp)"
```

--------------------------------

### Example usage of organization tools

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-organizations.md

Shows how to import and use listSubAccounts and createSubAccount, handle errors, and directly catch client construction errors.

```typescript
import listSubAccounts from "./listSubAccounts.js";
import createSubAccount from "./createSubAccount.js";

// List organization sub-accounts:
const res = await listSubAccounts();
if (res.isError) {
  console.log(res.content[0].text); // e.g. "Failed to list sub-accounts: MAILTRAP_ORGANIZATION_ID environment variable is required for organization tools"
} else {
  const subAccounts = JSON.parse(res.content[0].text); // SubAccount[]
}

// Create:
await createSubAccount({ name: "Client A" });

// Client construction errors are catchable directly too:
import { getOrganizationClient } from "../../client.js";
try {
  getOrganizationClient();
} catch (error) {
  console.log((error as Error).message);
}
```

--------------------------------

### Example: composing address schemas into a tool schema

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-address-schemas.md

Example of composing the address schemas into a tool schema. Imports the default and named exports and uses them for from, to, cc, and bcc properties.

```ts
import mailtrapAddressParamSchema, {
  mailtrapAddressListParamSchema,
  mailtrapFromParamSchema,
  mailtrapCcParamSchema,
  mailtrapBccParamSchema,
} from "../schemas/mailtrapAddressParam";

const myToolSchema = {
  type: "object",
  properties: {
    from: mailtrapFromParamSchema,
    to: mailtrapAddressListParamSchema,
    cc: mailtrapCcParamSchema,
    bcc: mailtrapBccParamSchema,
  },
  additionalProperties: false,
};
```

--------------------------------

### Tools registry entry example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/server.md

Example entry from the tools registry array. Each entry is a plain object with name, description, inputSchema, handler, and annotations. annotations uses only readOnlyHint and destructiveHint, always set explicitly.

```ts
{
  name: "send-email",
  description: "Send an email to your recipient email address using Mailtrap Email API...",
  inputSchema: sendEmailSchema,
  handler: sendEmail,
  annotations: { destructiveHint: false },
}
```

--------------------------------

### Usage example for tracking opt-out tools

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-trackingOptOuts.md

Shows how to import and use the create, list, and delete tracking opt-out handlers. Includes error handling for missing domain_id and pagination hint detection.

```typescript
import createTrackingOptOut from "./createTrackingOptOut.js";
import listTrackingOptOuts from "./listTrackingOptOuts.js";
import deleteTrackingOptOut from "./deleteTrackingOptOut.js";

// Exclude an address:
await createTrackingOptOut({ email: "no-tracking@example.com", domain_id: 5 });

// List and paginate:
const res = await listTrackingOptOuts({ email: "no-tracking@example.com" });
if (res.content[0].text.includes("More results available")) {
  // parse last_id hint and call listTrackingOptOuts({ last_id })
}

// Error handling — missing domain_id is caught by Zod:
const bad = await createTrackingOptOut({ email: "x@y.com" });
console.log(bad.isError); // true — "Invalid input: domain_id: Required"

// Re-enable tracking for the address:
await deleteTrackingOptOut({ tracking_opt_out_id: "uuid" });
```

--------------------------------

### Create and update webhook example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-webhooks.md

Example usage of createWebhook and updateWebhook. Creates an inbound-receiving webhook and extracts the signing_secret from the response, noting it is only returned on creation. Then updates a mutable field (url and active) for webhook_id 7.

```ts
import createWebhook from "./createWebhook.js";
import updateWebhook from "./updateWebhook.js";

// Create an inbound-receiving webhook; keep the signing secret:
const res = await createWebhook({
  url: "https://app.example/hooks/mailtrap",
  webhook_type: "inbound_receiving",
  payload_format: "json",
});
const { signing_secret } = JSON.parse(res.content[0].text); // store it — only returned here

// Update a mutable field only:
await updateWebhook({ webhook_id: 7, url: "https://app.example/hooks/v2", active: false });
```

--------------------------------

### Example usage of buildSuccessResponse and buildErrorResponse

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-responses.md

Complete example showing how to use both helpers in a tool handler. It wraps a potentially throwing operation in a try/catch, returning a success response with pretty-printed JSON or an error response with a lowercase gerund action phrase. The comment shows the resulting error envelope.

```typescript
import {
  buildSuccessResponse,
  buildErrorResponse,
  ToolResponse,
} from "../utils/responses.js";

async function myTool(): Promise<ToolResponse> {
  try {
    const data = await fetchSomething(); // may throw
    return buildSuccessResponse(JSON.stringify(data, null, 2));
  } catch (error) {
    return buildErrorResponse("fetch something", error);
    // → { content: [{ type: "text", text: "Failed to fetch something: ..." }], isError: true }
  }
}
```

--------------------------------

### Unknown tool call error example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/server.md

Example JSON-RPC request calling an unknown tool, which results in an MCP error rather than a tool result. The error message is 'Unknown tool: nope'.

```json
{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "nope", "arguments": {} } }
// → error: Unknown tool: nope
```

--------------------------------

### Run MCP Inspector browser UI

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Starts the MCP Inspector browser UI. The Inspector prints a URL like http://localhost:6274; open it, switch to the Tools tab, pick a tool (e.g. get-template), fill parameters as JSON, and hit Run.

```bash
npm run dev
```

--------------------------------

### Enable debug logging with DEBUG=true

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Enable debug logging by setting the DEBUG environment variable to true when starting the server. The server writes logs to stderr so stdout remains reserved for JSON-RPC frames.

```bash
# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js
```

--------------------------------

### TypeScript type and function signatures for DNS records and setup instructions

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-sendingDomains.md

Defines the `DnsRecord` type and the signatures for `formatSetupInstructionsDnsTable` and `buildSetupInstructionsSection`. `buildSetupInstructionsSection` renders a markdown section with DNS records, and `formatSetupInstructionsDnsTable` returns '(no DNS records to add)' for empty input.

```typescript
export type DnsRecord = {
  key: string;
  type: string;
  name: string;
  value: string;
  status: string;
};

export function formatSetupInstructionsDnsTable(dnsRecords: DnsRecord[]): string
export function buildSetupInstructionsSection(
  domainName: string,
  dnsRecords: DnsRecord[] | undefined
): string
```

--------------------------------

### Sandbox email tools example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-sandbox.md

Example usage of sandbox email tools. Uses MAILTRAP_TEST_INBOX_ID as fallback for sendSandboxEmail and MAILTRAP_SANDBOX_ID for markSandboxAsRead. Shows optional report flags for showEmailMessage and the error path when resolveSandboxId is called without an environment variable.

```ts
import sendSandboxEmail from "./sendSandboxEmail.js";
import showEmailMessage from "./showSandboxEmailMessage.js";
import markSandboxAsRead from "./markSandboxAsRead.js";

// Send a sandbox email (MAILTRAP_TEST_INBOX_ID fallback):
await sendSandboxEmail({
  to: "receiver@example.com",
  subject: "Test",
  html: "<b>Hi</b>",
});

// Message details with optional reports:
await showEmailMessage({
  message_id: 9876,
  include_spam_report: true,
  include_html_analysis: true,
});

// Sandbox-scoped action (MAILTRAP_SANDBOX_ID fallback):
await markSandboxAsRead({ sandbox_id: 1234 });

// Error path (missing sandbox resolution):
const res = await resolveSandboxId(undefined); // throws if no env var set
```

--------------------------------

### Suppression Tools Usage Example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-suppressions.md

Demonstrates how to create a suppression, list suppressions by email, and handle validation errors when required fields are missing.

```ts
import createSuppression from "./createSuppression.js";
import listSuppressions from "./listSuppressions.js";

// Suppress an address:
await createSuppression({
  email: "spammer@example.com",
  domain_id: 5,
  sending_stream: "transactional",
  type: "manual import",
});

// Search:
await listSuppressions({ email: "spammer@example.com" });

// Validation error handling:
const res = await createSuppression({ email: "x@y.com", domain_id: 5 }); // missing sending_stream
console.log(res.isError); // true — "Invalid input: sending_stream: Required"
```

--------------------------------

### getSendingStats usage example

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-stats.md

Shows how to call `getSendingStats` with aggregated, broken-down, and invalid inputs. Invalid input returns an error result instead of throwing.

```ts
import getSendingStats from "./getSendingStats.js";

// Aggregated stats:
await getSendingStats({
  start_date: "2025-01-01",
  end_date: "2025-01-31",
});

// Broken down and filtered:
await getSendingStats({
  start_date: "2025-01-01",
  end_date: "2025-01-31",
  breakdown: "by_domain",
  sending_domain_ids: [42, 43],
  sending_streams: ["transactional"],
});

// Invalid input is reported, not thrown:
const res = await getSendingStats({ end_date: "2025-01-31" }); // missing start_date
console.log(res.isError); // true
```

--------------------------------

### Create, schedule, and get stats for an email campaign

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-emailCampaigns.md

Shows how to create a draft email campaign, schedule it with a Zod-validated datetime window, and retrieve its stats. The schedule call returns an object with an isError flag that is true when the datetime is in the past or more than one month ahead.

```ts
import createEmailCampaign from "./createEmailCampaign.js";
import scheduleEmailCampaign from "./scheduleEmailCampaign.js";
import getEmailCampaignStats from "./getEmailCampaignStats.js";

// Create a draft:
await createEmailCampaign({
  name: "Spring sale",
  domain_id: 5,
  from_local_part: "offers",
  template_attributes: { subject: "Spring sale — up to 50% off", body_html: "<p>Hi {{first_name}}</p>" },
  delivery_mode: "gradual",
  delivery_options: { emails_per_hour: 100 },
});

// Schedule (Zod-validated window):
const res = await scheduleEmailCampaign({ email_campaign_id: 3, datetime: "2025-01-01T00:00:00Z" });
console.log(res.isError); // true if in the past or > 1 month ahead

// Stats:
await getEmailCampaignStats({ email_campaign_id: 3, start_date: "2025-01-01", end_date: "2025-01-31" });
```

--------------------------------

### Use Mailtrap contacts tools (create, list, field, import, export)

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-contacts.md

Imports and invokes the Mailtrap MCP contacts tools: createContact, listContactLists, createContactField, createContactImport, and createContactExport. The example creates a contact with fields and list IDs, searches lists, defines a text field, bulk imports contacts, and exports contacts filtered by subscription status.

```typescript
import createContact from "./contacts/createContact.js";
import listContactLists from "./contactLists/listContactLists.js";
import createContactField from "./contactFields/createContactField.js";
import createContactImport from "./contactImports/createContactImport.js";
import createContactExport from "./contactExports/createContactExport.js";

// Create a contact with fields and lists:
await createContact({
  email: "user@example.com",
  fields: { first_name: "Ada", vip: true },
  list_ids: [1, 2],
});

// Search contact lists:
await listContactLists({ search: "news" });

// Define a contact field:
await createContactField({ name: "First name", merge_tag: "first_name", data_type: "text" });

// Bulk import:
await createContactImport({
  contacts: [
    { email: "a@example.com", fields: { first_name: "A" }, list_ids_included: [1] },
    { email: "b@example.com" },
  ],
});

// Export:
await createContactExport({
  filters: [{ name: "subscription_status", operator: "equal", value: "subscribed" }],
});
```

--------------------------------

### startServer() function signature

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/server.md

Signature of the startServer function that connects the server to a stdio transport. It takes the server returned by createServer() and returns a Promise that resolves after the transport is connected.

```ts
export async function startServer(server: Server): Promise<void>
```

--------------------------------

### reviveJsonString() function signature

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/utils-mailtrapAddresses.md

Internal function that attempts to JSON.parse strings starting with '[' or '{', returning the parsed value or the original string if parsing fails. Non-strings pass through unchanged.

```typescript
function reviveJsonString(value: unknown): unknown
```

--------------------------------

### Run MCPB server in development

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Development command for the MCPB server with the MCP Inspector.

```bash
npm run dev:mcpb
```

--------------------------------

### Sending Emails and Batch Operations

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-sendEmail.md

Demonstrates basic email sending, handling template conflicts, and performing batch transactional email sends.

```ts
import sendEmail from "./sendEmail.js";
import batchSendTransactionalEmail from "./batchSendTransactionalEmail.js";

// Basic send:
const result = await sendEmail({
  from: { email: "sender@example.com", name: "Sender" },
  to: [{ email: "user@example.com" }],
  subject: "Hello",
  html: "<p>Hi!</p>",
  category: "Welcome",
});

// Error path (template/conflicts surface as isError: true, not throws):
const bad = await sendEmail({
  template_uuid: "abcd-1234",
  subject: "Conflicting subject", // rejected
});
console.log(bad.isError); // true

// Batch send:
await batchSendTransactionalEmail({
  base: { from: "sender@example.com", subject: "Receipt", html: "<b>Thanks</b>" },
  requests: [
    { to: "a@example.com" },
    { to: "b@example.com", html: "<b>Thanks, B!</b>" },
  ],
});
```

--------------------------------

### MCP Server construction with capabilities

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/server.md

Constructs the MCP Server with the configured name and version, and declares capabilities for tools, prompts, and resources. This is the core of createServer().

```ts
new Server(
  {
    name: CONFIG.MCP_SERVER_NAME,       // "mailtrap-mcp-server"
    version: CONFIG.MCP_SERVER_VERSION, // "0.9.0"
  },
  {
    capabilities: {
      tools: {},
      prompts: {},
      resources: {},
    },
  }
)
```

--------------------------------

### Configure Mailtrap MCP with asdf for Claude Desktop or Cursor

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Alternative configuration for Claude Desktop or Cursor when using `asdf` for Node.js management. Uses an absolute path to the Node executable and sets `ASDF_*` environment variables (example for Mac).

```json
{
  "mcpServers": {
    "mailtrap": {
      "command": "/Users/<username>/.asdf/shims/node",
      "args": ["/path/to/mailtrap-mcp/dist/index.js"],
      "env": {
        "PATH": "/Users/<username>/.asdf/shims:/usr/bin:/bin",
        "ASDF_DIR": "/opt/homebrew/opt/asdf/libexec",
        "ASDF_DATA_DIR": "/Users/<username>/.asdf",
        "ASDF_NODEJS_VERSION": "20.6.1",
        "MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
        "DEFAULT_FROM_EMAIL": "your_sender@example.com",
        "MAILTRAP_ACCOUNT_ID": "your_account_id",
        "MAILTRAP_TEST_INBOX_ID": "your_test_inbox_id"
      }
    }
  }
}
```

--------------------------------

### Build the bundle

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Builds the bundle before running tools against a real Mailtrap account. Required before using the MCP Inspector or CLI mode.

```bash
npm run build
```

--------------------------------

### Using listEmailLogs and getEmailLogMessage

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-emailLogs.md

Shows how to import and use the listEmailLogs and getEmailLogMessage functions. listEmailLogs accepts filters like status, from_email, and sent_after; getEmailLogMessage requires a message_id and optionally include_content. The pagination hint in the list response indicates using search_after with a cursor to fetch more results.

```ts
import listEmailLogs from "./listEmailLogs.js";
import getEmailLogMessage from "./getEmailLogMessage.js";

// List logs with filters:
await listEmailLogs({
  status: "delivered",
  from_email: "sender@example.com",
  sent_after: "2025-01-01T00:00:00Z",
});

// Get a single message with content:
await getEmailLogMessage({ message_id: "uuid-here", include_content: true });

// Pagination hint from a list response:
const res = await listEmailLogs({});
// res.content[0].text includes: Next page: use search_after: "<cursor>" to fetch more.
```

--------------------------------

### Build and pack MCPB bundle

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Commands to build, inspect, and optionally sign an MCPB bundle for distribution. Creates mailtrap-mcp.mcpb using the repository manifest.json and built artifacts in dist/.

```bash
# Build TypeScript and pack the MCPB bundle
npm run mcpb:pack

# Inspect bundle metadata
npm run mcpb:info

# Sign the bundle for distribution (optional)
npm run mcpb:sign
```

--------------------------------

### createEmailCampaign handler

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-emailCampaigns.md

Handler for the createEmailCampaign tool. Parses input with createEmailCampaignZod (strict) and calls mailtrap.emailCampaigns.create(parsed.data). The schema requires name, domain_id, from_local_part, and template_attributes; template_attributes.subject is required (max 255 chars, supports {{tag}} merge tags). Optional fields include template_attributes.body_html/body_text/merge_tags, from_display_name, reply_to, delivery_mode ("rapid"|"gradual"), delivery_options.emails_per_hour, contact_list_ids, and contact_segment_ids. Created campaigns start in draft state.

```typescript
async function createEmailCampaign(raw: unknown): Promise<ToolResponse>
```

--------------------------------

### Run MCPB server

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Runs the MCPB server directly with Node or via the provided binary.

```bash
# Run the MCPB server directly
node dist/mcpb-server.js

# Or use the provided binary
mailtrap-mcpb-server
```

--------------------------------

### Account Admin Tool Operations

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/_autodocs/api-reference/tools-accountAdmin.md

Demonstrates creating an API token, updating user permissions for inboxes, and handling a validation error when removing account access.

```ts
import listAccounts from "./accounts/listAccounts.js";
import getBillingUsage from "./billing/getBillingUsage.js";
import createApiToken from "./apiTokens/createApiToken.js";
import bulkUpdatePermissions from "./permissions/bulkUpdatePermissions.js";

// Create an API token (store the returned secret immediately):
await createApiToken({ name: "ci-deploy", resources: [{ resource_type: "account", resource_id: 1, access_level: 100 }] });

// Grant a user access to two inboxes:
await bulkUpdatePermissions({
  account_access_id: 55,
  permissions: [
    { resource_id: 10, resource_type: "inbox", access_level: 100 },
    { resource_id: 11, resource_type: "inbox", access_level: 10 },
  ],
});

// Validation error path:
const res = await removeAccountAccess({ account_access_id: -3 });
console.log(res.isError); // true — "Invalid input: account_access_id: ..."
```

--------------------------------

### create-contact-import

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

Bulk import contacts into the account.

```APIDOC
## create-contact-import

### Description
Bulk import contacts. Returns an import job record; poll its status with `get-contact-import`.

### Parameters
- `contacts` (array) - Required - Array of contact entries. Each entry needs:
  - `email` (string) - Required - Contact email address
  - `fields` (object) - Optional - Custom field values keyed by merge tag (string or number values)
  - `list_ids_included` (array) - Optional - List IDs to add the contact to
  - `list_ids_excluded` (array) - Optional - List IDs to remove the contact from
```

--------------------------------

### Run MCP Inspector CLI

Source: https://github.com/mailtrap/mailtrap-mcp/blob/main/README.md

One-shot calls from the shell using the Inspector CLI mode. Pass flags after `--` so npm forwards them verbatim. Requires MAILTRAP_API_TOKEN and MAILTRAP_ACCOUNT_ID exported.

```bash
# List all tools
npm run mcp:cli -- --method tools/list

# Call a tool — flags after the `--`
npm run mcp:cli -- \
  --method tools/call \
  --tool-name get-template \
  --tool-arg template_id=12345

# Multiple --tool-arg flags for tools with several params
npm run mcp:cli -- \
  --method tools/call \
  --tool-name send-sending-domain-setup-instructions \
  --tool-arg sending_domain_id=3938 \
  --tool-arg email=devops@example.com
```