内容
[](https://github.com/mailtrap/mailtrap-mcp/actions/workflows/main.yml)
[](https://www.npmjs.com/package/mcp-mailtrap)
# Official Mailtrap MCP Server
The official MCP server for Mailtrap — the email delivery platform. It connects your Mailtrap account to Claude, Cursor, VS Code, and other MCP-compatible AI assistants.
Send transactional and bulk email, test messages safely in Email Sandbox, manage templates, contacts, sending domains, and webhooks, inspect email logs and delivery statistics, troubleshoot deliverability, and manage account resources — all using natural-language prompts.
## Capabilities
- **Email API and SMTP** — Send transactional and bulk email, including batch and template-based messages.
- **Email testing** — Test messages in Email Sandbox and inspect content, headers, attachments, spam scores, and HTML client compatibility.
- **Delivery monitoring** — Search email logs, inspect event history, and analyze delivery, bounce, open, click, and spam rates.
- **Email infrastructure** — Manage sending domains, DNS verification, webhooks, and suppressions.
- **Contacts** — Manage contacts, lists, custom fields, and events, with imports and exports.
- **Account management** — Review billing usage and manage access, permissions, API tokens, and sub-accounts.
## Supported MCP Clients
Works with Claude Desktop, Claude Code, Cursor, VS Code, and any other MCP-compatible client. Setup instructions for each are below.
## Prerequisites
Before using this MCP server, you need to:
1. [Create a Mailtrap account](https://mailtrap.io/signup)
2. [Verify your domain](https://mailtrap.io/sending/domains)
3. Get your API token from [Mailtrap API settings](https://mailtrap.io/api-tokens)
4. Get your Account ID from [Mailtrap account management](https://mailtrap.io/account-management)
**Required Environment Variables:**
- `MAILTRAP_API_TOKEN` - Required for all functionality
- `MAILTRAP_ACCOUNT_ID` - Required for templates, stats, email logs, sandbox list/show, sending domains, and suppressions. Optional only for the send tools (send-email, send-sandbox-email, and the batch-send-\* tools), the email campaign tools, the company info tools, and the tracking opt-out tools.
**Optional (can be passed as tool parameters instead):**
- `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 (test inbox) ID when a tool's `sandbox_id` is not provided (legacy `test_inbox_id` on send/list/show sandbox message tools still accepted). Enables switching inboxes per call via parameters.
- `MAILTRAP_TEST_INBOX_ID` - Legacy alias for `MAILTRAP_SANDBOX_ID`; still read as a fallback for existing configs.
- `MAILTRAP_ORGANIZATION_ID` - Required for organization tools (`list-sub-accounts`, `create-sub-account`).
- `MAILTRAP_ORGANIZATION_API_TOKEN` - Organization-scoped API token. Required for organization tools (separate from `MAILTRAP_API_TOKEN`).
## Quick Install
[](https://cursor.com/en-US/install-mcp?name=mailtrap&config=eyJlbnYiOnsiTUFJTFRSQVBfQVBJX1RPS0VOIjoieW91cl9tYWlsdHJhcF9hcGlfdG9rZW4iLCJERUZBVUxUX0ZST01fRU1BSUwiOiJ5b3VyX3NlbmRlckBleGFtcGxlLmNvbSIsIk1BSUxUUkFQX0FDQ09VTlRfSUQiOiJ5b3VyX2FjY291bnRfaWQiLCJNQUlMVFJBUF9TQU5EQk9YX0lEIjoieW91cl9zYW5kYm94X2lkIn0sImNvbW1hbmQiOiJucHggLXkgbWNwLW1haWx0cmFwIn0%3D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=mailtrap&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-mailtrap%22%5D%2C%22env%22%3A%7B%22MAILTRAP_API_TOKEN%22%3A%22%24%7Binput%3AmailtrapApiToken%7D%22%2C%22DEFAULT_FROM_EMAIL%22%3A%22%24%7Binput%3AsenderEmail%7D%22%2C%22MAILTRAP_ACCOUNT_ID%22%3A%22%24%7Binput%3AmailtrapAccountId%7D%22%2C%22MAILTRAP_SANDBOX_ID%22%3A%22%24%7Binput%3AmailtrapSandboxId%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapApiToken%22%2C%22description%22%3A%22Mailtrap+API+Token%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22senderEmail%22%2C%22description%22%3A%22Sender+Email+Address%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapAccountId%22%2C%22description%22%3A%22Mailtrap+Account+ID%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22mailtrapSandboxId%22%2C%22description%22%3A%22Mailtrap+Sandbox+ID+%28optional%29%22%7D%5D)
### Docker
Run the server over stdio with the [Docker MCP Catalog](https://hub.docker.com/mcp) image:
```bash
docker run --rm -i \
-e MAILTRAP_API_TOKEN="${MAILTRAP_API_TOKEN}" \
-e MAILTRAP_ACCOUNT_ID="${MAILTRAP_ACCOUNT_ID}" \
-e DEFAULT_FROM_EMAIL="${DEFAULT_FROM_EMAIL}" \
-e MAILTRAP_SANDBOX_ID="${MAILTRAP_SANDBOX_ID}" \
-e MAILTRAP_ORGANIZATION_ID="${MAILTRAP_ORGANIZATION_ID}" \
-e MAILTRAP_ORGANIZATION_API_TOKEN="${MAILTRAP_ORGANIZATION_API_TOKEN}" \
mcp/mailtrap
```
See [Prerequisites](#prerequisites) for required and optional environment variables.
To build from this repository: `docker build -t mcp/mailtrap .`
### Smithery CLI
[Smithery](https://smithery.ai) is a registry and installer for MCP servers that works with AI clients.
Install the published server (`mailtrap/mailtrap-mcp`) into a local client (replace the client name as needed):
```bash
npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude
```
See the [Smithery CLI docs](https://smithery.ai/docs/concepts/cli) for other clients (`cursor`, `windsurf`, etc.) and for publishing updates.
## Setup
### Claude Desktop
Use MCPB to install the Mailtrap server. You can find those files in [Releases](https://github.com/mailtrap/mailtrap-mcp/releases). <br>Download .MCPB file and open it. If you have Claude Desktop - it will open it and suggest to configure.
### Claude Desktop or Cursor
Add the following configuration:
```json
{
"mcpServers": {
"mailtrap": {
"command": "npx",
"args": ["-y", "mcp-mailtrap"],
"env": {
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_SANDBOX_ID": "your_sandbox_id"
}
}
}
}
```
If you are using `asdf` for managing Node.js you must use absolute path to executable (example for Mac)
```json
{
"mcpServers": {
"mailtrap": {
"command": "/Users/<username>/.asdf/shims/npx",
"args": ["-y", "mcp-mailtrap"],
"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_SANDBOX_ID": "your_sandbox_id"
}
}
}
}
```
#### Claude Desktop config file location
**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Cursor config file location
**Mac**: `~/.cursor/mcp.json`
**Windows**: `%USERPROFILE%\.cursor\mcp.json`
### VS Code
#### Manually changing config
Run in Command Palette: `Preferences: Open User Settings (JSON)`
Then, in the settings file, add the following configuration:
```json
{
"mcp": {
"servers": {
"mailtrap": {
"command": "npx",
"args": ["-y", "mcp-mailtrap"],
"env": {
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_SANDBOX_ID": "your_sandbox_id"
}
}
}
}
}
```
> [!TIP]
> Don't forget to restart your MCP server after changing the "env" section.
### MCP Bundle (MCPB)
For easy installation in hosts that support MCP Bundles, you can distribute an `.mcpb` bundle file.
```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
```
This creates `mailtrap-mcp.mcpb` using the repository `manifest.json` and built artifacts in `dist/`.
## Usage
Once configured, you can ask agent to send emails and manage templates, for example:
**Email Sending Operations:**
- "Send an email to john.doe@example.com with the subject 'Meeting Tomorrow' and a friendly reminder about our upcoming meeting."
- "Email sarah@example.com about the project update, and CC the team at team@example.com"
- "Send the welcome template (uuid `b81aabcd-1a1e-41cf-91b6-eca0254b3d96`) to new@example.com with variables `{ name: 'Alex' }`"
- "Send a sandbox email to test@example.com with subject 'Test Template' to preview how our welcome email looks"
**Email Logs (debug delivery):**
- "List my recent sent email logs"
- "Show email logs for emails sent to user@example.com"
- "Get the email log message for ID abc-123-uuid to check delivery status"
**Sending Statistics:**
- "Get sending stats for January 2025"
- "Show delivery rates broken down by domain for last month"
- "What are my email stats by category from 2025-01-01 to 2025-01-31?"
**Sandbox Operations:**
- "Get all messages from my sandbox inbox"
- "Show me the first page of sandbox messages"
- "Search for messages containing 'test' in my sandbox inbox"
- "Show me the details of sandbox message with ID 5159037506"
**Template Operations:**
- "List all email templates in my Mailtrap account"
- "Create a new email template called 'Welcome Email' with subject 'Welcome to our platform!'"
- "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"
- "Turn on click tracking for sending domain 3938"
- "Delete sending domain 3938"
- "Get sending domain 3938 with DNS setup instructions"
- "Show the company info for sending domain 3938"
- "Set the company info for domain 3938 to Acme Inc, 123 Main St, San Francisco, US, 94105, https://acme.com"
- "Change the company info city for domain 3938 to New York"
**Suppressions:**
- "List suppressions for bounced@example.com"
- "Suppress bounced@example.com on the transactional stream of domain 3938"
- "Show me all suppressed email addresses"
- "Why is user@example.com not receiving my emails?"
- "Remove user@example.com from the suppression list"
**Tracking Opt-outs:**
- "Stop tracking opens and clicks for privacy@example.com on domain 3938"
- "List everyone who opted out of tracking"
**Contacts and Lists:**
- "Add john.doe@example.com to my newsletter contact list"
- "Show me all my contact lists"
- "Create a contact field called 'signup_source' for tracking where contacts came from"
- "Update the contact john.doe@example.com to set their plan to 'pro'"
- "Import contacts from this CSV into my onboarding list"
- "Export all contacts from my newsletter list"
- "Record a 'trial_started' event for contact john.doe@example.com"
**Webhooks:**
- "List all webhooks configured on my account"
- "Create a webhook pointing to https://example.com/hooks/mailtrap for bounce and spam events"
- "Update webhook 4821 to also send delivery events"
- "Delete webhook 4821"
**Account and Billing:**
- "What's my current billing usage this month?"
- "How many emails do I have left in my plan?"
- "List everyone who has access to this Mailtrap account"
- "Show me the permission resources available on my account"
**API Tokens:**
- "List all API tokens on my account"
- "Create a new API token for the staging environment"
- "Reset the API token with ID 1234"
- "Delete the unused API token 1234"
**Organization and Sub-Accounts:**
- "List all sub-accounts in my organization"
- "Create a new sub-account for the client project 'Acme Corp'"
## Available Tools
### send-email
Sends a transactional email through Mailtrap. Supports two mutually exclusive modes — **inline content** (`subject` + `text`/`html`) or **template-based** (`template_uuid`).
**Parameters:**
- `from` (optional): Sender as `{ email, name? }` (a bare email string is also accepted at runtime). If not provided, `DEFAULT_FROM_EMAIL` is used.
- `to` (optional): Array of recipients as `{ email, name? }` objects (bare email strings, or a single non-array address, are also accepted at runtime). Optional if `cc` or `bcc` is provided; at least one of `to` / `cc` / `bcc` must contain a recipient.
- `cc` (optional): Array of CC recipients as `{ email, name? }` objects (bare email strings also accepted at runtime).
- `bcc` (optional): Array of BCC recipients as `{ email, name? }` objects (bare email strings also accepted at runtime).
- `subject` (conditional): Email subject line. Required for inline sends; must be omitted when `template_uuid` is set.
- `text` (conditional): Email body text. Required (alongside or instead of `html`) for inline sends; must be omitted when `template_uuid` is set.
- `html` (conditional): HTML version of the email body. Required (alongside or instead of `text`) for inline sends; must be omitted when `template_uuid` is set.
- `category` (optional): Email category for tracking and analytics. Must be omitted when `template_uuid` is set.
- `template_uuid` (optional): Use a Mailtrap email template instead of inline content. When set, `subject` / `text` / `html` / `category` must be omitted (per Mailtrap API).
- `template_variables` (optional): Object of variables substituted into the template referenced by `template_uuid`. Only allowed together with `template_uuid`.
### batch-send-transactional-email
Sends a batch of transactional emails in one Mailtrap API call (default sending stream). Shared fields go on `base`; per-recipient overrides go in `requests[]`. Each request must include at least one recipient via `to`, `cc`, or `bcc`. Same inline-vs-template mutual exclusion as `send-email` — checked after merging base with each request.
**Parameters:**
- `base` (optional): Object with fields shared across the batch.
- `from` (optional): Sender as `{ email, name? }` (a bare email string is also accepted at runtime). Falls back to `DEFAULT_FROM_EMAIL`.
- `reply_to` (optional): Reply-to address.
- `subject` / `text` / `html` / `category` (optional, inline mode): Default content for every request.
- `template_uuid` / `template_variables` (optional, template mode): Default template + variables. Mutually exclusive with the inline fields.
- `custom_variables` (optional): Default custom variables (string-valued).
- `headers` (optional): Default custom headers.
- `requests` (required): Non-empty array of per-recipient messages. Each entry has:
- `to` (optional): Array of recipients as `{ email, name? }` objects (bare email strings, or a single non-array address, are also accepted at runtime). Optional if `cc` or `bcc` is provided; at least one of `to` / `cc` / `bcc` must contain a recipient.
- `cc`, `bcc`, `reply_to` (optional).
- Inline (`subject`/`text`/`html`/`category`) or template (`template_uuid`/`template_variables`) overrides; any field omitted falls back to the matching `base` value.
- `custom_variables`, `headers` (optional).
### batch-send-bulk-email
Sends a batch of bulk emails through Mailtrap's bulk-stream API. Same `base` + `requests[]` shape, validation, and inline-vs-template rules as `batch-send-transactional-email` — the only difference is that this tool routes the call through the bulk endpoint instead of the transactional one. See the parameters above.
### list-email-logs
Lists sent email logs (delivery history) with optional pagination and filters. Use to debug delivery issues from the IDE.
**Parameters:**
- `search_after` (optional): Pagination cursor from the previous response's `next_page_cursor`
- `sent_after` (optional): ISO 8601 date/time; only logs sent after this time
- `sent_before` (optional): ISO 8601 date/time; only logs sent before this time
- `from_email` (optional): Filter by sender email; use with `from_operator` (default: ci_equal)
- `to_email` (optional): Filter by recipient email; use with `to_operator` (default: ci_equal)
- `status` (optional): Filter by delivery status: delivered, not_delivered, enqueued, opted_out; use with `status_operator` (default: equal)
- `subject` (optional): Filter by email subject; use with `subject_operator` (default: ci_contain). Use `subject_operator`: empty/not_empty to filter by presence of subject.
- `sending_domain_id` (optional): Filter by sending domain ID (number); use with `sending_domain_id_operator` (default: equal)
- `sending_stream` (optional): Filter by stream: transactional or bulk; use with `sending_stream_operator` (default: equal)
- `events` (optional): Filter by event type(s): delivery, open, click, bounce, spam, unsubscribe, soft_bounce, reject, suspension; use with `events_operator` (include_event / not_include_event)
- `clicks_count` / `opens_count` (optional): Filter by click/open count; use with `*_operator`: equal, greater_than, less_than
- `client_ip` / `sending_ip` (optional): Filter by IP; use with `*_operator`: equal, not_equal, contain, not_contain
- `email_service_provider_response` (optional): Filter by provider response text; use with `*_operator` (ci_contain, etc.)
- `email_service_provider` (optional): Filter by provider (exact); use with `*_operator`: equal, not_equal
- `recipient_mx` (optional): Filter by recipient MX; use with `recipient_mx_operator` (ci_contain, etc.)
- `category` (optional): Filter by email category; use with `category_operator`: equal, not_equal
All parameters are optional.
### get-email-log-message
Gets a single email log message by ID (UUID): a readable summary (from, to, subject, sent time, status, category, stream, engagement, delivery context), then detailed event history. Optionally, with `include_content: true`, you can also load and show the message body (HTML and plain text) when Mailtrap exposes a raw message URL.
**Parameters:**
- `message_id` (required): UUID of the email log message (from send response or list-email-logs). Use `list-email-logs` to find message IDs.
- `include_content` (optional): When `true`, fetches the raw EML (if `raw_message_url` is available) and appends parsed HTML and plain-text body sections, similar to show-sandbox-email-message.
### get-sending-stats
Get email sending statistics (delivery, bounce, open, click, spam rates) for a date range. Optionally break down by domain, category, email service provider, or date. Check delivery rates without leaving the editor.
**Parameters:**
- `start_date` (required): Start date for the stats range (YYYY-MM-DD)
- `end_date` (required): End date for the stats range (YYYY-MM-DD)
- `breakdown` (optional): How to break down the stats: `aggregated` (default), `by_domain`, `by_category`, `by_email_service_provider`, or `by_date`
- `sending_domain_ids` (optional): Limit results to these sending domain IDs (array of integers)
- `sending_streams` (optional): Limit to `transactional` and/or `bulk` (array of strings)
- `categories` (optional): Limit to these email categories (array of strings)
- `email_service_providers` (optional): Limit to these providers, e.g. Google, Yahoo, Outlook (array of strings)
### create-template
Creates a new email template in your Mailtrap account.
**Parameters:**
- `name` (required): Name of the template
- `subject` (required): Email subject line
- `html` (or `text` is required): HTML content of the template
- `text` (or `html` is required): Plain text version of the template
- `category` (optional): Template category (defaults to "General")
### list-templates
Lists all email templates in your Mailtrap account.
**Parameters:**
- No parameters required
### get-template
Get a single email template by ID, including subject, category, and HTML/text body.
**Parameters:**
- `template_id` (required): ID of the template to fetch
### update-template
Updates an existing email template.
**Parameters:**
- `template_id` (required): ID of the template to update
- `name` (optional): New name for the template
- `subject` (optional): New email subject line
- `html` (optional): New HTML content of the template
- `text` (optional): New plain text version of the template
- `category` (optional): New category for the template
> [!NOTE]
> At least one updatable field (name, subject, html, text, or category) must be provided when calling update-template to perform an update.
### delete-template
Deletes an existing email template.
**Parameters:**
- `template_id` (required): ID of the template to delete
### send-sandbox-email
Sends an email to your Mailtrap test inbox for development and testing purposes. This is perfect for testing email templates without sending emails to real recipients. Supports the same two modes as `send-email` — **inline content** or **template-based** (`template_uuid`).
**Parameters:**
- `sandbox_id` (optional): Preferred. Mailtrap sandbox (test inbox) ID. Required unless `MAILTRAP_SANDBOX_ID` is set.
- `test_inbox_id` (optional): Legacy alias for `sandbox_id` when `sandbox_id` is omitted.
- `from` (optional): Sender as `{ email, name? }` (a bare email string is also accepted at runtime). If not provided, `DEFAULT_FROM_EMAIL` is used.
- `to` (optional): Array of recipients as `{ email, name? }` objects (bare email strings in the array, or a comma-separated string of plain emails, are also accepted at runtime). Optional if `cc` or `bcc` is provided; at least one of `to` / `cc` / `bcc` must contain a recipient.
- `cc` (optional): Array of CC recipients as `{ email, name? }` objects (bare email strings also accepted at runtime).
- `bcc` (optional): Array of BCC recipients as `{ email, name? }` objects (bare email strings also accepted at runtime).
- `subject` (conditional): Email subject line. Required for inline sends; must be omitted when `template_uuid` is set.
- `text` (conditional): Email body text. Required (alongside or instead of `html`) for inline sends; must be omitted when `template_uuid` is set.
- `html` (conditional): HTML version of the email body. Required (alongside or instead of `text`) for inline sends; must be omitted when `template_uuid` is set.
- `category` (optional): Email category for tracking. Must be omitted when `template_uuid` is set.
- `template_uuid` (optional): Use a Mailtrap email template instead of inline content. When set, `subject` / `text` / `html` / `category` must be omitted.
- `template_variables` (optional): Object of variables substituted into the template referenced by `template_uuid`. Only allowed together with `template_uuid`.
### batch-send-sandbox-email
Sends a batch of emails to your Mailtrap test inbox in one API call, without delivering to real recipients. Same `base` + `requests[]` shape, validation, and inline-vs-template rules as `batch-send-transactional-email` — the difference is that this tool routes the call through the sandbox endpoint for a single test inbox.
**Parameters:**
- `sandbox_id` (optional): Mailtrap sandbox (test inbox) ID. Required unless `MAILTRAP_SANDBOX_ID` is set; pass per call to target a specific sandbox.
- `base` (optional), `requests` (required): See `batch-send-transactional-email` above.
> [!NOTE]
> Most sandbox tools take **`sandbox_id`** (or fall back to `MAILTRAP_SANDBOX_ID`; legacy env `MAILTRAP_TEST_INBOX_ID` still works). **`send-sandbox-email`**, **`get-sandbox-messages`**, and **`show-sandbox-email-message`** also accept legacy **`test_inbox_id`**. **`get-sandbox-inbox`**, **`update-sandbox-inbox`**, **`delete-sandbox-inbox`**, and **`clean-sandbox-inbox`** use **`sandbox_id`** with legacy **`inbox_id`** (same ID; `inbox_id` is not used on message tools). Inbound email tools use **`inbox_id`** for a different product (received mail), not the sandbox.
### get-sandbox-messages
Retrieves a list of messages from your Mailtrap test inbox. Useful for checking what emails have been received in your sandbox during testing.
**Parameters:**
- `sandbox_id` (optional): Preferred. Sandbox (test inbox) ID unless `MAILTRAP_SANDBOX_ID` is set.
- `test_inbox_id` (optional): Legacy alias for `sandbox_id`.
- `page` (optional): Page number for pagination (minimum: 1)
- `last_id` (optional): Pagination using last message ID. Returns messages after the specified message ID (minimum: 1)
- `search` (optional): Search query to filter messages
> [!NOTE]
> Inbox ID parameters are optional when `MAILTRAP_SANDBOX_ID` is set. If none of `sandbox_id`, `test_inbox_id`, or env are provided, the call fails. Pagination: use `page`, `last_id`, or `search` as needed.
### show-sandbox-email-message
Shows detailed information and content of a specific email message from your Mailtrap test inbox, including HTML and text body content.
**Parameters:**
- `sandbox_id` (optional): Preferred. Sandbox (test inbox) ID unless `MAILTRAP_SANDBOX_ID` is set.
- `test_inbox_id` (optional): Legacy alias for `sandbox_id`.
- `message_id` (required): ID of the sandbox email message to retrieve
> [!NOTE]
> Use `get-sandbox-messages` first to get message IDs, then this tool for full content.
### get-sandbox-project
Get a sandbox project by ID, including its inboxes and email counts.
**Parameters:**
- `project_id` (required): ID of the project to fetch
### update-sandbox-project
Rename an existing sandbox project.
**Parameters:**
- `project_id` (required): ID of the project to update
- `name` (required): New name for the project (2–100 characters)
### list-sandboxes
List every sandbox accessible to the API token across all projects.
**Parameters:**
- No parameters required
### mark-sandbox-as-read
Mark all messages in a sandbox as read.
**Parameters:**
- `sandbox_id` (required): ID of the sandbox to act on
### reset-sandbox-credentials
Reset the SMTP credentials for a sandbox. Returns the new username/password.
**Parameters:**
- `sandbox_id` (required): ID of the sandbox to act on
### enable-sandbox-email-address
Enable the receive-by-email address for a sandbox (turns on the Mailtrap address that delivers messages to the sandbox via SMTP).
**Parameters:**
- `sandbox_id` (required): ID of the sandbox to act on
### reset-sandbox-email-address
Generate a new receive-by-email address for a sandbox.
**Parameters:**
- `sandbox_id` (required): ID of the sandbox to act on
### forward-sandbox-message
Forward a sandbox message to an external email address. Counts against your monthly forwarding quota.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message to forward
- `email` (required): Email address to forward the message to
### update-sandbox-message
Mark a sandbox message as read or unread.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message to update
- `is_read` (required): `true` marks as read, `false` marks as unread
### delete-sandbox-message
Delete a single sandbox message.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message to delete
### get-sandbox-message-spam-score
Get the SpamAssassin spam report for a sandbox message (score, rules, full report). Standalone alternative to `include_spam_report: true` on `show-sandbox-email-message`.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-html-analysis
Get the HTML analysis report for a sandbox message (client compatibility scores, problematic elements). Standalone alternative to `include_html_analysis: true` on `show-sandbox-email-message`.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-headers
Get the parsed mail headers for a sandbox message.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-html
Get the rendered HTML body of a sandbox message.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-text
Get the plain-text body of a sandbox message.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-raw
Get the raw, MIME-formatted message (headers + body) for a sandbox message.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-eml
Get the message rendered as an EML file payload (suitable for attaching to a ticket or importing into another mail client).
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-message-html-source
Get the unrendered HTML source of a sandbox message (HTML before any Mailtrap-side transformations like CID-link rewrites).
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### list-sandbox-attachments
List all attachments on a sandbox message (filename, content type, size, download path).
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message
### get-sandbox-attachment
Get metadata and download URL for a single attachment.
**Parameters:**
- `sandbox_id` (optional): Sandbox ID. Falls back to `MAILTRAP_SANDBOX_ID`.
- `message_id` (required): ID of the sandbox message that contains the attachment
- `attachment_id` (required): ID of the attachment to fetch
### 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)
### update-sending-domain
Update a sending domain's tracking and inbound settings.
**Parameters:**
- `sending_domain_id` (required): Sending domain ID
- `open_tracking_enabled` (optional): Track opens on emails sent from this domain
- `click_tracking_enabled` (optional): Track clicks on links in emails sent from this domain
- `tracking_opt_out_enabled` (optional): Add the tracking opt-out link to tracked emails. Requires open or click tracking
- `auto_unsubscribe_link_enabled` (optional): Automatically add an unsubscribe link to emails
- `inbound_enabled` (optional): Allow the domain to be attached to an inbound inbox as a catch-all
At least one setting besides `sending_domain_id` must be provided.
### delete-sending-domain
Delete a sending domain.
**Parameters:**
- `sending_domain_id` (required): Sending domain ID to delete
### send-sending-domain-setup-instructions
Email DNS setup instructions for a sending domain to a given address. Useful for forwarding DNS records to a DevOps teammate.
**Parameters:**
- `sending_domain_id` (required): Sending domain ID
- `email` (required): Email address to send DNS setup instructions to
### get-company-info
Get the company info of a sending domain, used for domain compliance verification.
**Parameters:**
- `sending_domain_id` (required): Sending domain ID
### create-company-info
Set the company info of a sending domain, required for domain compliance verification.
**Parameters:**
- `sending_domain_id` (required): Sending domain ID
- `name` (required): Company or individual name
- `address` (required): Street address
- `city` (required): City
- `country` (required): Country
- `zip_code` (required): ZIP or postal code
- `website_url` (required): Company website URL
- `phone` (optional): Phone number
- `privacy_policy_url` (optional): URL of the privacy policy page
- `terms_of_service_url` (optional): URL of the terms of service page
- `info_level` (optional): `business` or `individual`
### update-company-info
Update the company info of a sending domain.
**Parameters:**
- `sending_domain_id` (required): Sending domain ID
- Every field of create-company-info, all optional. At least one must be provided; fields left out are unchanged.
### list-suppressions
List or search suppressions (hard bounces, spam complaints, unsubscriptions, manual imports). Returns up to 1000 results per call.
**Parameters:**
- `email` (optional): Email filter. Returns only suppressions matching this address.
### create-suppression
Add an email address to the account's suppression list, so Mailtrap stops delivering to it.
**Parameters:**
- `email` (required): Email address to suppress
- `domain_id` (required): ID of the sending domain the suppression applies to
- `sending_stream` (required): `transactional` or `bulk`
- `type` (optional): `hard bounce`, `spam complaint`, `unsubscription` or `manual import`. Defaults to `manual import`
### delete-suppression
Delete a suppression by ID. Mailtrap will resume delivery to this email unless it gets suppressed again.
**Parameters:**
- `suppression_id` (required): ID of the suppression to delete
### list-tracking-opt-outs
List email addresses excluded from open and click tracking. Returns up to 1000 records per call.
**Parameters:**
- `email` (optional): Email filter. Returns only opt-outs matching this address
- `start_time` (optional): Only opt-outs created at or after this time (ISO 8601)
- `end_time` (optional): Only opt-outs created at or before this time (ISO 8601)
- `last_id` (optional): Pagination cursor — the `last_id` from the previous response
### create-tracking-opt-out
Exclude an email address from open and click tracking for a sending domain.
**Parameters:**
- `email` (required): Email address to opt out of tracking
- `domain_id` (required): ID of the sending domain the opt-out applies to
### delete-tracking-opt-out
Remove an email address from the tracking opt-out list, so open and click tracking applies to it again.
**Parameters:**
- `tracking_opt_out_id` (required): ID of the tracking opt-out to delete
### list-webhooks
List all webhooks configured for the account. Returns the full webhook records as JSON.
**Parameters:**
- No parameters required
### get-webhook
Get a single webhook by ID. Returns the full webhook record as JSON. Note: `signing_secret` is **not** returned here — it is only available in the response from `create-webhook`.
**Parameters:**
- `webhook_id` (required): ID of the webhook to fetch
### create-webhook
Create a webhook. The response includes a `signing_secret` for verifying webhook payload signatures — this secret is returned **only on creation**, so store it now. If you lose it, recreate the webhook.
**Parameters:**
- `url` (required): URL Mailtrap will POST webhook events to
- `webhook_type` (required): `"email_sending"`, `"audit_log"`, or `"inbound_receiving"`
- `active` (optional, boolean): defaults to `true`
- `payload_format` (optional): `"json"` or `"jsonlines"`. Defaults to `"json"`
- `sending_stream` (optional, `email_sending` only): `"transactional"` or `"bulk"`
- `event_types` (optional, `email_sending` only): array of `delivery`, `soft_bounce`, `bounce`, `suspension`, `unsubscribe`, `open`, `spam_complaint`, `click`, `reject`
- `domain_id` (optional, `email_sending` only): sending domain ID to scope this webhook to
- `inbound_inbox_id` (optional, `inbound_receiving` only): ID of the inbound inbox the webhook is linked to; omit to apply to all inboxes in the account
### update-webhook
Update a webhook's mutable fields. `webhook_type`, `sending_stream`, and `domain_id` cannot be changed after creation — recreate the webhook if you need to change those.
**Parameters:**
- `webhook_id` (required): ID of the webhook to update
- `url` (optional): New webhook URL
- `active` (optional, boolean): Enable or disable the webhook
- `payload_format` (optional): `"json"` or `"jsonlines"`
- `event_types` (optional, `email_sending` only): array of `delivery`, `soft_bounce`, `bounce`, `suspension`, `unsubscribe`, `open`, `spam_complaint`, `click`, `reject`
- `inbound_inbox_id` (optional, `inbound_receiving` only): ID of the inbound inbox the webhook is linked to
### delete-webhook
Permanently delete a webhook by ID. Returns the deleted webhook record.
**Parameters:**
- `webhook_id` (required): ID of the webhook to delete
### get-contact
Get a contact by ID or email. Returns the full contact record (list memberships, status, custom fields).
**Parameters:**
- `contact_identifier` (required): Contact ID or email address
### create-contact
Create a new contact.
**Parameters:**
- `email` (required): Email address
- `fields` (optional): Custom field values keyed by merge tag (e.g. `first_name`). String, number, or boolean values
- `list_ids` (optional): IDs of contact lists to subscribe this contact to
- `unsubscribed` (optional, boolean): Create the contact in `unsubscribed` status
### update-contact
Update an existing contact identified by ID or email. `list_ids` replaces the contact's full membership set; `list_ids_included`/`list_ids_excluded` add/remove without disturbing the rest.
**Parameters:**
- `contact_identifier` (required): Contact ID or email
- `email` (optional): New email address
- `fields` (optional): Custom field values keyed by merge tag
- `list_ids` (optional): Replace membership set with this exact list
- `list_ids_included` (optional): List IDs to add (additive)
- `list_ids_excluded` (optional): List IDs to remove
- `unsubscribed` (optional, boolean): Set to `unsubscribed` (true) or `subscribed` (false)
### delete-contact
Permanently delete a contact by ID or email. Returns the deleted contact record when the API responds with one; otherwise returns a confirmation payload.
**Parameters:**
- `contact_identifier` (required): Contact ID or email
### create-contact-event
Record a contact event against a contact (by ID or email). Used to trigger contact-list automations.
**Parameters:**
- `contact_identifier` (required): Contact ID or email
- `name` (required): Event name (matches automation triggers)
- `params` (required): Object of arbitrary key/value pairs. Values may be string, number, boolean, or null
### list-contact-lists
List all contact lists for the account.
**Parameters:**
- `search` (optional): Filter contact lists by name (case-insensitive match), e.g. `news`
### get-contact-list
Get a contact list by ID.
**Parameters:**
- `list_id` (required): ID of the contact list to fetch
### create-contact-list
Create a new contact list.
**Parameters:**
- `name` (required): Name for the new list
### update-contact-list
Rename an existing contact list.
**Parameters:**
- `list_id` (required): ID of the contact list
- `name` (required): New name for the list
### delete-contact-list
Permanently delete a contact list by ID.
**Parameters:**
- `list_id` (required): ID of the contact list to delete
### list-contact-fields
List all contact field definitions for the account.
**Parameters:**
- No parameters required
### get-contact-field
Get a contact field definition by ID.
**Parameters:**
- `field_id` (required): ID of the contact field
### create-contact-field
Create a new contact field definition. `merge_tag` must be unique within the account and is used as the placeholder name in template variables.
**Parameters:**
- `name` (required): Display name (e.g. "First Name")
- `merge_tag` (required): Unique placeholder name (e.g. `first_name`)
- `data_type` (required): One of `text`, `number`, `boolean`, `date`
### update-contact-field
Update a contact field definition. Any combination of `name`, `merge_tag`, and `data_type` can be changed.
**Parameters:**
- `field_id` (required): ID of the contact field
- `name` (optional): New display name
- `merge_tag` (optional): New merge tag (must remain unique)
- `data_type` (optional): One of `text`, `number`, `boolean`, `date`
### delete-contact-field
Permanently delete a contact field definition by ID.
**Parameters:**
- `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
### list-email-campaigns
List the account's email campaigns, newest first, with page-token pagination. Optionally filter by name with `search`.
**Parameters:**
- `token` (optional): Page number to retrieve (page-token pagination). Defaults to `1`
- `per_page` (optional): Number of campaigns per page. Defaults to `50`, maximum `100`
- `search` (optional): Filter campaigns by name (case-insensitive partial match)
### get-email-campaign
Get an email campaign by ID.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign
### create-email-campaign
Create a new email campaign. The campaign is always created in the `draft` state; scheduling and starting are separate tools (`schedule-email-campaign`, `start-email-campaign`).
**Parameters:**
- `name` (required): Campaign name
- `domain_id` (required): ID of the verified sending domain used for the campaign, as returned by the Sending Domains endpoints
- `from_local_part` (required): Local part (before the @) of the From address
- `template_attributes` (required): Inline email template. Has:
- `subject` (required): Email subject line (max 255 chars). Supports merge tags, e.g. `Hi {{first_name}}`
- `body_html` (optional): HTML body (the design). Required before the campaign can be scheduled or started. Include an unsubscribe link via an anchor whose `href` contains the `__unsubscribe_url__` placeholder
- `body_text` (optional): Plain-text alternative of the email body
- `merge_tags` (optional): Bare names of the merge tags referenced in the subject/body, e.g. `["first_name"]`
- `from_display_name` (optional): Display name shown in the From header
- `reply_to` (optional): Reply-To address parts (`display_name`, `local_part`, `domain`)
- `delivery_mode` (optional): `rapid` (send as fast as possible) or `gradual` (throttle to `delivery_options.emails_per_hour`)
- `delivery_options` (optional): Delivery throttling options (`emails_per_hour`)
- `contact_list_ids` (optional): IDs of contact lists to send to (treated as the full set of included lists)
- `contact_segment_ids` (optional): IDs of contact segments to send to (treated as the full set of included segments)
### update-email-campaign
Update a `draft` email campaign. Only the provided fields change; the template is edited in place. Campaigns in any other state cannot be updated.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to update
- All other parameters are optional and identical to `create-email-campaign` (`name`, `domain_id`, `from_local_part`, `from_display_name`, `reply_to`, `template_attributes`, `delivery_mode`, `delivery_options`, `contact_list_ids`, `contact_segment_ids`)
### delete-email-campaign
Delete an email campaign by ID. Only a campaign in the `draft` state can be deleted.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to delete
### start-email-campaign
Start sending a `draft` email campaign immediately. Only `draft` campaigns can be started; the template must have a `body_html` design and the audience and verified sending domain must be set.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to start
### schedule-email-campaign
Schedule a `draft` email campaign to start sending at a future time. Only `draft` campaigns can be scheduled.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to schedule
- `datetime` (required): When to send the campaign (ISO 8601). Must be in the future and no more than 1 month ahead
### cancel-email-campaign
Cancel a `scheduled` email campaign, returning it to `draft`. Only `scheduled` campaigns can be cancelled.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to cancel
### terminate-email-campaign
Terminate an email campaign that is currently sending (`started`, `queued`, or `paused`), aborting the in-flight send.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to terminate
### reset-email-campaign
Reset a `scheduled` email campaign back to `draft`. Only `scheduled` campaigns can be reset.
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign to reset
### get-email-campaign-stats
Get aggregated performance statistics for an email campaign (counts and rates for deliveries, opens, clicks, bounces, spam complaints, and unsubscriptions).
**Parameters:**
- `email_campaign_id` (required): ID of the email campaign
- `start_date` (optional): Start of the aggregation window (inclusive), `YYYY-MM-DD`. Defaults to the day the campaign was last started
- `end_date` (optional): End of the aggregation window (inclusive), `YYYY-MM-DD`. Defaults to the current date
### list-accounts
List Mailtrap accounts the current API token can access, with each account's access levels.
**Parameters:**
- No parameters required
### get-billing-usage
Get the current billing cycle usage for the account: sending and testing plans, limits, and current counts.
**Parameters:**
- No parameters required
### list-account-accesses
List account accesses (users, invites, API tokens) for the account. Optional filters narrow the result to specific resources. Requires account admin/owner permissions.
**Parameters:**
- `domain_uuids` (optional): Filter by sending domain UUIDs (array of strings)
- `inbox_ids` (optional): Filter by sandbox inbox IDs (array of strings)
- `project_ids` (optional): Filter by sandbox project IDs (array of strings)
### remove-account-access
Remove an account access by ID. For `User` specifiers this revokes their permissions; for `Invite` or `ApiToken` specifiers it removes the specifier entirely. Requires admin/owner.
**Parameters:**
- `account_access_id` (required): ID of the access record to remove
### get-permission-resources
Get all resources (inboxes, projects, domains, billing, account) to which the API token has admin access, nested by hierarchy.
**Parameters:**
- No parameters required
### bulk-update-permissions
Bulk create, update, or destroy permissions for a single account access. Existing `(resource_type, resource_id)` pairs are updated; new ones are created. Set `destroy: true` on an entry to remove it.
**Parameters:**
- `account_access_id` (required): Target account access ID
- `permissions` (required): Array of permission entries. Each has:
- `resource_id` (required): Resource ID (number or string)
- `resource_type` (required): One of `account`, `project`, `inbox`, `domain`, `billing`
- `access_level` (optional): `admin`/`100` or `viewer`/`10`
- `destroy` (optional, boolean): When true, removes this permission instead of creating/updating it
### list-api-tokens
List all API tokens for the account.
**Parameters:**
- No parameters required
### create-api-token
Create a new API token. The response includes the secret `token` value — this is the **only time** the full token is returned, so store it immediately. If you lose it, recreate the token.
**Parameters:**
- `name` (required): Display name for the token
- `expires_at` (optional): Token expiration as an ISO 8601 date-time. Omit for the server default (1 year); pass an explicit `null` for a token that never expires. Past values or values more than 5 years ahead are rejected
- `resources` (optional): Array of resource permissions to scope the token to. Each entry has:
- `resource_type` (required): One of `account`, `project`, `inbox`, `domain`, `billing`
- `resource_id` (required): ID of the resource
- `access_level` (required): `100` (admin) or `10` (viewer)
### get-api-token
Get an API token by ID. Returns metadata only — the secret token value is **not** returned here (only from `create-api-token` / `reset-api-token`).
**Parameters:**
- `api_token_id` (required): ID of the API token
### reset-api-token
Reset (rotate) an API token by ID. The response includes the **new** secret `token` value — returned only on this call, so store it immediately. The previous token is invalidated.
**Parameters:**
- `api_token_id` (required): ID of the API token to reset
- `expires_at` (optional): Expiration for the new token as an ISO 8601 date-time. Omit for the server default (1 year); pass an explicit `null` for a token that never expires. Past values or values more than 5 years ahead are rejected
### delete-api-token
Permanently delete an API token by ID. The token can no longer authenticate after deletion.
**Parameters:**
- `api_token_id` (required): ID of the API token to delete
### list-sub-accounts
List sub-accounts in the organization. Requires `MAILTRAP_ORGANIZATION_ID` env var and sub-account management permissions.
**Parameters:**
- No parameters required
### create-sub-account
Create a new sub-account under the organization. Requires `MAILTRAP_ORGANIZATION_ID` env var and sub-account management permissions.
**Parameters:**
- `name` (required): Display name for the new sub-account
### list-inbound-folders
List all inbound folders in the account. Returns a formatted summary.
**Parameters:**
- No parameters required
### get-inbound-folder
Get a single inbound folder by ID. Returns the full folder record as JSON.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
### create-inbound-folder
Create a new inbound folder.
**Parameters:**
- `name` (required): The folder name
### update-inbound-folder
Rename an inbound folder.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
- `name` (required): The new folder name
### delete-inbound-folder
Permanently delete an inbound folder along with all of its inboxes.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
### list-inbound-inboxes
List all inboxes in an inbound folder. Returns a formatted summary.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
### get-inbound-inbox
Get a single inbound inbox by ID. Returns the full inbox record as JSON.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
- `inbox_id` (required): ID of the inbox
### create-inbound-inbox
Create a new inbound inbox in a folder.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
- `name` (required): The inbox name
- `domain_id` (optional): Attach to a custom sending domain (catch-all inbox). Omit for a Mailtrap-hosted inbox
### update-inbound-inbox
Rename an inbound inbox.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
- `inbox_id` (required): ID of the inbox
- `name` (required): The new inbox name
### delete-inbound-inbox
Permanently delete an inbound inbox.
**Parameters:**
- `folder_id` (required): ID of the inbound folder
- `inbox_id` (required): ID of the inbox
### list-inbound-messages
List received messages in an inbound inbox (cursor-paginated). Returns a formatted summary with a next-page hint when more results exist.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `last_id` (optional): Pagination cursor from a previous response's `last_id`
### get-inbound-message
Get a single inbound message with its full body and attachment download URLs. Returns the full message record as JSON.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `message_id` (required): ID of the message
### delete-inbound-message
Permanently delete an inbound message.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `message_id` (required): ID of the message
### reply-to-inbound-message
Reply to an inbound message (sends to the original sender). Sends a real email. Addresses accept a bare email string or `{ email, name? }`.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `message_id` (required): ID of the message to reply to
- `text` / `html` (at least one recommended): Reply body
- `from` (optional): Sender. Rejected for Mailtrap-hosted inboxes; required for custom-domain inboxes
- `cc` / `bcc` / `reply_to` (optional): Additional addresses
- `category` (optional): Message category
- `attachments` (optional): Array of `{ content (base64), filename, type?, disposition?, content_id? }`
- `headers` / `custom_variables` (optional): Objects of string values
### reply-all-to-inbound-message
Reply to an inbound message and copy the original's other recipients. Sends a real email. Same parameters as `reply-to-inbound-message`.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `message_id` (required): ID of the message to reply to
- Plus the same optional send fields as `reply-to-inbound-message`
### forward-inbound-message
Forward an inbound message to new recipients. Sends a real email.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `message_id` (required): ID of the message to forward
- `to` (required): At least one recipient (bare email string or `{ email, name? }`, or an array)
- Plus the same optional send fields as `reply-to-inbound-message`
### list-inbound-threads
List conversation threads in an inbound inbox (cursor-paginated). Returns a formatted summary with a next-page hint when more results exist.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `last_id` (optional): Pagination cursor from a previous response's `last_id`
### get-inbound-thread
Get a single inbound thread with its messages embedded (oldest first). Returns the full thread record as JSON.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `thread_id` (required): ID of the thread
### delete-inbound-thread
Permanently delete an inbound thread.
**Parameters:**
- `inbox_id` (required): ID of the inbox
- `thread_id` (required): ID of the thread
## Development
1. Clone the repository:
```bash
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
```
2. Install dependencies:
```bash
npm install
```
### Configuration with Claude Desktop or Cursor
> [!TIP]
> See the location of the config file in the [Setup](#setup) section.
Add the following configuration:
```json
{
"mcpServers": {
"mailtrap": {
"command": "node",
"args": ["/path/to/mailtrap-mcp/dist/index.js"],
"env": {
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_SANDBOX_ID": "your_sandbox_id"
}
}
}
}
```
If you are using `asdf` for managing Node.js you should use absolute path to executable:
(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_SANDBOX_ID": "your_sandbox_id"
}
}
}
}
```
### VS Code
> [!TIP]
> See the location of the config file in the [Setup](#setup) section.
```json
{
"mcp": {
"servers": {
"mailtrap": {
"command": "node",
"args": ["/path/to/mailtrap-mcp/dist/index.js"],
"env": {
"MAILTRAP_API_TOKEN": "your_mailtrap_api_token",
"DEFAULT_FROM_EMAIL": "your_sender@example.com",
"MAILTRAP_ACCOUNT_ID": "your_account_id",
"MAILTRAP_SANDBOX_ID": "your_sandbox_id"
}
}
}
}
}
```
## Testing
### Running tools against real Mailtrap
There are two ways to exercise a tool end-to-end against a real Mailtrap account: the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) browser UI for interactive exploration, or its CLI mode for one-shot calls from the shell.
Both require the bundle to be built first:
```bash
npm run build
```
and `MAILTRAP_API_TOKEN` + `MAILTRAP_ACCOUNT_ID` exported in your shell (the `mcp:cli` script forwards both to the spawned server).
#### Browser UI
```bash
npm run dev
```
The Inspector prints a URL like `http://localhost:6274`. Open it, switch to the **Tools** tab, pick a tool (e.g. `get-template`), fill the parameters as JSON, and hit **Run**. The Mailtrap response appears in the panel below.
#### CLI
For one-shot calls without the UI, use `npm run mcp:cli`. Pass the Inspector's CLI flags after `--` so npm forwards them verbatim:
```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
```
### Running the MCPB Server
```bash
# Run the MCPB server directly
node dist/mcpb-server.js
# Or use the provided binary
mailtrap-mcpb-server
```
> [!TIP]
> For development with the MCP Inspector:
```bash
npm run dev:mcpb
```
## Error Handling
This server uses structured error handling aligned with MCP conventions:
- `VALIDATION_ERROR`: Input validation failures
- `CONFIGURATION_ERROR`: Missing or invalid configuration
- `EXECUTION_ERROR`: Runtime execution errors
- `TIMEOUT`: Operation timeout (30 seconds default)
Errors include actionable messages and are logged in structured form.
## Security
- Input validated via Zod schemas
- Environment variables handled securely
- Timeout protection on operations (30 seconds)
- Sensitive details sanitized in error output
## Logging
Structured JSON logs with levels: INFO, WARN, ERROR, DEBUG.
Enable debug logging by setting `DEBUG=true`.
```bash
# Example: enable debug logging
DEBUG=true node dist/mcpb-server.js
```
> Important: The server writes logs to stderr so stdout remains reserved for JSON-RPC frames. This prevents hosts from encountering JSON parsing errors due to interleaved logs.
Log analysis example using `jq`:
```bash
# Filter error logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'
# Filter debug logs
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'
```
## Troubleshooting
Common issues:
1. Missing API Token: ensure `MAILTRAP_API_TOKEN` is set
2. Sandbox not working: provide `sandbox_id` in the tool call (or legacy `test_inbox_id` on send/list/show message tools), or set `MAILTRAP_SANDBOX_ID` env
3. Timeout errors: check network connectivity and Mailtrap API status
4. Validation errors: ensure all required fields are provided
## Contributing
Bug reports and pull requests are welcome on [GitHub](https://github.com/mailtrap/mailtrap-mcp). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
## License
The package is available as open source under the terms of the [MIT License](LICENSE.txt).
## Code of Conduct
Everyone interacting in the Mailtrap project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
