
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, 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 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:
- Create a Mailtrap account
- Verify your domain
- Get your API token from Mailtrap API settings
- Get your Account ID from Mailtrap account management
- Install Node.js 22 or later, unless you run the Docker image
Required Environment Variables:
MAILTRAP_API_TOKEN - Required for all functionality
MAILTRAP_ACCOUNT_ID - Required for templates, get-sending-stats, email logs, sandbox list/show, domains, and suppressions. Optional only for the send tools (send-email, send-sandbox-email, and the batch-send-* tools), the email campaign tools, get-marketing-stats, the company info tools, the tracking opt-out tools, and list-accounts.
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 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 sandboxes per call via parameters.
MAILTRAP_TEST_INBOX_ID - Deprecated alias for MAILTRAP_SANDBOX_ID; still read as a fallback for existing configs, and logs a deprecation warning to stderr when used.
MAILTRAP_ORGANIZATION_ID - Required for organization tools (list-sub-accounts, create-sub-account, delete-sub-account).
MAILTRAP_ORGANIZATION_API_TOKEN - Organization-scoped API token. Required for organization tools (separate from MAILTRAP_API_TOKEN).
Quick Install


Docker
Run the server over stdio with the Docker MCP Catalog image:
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 for required and optional environment variables.
To build from this repository: docker build -t mcp/mailtrap .
Smithery CLI
Smithery 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):
npx -y smithery mcp add mailtrap/mailtrap-mcp --client claude
See the Smithery CLI docs 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.
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:
{
"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)
{
"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": "22.14.0",
"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:
{
"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.
npm run mcpb:pack
npm run mcpb:info
npm run mcpb:sign
This creates mailtrap-mcp.mcpb. The script copies dist/, manifest.json, icon.png and the
license into mcpb-build/, installs production dependencies there, and packs only that directory.
Do not run mcpb pack . from the repository root.
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"
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?"
- "How did my email marketing perform last month? Compare campaigns with automations"
Sandbox Operations:
- "Get all messages from my sandbox"
- "Show me the first page of sandbox messages"
- "Search for messages containing 'test' in my sandbox"
- "Create a sandbox called 'QA' in project 42 and give me its SMTP credentials"
- "Delete all messages from sandbox 1234"
- "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"
Domains:
- "List my domains"
- "Get domain with ID 3938"
- "Create a domain for example.com"
- "Turn on click tracking for domain 3938"
- "Delete domain 3938"
- "Get domain 3938 with DNS setup instructions"
- "Show the company info for 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:
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'"
Mailtrap now calls test inboxes sandboxes and sending domains domains, and the tools follow suit. The old names no longer appear in the tool list, but calls to them still work and log a deprecation warning to stderr. They will be removed in a future major release.
MCP clients and agent frameworks match allow, deny and filter lists against the advertised tool name, so move any per-tool entries to the new names: a deny entry for delete-sending-domain no longer blocks delete-domain.
| Old name | New name |
|---|
create-sandbox-inbox | create-sandbox |
get-sandbox-inbox | get-sandbox |
update-sandbox-inbox | update-sandbox |
delete-sandbox-inbox | delete-sandbox |
clean-sandbox-inbox | clean-sandbox |
list-sending-domains | list-domains |
get-sending-domain | get-domain |
create-sending-domain | create-domain |
update-sending-domain | update-domain |
delete-sending-domain | delete-domain |
send-sending-domain-setup-instructions | send-domain-setup-instructions |
sending_domain_id param of the domain and company info tools | domain_id |
MAILTRAP_TEST_INBOX_ID env var | MAILTRAP_SANDBOX_ID |
Filters that mirror an API field keep their names: sending_domain_id on list-email-logs and sending_domain_ids on the stats 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 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 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)
get-marketing-stats
Get aggregated Email Marketing statistics across campaigns and automations for a date range: sent, delivery, bounce, open, click, spam and unsubscription counts and rates. delivery_rate and bounce_rate are shares of sent_count; the other rates are shares of delivery_count.
Parameters:
start_date (required): Start of the date range (inclusive), YYYY-MM-DD
end_date (required): End of the date range (inclusive), YYYY-MM-DD
sending_domain_ids (optional): Limit results to these domain IDs (array of integers)
sources (optional): campaigns or automations narrows the stats to that source; omit it, or pass both, for all Email Marketing traffic (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 the email templates in your Mailtrap account with page-token pagination. When more templates exist, the result names the token for the next page. Pages are offsets over the newest-first list, so after deleting templates list again from token 1 instead of continuing with the next token; an empty page names the last page that still has templates.
Parameters:
token (optional): Page number to retrieve (page-token pagination). Defaults to 1
per_page (optional): Number of templates per page. Defaults to 50, maximum 100. Pass the same value on every page
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 sandbox 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 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 sandbox 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 sandbox.
Parameters:
sandbox_id (optional): Mailtrap sandbox 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; the deprecated 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, update-sandbox, delete-sandbox, and clean-sandbox 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 sandbox. Useful for checking what emails have been received in your sandbox during testing.
Parameters:
sandbox_id (optional): Preferred. Sandbox 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
Sandbox 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 sandbox, including HTML and text body content.
Parameters:
sandbox_id (optional): Preferred. Sandbox 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.
list-sandbox-projects
List all sandbox projects and their sandboxes.
Parameters:
create-sandbox-project
Create a new sandbox project to group sandboxes.
Parameters:
name (required): Name of the project (2β100 characters)
get-sandbox-project
Get a sandbox project by ID, including its sandboxes 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)
delete-sandbox-project
Delete a sandbox project and all its sandboxes.
Parameters:
project_id (required): ID of the project to delete
create-sandbox
Create a new sandbox within a project. Returns the new sandbox's SMTP credentials.
Parameters:
project_id (required): ID of the project to create the sandbox in
name (required): Name of the sandbox
get-sandbox
Get sandbox details, including SMTP credentials, email counts, and status.
Parameters:
sandbox_id (optional): Sandbox ID. Required unless MAILTRAP_SANDBOX_ID is set.
inbox_id (optional): Legacy alias for sandbox_id.
update-sandbox
Update a sandbox's name or email username.
Parameters:
sandbox_id (required): Sandbox ID (legacy alias: inbox_id)
name (optional): New name for the sandbox
email_username (optional): New email username for the sandbox
At least one of name or email_username must be provided.
delete-sandbox
Delete a sandbox and all its messages.
Parameters:
sandbox_id (required): Sandbox ID (legacy alias: inbox_id)
clean-sandbox
Delete all messages from a sandbox without deleting the sandbox itself.
Parameters:
sandbox_id (required): Sandbox ID (legacy alias: inbox_id)
list-sandboxes
List every sandbox accessible to the API token across all projects.
Parameters:
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-domains
List domains and their DNS verification status.
Parameters:
get-domain
Get a domain by ID and its verification status (including DNS records). Optionally include DNS setup instructions by setting include_setup_instructions to true.
Parameters:
domain_id (required): Domain ID (legacy alias: sending_domain_id)
include_setup_instructions (optional): If true, append DNS setup instructions to the response. Default: false
create-domain
Create a new domain. After creation, add DNS records to verify the domain (use get-domain with include_setup_instructions: true to see the records).
Parameters:
domain_name (required): Domain name (e.g. example.com)
update-domain
Update a domain's tracking and inbound settings.
Parameters:
domain_id (required): Domain ID (legacy alias: 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 domain_id must be provided.
delete-domain
Delete a domain.
Parameters:
domain_id (required): Domain ID to delete (legacy alias: sending_domain_id)
send-domain-setup-instructions
Email DNS setup instructions for a domain to a given address. Useful for forwarding DNS records to a DevOps teammate.
Parameters:
domain_id (required): Domain ID (legacy alias: sending_domain_id)
email (required): Email address to send DNS setup instructions to
get-company-info
Get the company info of a domain, used for domain compliance verification.
Parameters:
domain_id (required): Domain ID (legacy alias: sending_domain_id)
create-company-info
Set the company info of a domain, required for domain compliance verification.
Parameters:
domain_id (required): Domain ID (legacy alias: 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 domain.
Parameters:
domain_id (required): Domain ID (legacy alias: 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 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 domain.
Parameters:
email (required): Email address to opt out of tracking
domain_id (required): ID of the 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:
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): 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 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 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 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)
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
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 all contact lists for the account.
Parameters:
search (optional): Filter contact lists by name (case-insensitive match), e.g. news
Get a contact list by ID.
Parameters:
list_id (required): ID of the contact list to fetch
Create a new contact list.
Parameters:
name (required): Name for the new list
Rename an existing contact list.
Parameters:
list_id (required): ID of the contact list
name (required): New name for the list
Permanently delete a contact list by ID.
Parameters:
list_id (required): ID of the contact list to delete
List all contact field definitions for the account.
Parameters:
Get a contact field definition by ID.
Parameters:
field_id (required): ID of the 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 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
Permanently delete a contact field definition by ID.
Parameters:
field_id (required): ID of the contact field to delete
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 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
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 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 domain used for the campaign, as returned by list-domains
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 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. Works without MAILTRAP_ACCOUNT_ID, so use it to find your account ID.
Parameters:
get-billing-usage
Get the current billing cycle usage for the account: sending and testing plans, limits, and current counts.
Parameters:
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 domain UUIDs (array of strings)
inbox_ids (optional): Filter by sandbox 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 (sandboxes, projects, domains, billing, account) to which the API token has admin access, nested by hierarchy.
Parameters:
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:
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:
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
delete-sub-account
Permanently delete a sub-account by ID, removing all of its data. Deleting the last sub-account deletes the organization; a repeated call returns 404. A concurrent deletion of the same sub-account returns 409. Requires MAILTRAP_ORGANIZATION_ID env var and organization admin permissions, and the organization must have the Organization & Sub-accounts feature enabled (403 otherwise).
Parameters:
sub_account_id (required): ID of the sub-account to delete
list-inbound-folders
List all inbound folders in the account. Returns a formatted summary.
Parameters:
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 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), optionally filtered by search. 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
search (optional): Case-insensitive text matched against the thread subject and the from/to/cc/bcc addresses of its messages. Pass the same value when paginating
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
list-inbound-forward-rules
List the forward rules of an inbound inbox. Returns a formatted summary.
Parameters:
inbox_id (required): ID of the inbox
get-inbound-forward-rule
Get a single inbound forward rule by ID. Returns the full rule record, including its conditions and destinations, as JSON.
Parameters:
inbox_id (required): ID of the inbox
forward_rule_id (required): ID of the forward rule
create-inbound-forward-rule
Create a forward rule on an inbound inbox. Received messages matching all conditions are forwarded to the rule's destinations.
Parameters:
inbox_id (required): ID of the inbox
name (required): Rule name, unique within the inbox
conditions (optional): Array of { match_type, operator, value?, header_key? }. match_type is sender, recipient, or header; operator is equal, not_equal, contains, starts_with, ends_with, empty, or not_empty (empty/not_empty only for header, and take no value); header_key is required for header. Omit or pass [] to match every message
destinations (optional): Array of { email } to forward matching messages to
update-inbound-forward-rule
Update an inbound forward rule. Only the provided fields change; a provided conditions or destinations array replaces the whole set.
Parameters:
inbox_id (required): ID of the inbox
forward_rule_id (required): ID of the forward rule
name (optional): New rule name
conditions (optional): Replacement condition set (same shape as on create); [] removes all conditions, so the rule matches every message
destinations (optional): Replacement destination set; [] removes all destinations
delete-inbound-forward-rule
Permanently delete an inbound forward rule.
Parameters:
inbox_id (required): ID of the inbox
forward_rule_id (required): ID of the forward rule
Development
- Clone the repository:
git clone https://github.com/mailtrap/mailtrap-mcp.git
cd mailtrap-mcp
- Install dependencies:
Configuration with Claude Desktop or Cursor
TIP
See the location of the config file in the Setup section.
Add the following configuration:
{
"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)
{
"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": "22.14.0",
"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 section.
{
"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
There are two ways to exercise a tool end-to-end against a real Mailtrap account: the MCP 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:
and MAILTRAP_API_TOKEN + MAILTRAP_ACCOUNT_ID exported in your shell (the mcp:cli script forwards both to the spawned server).
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 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:
npm run mcp:cli -- --method tools/list
npm run mcp:cli -- \
--method tools/call \
--tool-name get-template \
--tool-arg template_id=12345
npm run mcp:cli -- \
--method tools/call \
--tool-name send-domain-setup-instructions \
--tool-arg domain_id=3938 \
--tool-arg email=devops@example.com
Running the MCPB Server
node dist/mcpb-server.js
mailtrap-mcpb-server
TIP
For development with the MCP Inspector:
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.
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:
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "error")'
node dist/mcpb-server.js 2>&1 | jq 'select(.level == "debug")'
Troubleshooting
Common issues:
- Missing API Token: ensure
MAILTRAP_API_TOKEN is set
- 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
- Timeout errors: check network connectivity and Mailtrap API status
- Validation errors: ensure all required fields are provided
Contributing
Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
The package is available as open source under the terms of the MIT License.
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.