Overview

mailX exposes all email deliverability tools via MCP (Model Context Protocol) — the open standard for connecting AI agents to external tools. Any agent that speaks MCP can call mailX tools directly: check SPF, DKIM, DMARC, blacklists, test SMTP/IMAP, and generate DNS records.

Supported by Claude (Desktop, Code, API), ChatGPT (Connectors), Cursor, VS Code, Windsurf, Zed, OpenAI Agents SDK, Anthropic API, and any framework that speaks MCP (LangChain, CrewAI, Vercel AI SDK, etc.).

Quick Start

The fastest way to test — paste this into any terminal:

# 1. Initialize the connection
curl -s -X POST https://themailx.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "id": 1,
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": {"name": "curl-test", "version": "1.0"}
    }
  }'

# 2. List available tools
curl -s -X POST https://themailx.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

# 3. Call a tool
curl -s -X POST https://themailx.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 3,
    "params": {
      "name": "spf_check",
      "arguments": {"domain_name": "google.com"}
    }
  }'

Protocol Details

Transport

mailX uses the Streamable HTTP transport defined in the MCP specification. All communication is via POST to a single endpoint. Each request is a JSON-RPC 2.0 message; each response is a JSON object with Content-Type: application/json.

Lifecycle

1. initialize — Client sends its capabilities and protocol version. Server responds with its capabilities, server info, and human-readable instructions.
2. notifications/initialized — Client acknowledges initialization (no response expected).
3. tools/list — Fetch the list of available tools with input schemas and annotations.
4. tools/call — Call a tool with arguments. Server returns the result.
5. prompts/list — Fetch the list of one-click prompts (see Prompts).
6. prompts/get — Fetch a specific prompt rendered with arguments.
7. resources/list — Fetch the list of resources the server exposes (see Resources).
8. resources/read — Read a specific resource by URI.
9. resources/templates/list — List parameterized resource templates (none currently — returns empty array).
10. ping — Health check. Server returns an empty result.

Tool Annotations

Every tool in tools/list includes an annotations object that tells agents about the tool's behavior:

ChatGPT endpoint

ChatGPT connects to https://themailx.com/mcp/chatgpt. It is the same server without smtp_check and imap_check, because those take mailbox credentials. Everything else on this page applies to both endpoints.

Error Handling

Tool errors (invalid arguments, failed checks) are returned inside the result object with "isError": true, not as JSON-RPC protocol errors. This follows the MCP spec recommendation so the agent can self-correct. Calling a tool that doesn't exist on the endpoint returns a JSON-RPC error with code -32602.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "{\"errors\": {\"domain_name\": [\"Required\"]}}"}],
    "isError": true
  }
}

Available Tools

SPF spf_check

Use this when the user asks whether a domain's SPF record is valid, which servers may send email for a domain, or why SPF fails. Returns the live SPF record, a pass/fail status and a fix suggestion.

DKIM dkim_check

Use this when the user wants to verify DKIM for a domain. Pass the DKIM selector if known (for example google for Google Workspace, selector1 or selector2 for Microsoft 365). If the selector is unknown, omit it: mailX then tries common selectors and returns the ones it finds. Returns the published key and its status. A miss on common selectors does not prove DKIM is absent.

DMARC dmarc_check

Use this when the user asks about DMARC, spoofing protection, or what happens to emails that fail authentication. Returns the live DMARC record, its policy and a fix suggestion.

BIMI bimi_check

Use this when the user asks about BIMI or showing a brand logo next to their emails in inboxes. Returns the live BIMI record, the logo URL it declares, and a fix suggestion.

DMARC Generator dmarc_generate

Use this when the user needs a DMARC record. Returns the record name, value and type ready to publish. mailX does not publish it.

SPF Generator spf_generate

Use this when the user needs a new SPF record for their email provider. Returns a TXT record ready to publish, or explains what to set up instead when the provider does not need a root SPF include. mailX does not publish it.

SMTP Checker smtp_check

Use this only when the user explicitly asks to test an SMTP login for a mail account they control and provides its credentials. Connects to the SMTP server and reports whether connection, encryption and authentication succeed. If from_email and to_email are both given, it also sends one test email. Credentials are not stored.

IMAP Checker imap_check

Use this only when the user explicitly asks to test an IMAP login for a mailbox they control and provides its credentials. Connects to the IMAP server and reports whether connection, encryption and authentication succeed. Credentials are not stored.

SMTP Finder smtp_finder

Use this when the user needs the outgoing mail (SMTP) server settings for an email provider or sending service, such as Gmail, Outlook, Microsoft 365, Zoho, Amazon SES or SendGrid. Returns the host, ports with encryption, what to use to log in, and the provider's setup guide. Never asks for the user's credentials.

IMAP Finder imap_finder

Use this when the user needs the incoming mail (IMAP) server settings for an email provider, such as Gmail, Outlook, Yahoo, iCloud or Zoho. Returns the host, ports with encryption and the provider's setup guide. Never asks for the user's credentials.

Blacklist Checker blacklist_check

Use this when the user suspects their domain is blacklisted or blocked. Checks the domain against major DNS blocklists and returns the result for each list.

MX Lookup mx_lookup

Use this when the user wants to know which mail servers receive email for a domain. Returns the domain's live MX records with their priorities.

TXT Lookup txt_lookup

Use this when the user wants to see a domain's TXT records, for example to find verification tokens or check what SPF or other policies are published. Returns all live TXT records.

CNAME Lookup cname_lookup

Use this when the user wants to know whether a hostname is an alias of another one, for example to verify DKIM or tracking CNAMEs. Returns the live CNAME target.

PTR Lookup ptr_lookup

Use this when the user wants the reverse DNS (PTR) of an IP address, for example to check a sending server's reverse DNS. Returns the hostname the IP resolves to.

DNS Lookup dns_lookup

Use this when the user wants every DNS record for a domain in one view (A, AAAA, CNAME, MX, NS, TXT, SOA). Returns the live records grouped by type.

Prompts

mailX exposes two one-click prompts via prompts/list and prompts/get. In clients that support prompts (Claude Desktop, Claude Code, Cursor, Zed, MCP Inspector), they appear in the slash-command menu and let users run a full workflow without composing the agent message themselves.

Example prompts/get call:

curl -s -X POST https://themailx.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "prompts/get",
    "id": 1,
    "params": {
      "name": "audit-deliverability",
      "arguments": {"domain": "example.com"}
    }
  }'

Resources

mailX exposes its Agent Skill as MCP resources over the mailx:// URI scheme. Clients that support resources (Claude Desktop, MCP Inspector, Zed) can attach them as conversation context.

Use resources/list to enumerate them and resources/read with a URI to fetch the content.

Session Config (Smithery / hosted clients)

For aggregators like Smithery that pass user preferences through to the upstream server, mailX reads three optional query parameters at connection time and uses them as defaults whenever the corresponding tool input is omitted from a call:

Example: a client that points at https://themailx.com/mcp?default_dkim_selector=google&preferred_provider=mailgun can then call dkim_check with just {"domain_name": "example.com"} and the server will fill in dkim_selector=google automatically. Defaults never override values explicitly passed in the call.

Claude (Desktop, Web, Code)

Claude Code (CLI & IDE extensions)

Add a .mcp.json file to your project root:

{
  "mcpServers": {
    "mailx": {
      "type": "http",
      "url": "https://themailx.com/mcp"
    }
  }
}

Or via CLI:

claude mcp add --transport http mailx https://themailx.com/mcp

Claude.ai (Web) & Claude Desktop

1. Go to Customize (or Settings) → Connectors
2. Click "+" → Add custom connector
3. Paste this URL:
   https://themailx.com/mcp Copy
4. Click Add — no authentication needed

In a conversation, click "+" → Connectors → toggle mailX on.

Anthropic Messages API

See Anthropic API section below for programmatic usage.

ChatGPT

Custom Apps in ChatGPT (Web UI)

Available on all paid ChatGPT plans (Plus, Pro, Business, Enterprise, Education).

1. Open Settings → Apps → Advanced settings, and enable Developer mode.
2. Return to Apps and click Create.
3. Fill in the form:
   • Name: mailX
   • Description: Email deliverability tools — check SPF/DKIM/DMARC/BIMI, scan blacklists, test SMTP/IMAP, and generate DNS records.
   • Connector URL: https://themailx.com/mcp
   • Authentication: No Authentication
4. Save. mailX tools become available in chat (toggle the connector on per conversation) and in Deep Research.

OpenAI Responses API

See OpenAI Agents SDK section below for programmatic usage.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "mailx": {
      "url": "https://themailx.com/mcp"
    }
  }
}

Restart Cursor. Tools are available in Agent mode (including Plan Mode).

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "mailx": {
      "type": "http",
      "url": "https://themailx.com/mcp"
    }
  }
}

Or use MCP: Add Server from the Command Palette. Tools are available in Copilot Chat agent mode.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mailx": {
      "serverUrl": "https://themailx.com/mcp"
    }
  }
}

Zed

Add to your Zed settings.json:

{
  "context_servers": {
    "mailx": {
      "url": "https://themailx.com/mcp"
    }
  }
}

Tools are available in Zed's Agent Panel.

OpenAI Agents SDK / Responses API

Python SDK

Install with pip install openai-agents, then:

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="mailx",
        params={"url": "https://themailx.com/mcp"},
    ) as mailx:
        agent = Agent(
            name="Email Expert",
            instructions="Use mailx tools to diagnose email deliverability.",
            mcp_servers=[mailx],
        )
        result = await Runner.run(agent, "Audit deliverability for mailwarm.net")
        print(result.final_output)

asyncio.run(main())

Responses API (direct)

curl -X POST https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "tools": [{
      "type": "mcp",
      "server_label": "mailx",
      "server_url": "https://themailx.com/mcp",
      "require_approval": "never"
    }],
    "input": "Check the SPF and DMARC records for mailwarm.net"
  }'

Anthropic Messages API

Use MCP tools directly from the Claude API via the MCP Connector:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 4096,
    "mcp_servers": [{
      "type": "url",
      "url": "https://themailx.com/mcp",
      "name": "mailx"
    }],
    "tools": [{
      "type": "mcp_toolset",
      "mcp_server_name": "mailx"
    }],
    "messages": [{
      "role": "user",
      "content": "Run a full deliverability audit on mailwarm.net"
    }]
  }'

Agent Skill

mailX also publishes an Agent Skill — a markdown file (SKILL.md) that teaches AI agents how and when to use the MCP tools effectively.

The skill covers: diagnostic workflows, error interpretation, fix recommendations, and best-practice audit sequences.

Install via Claude Code

/plugin marketplace add Mailwarm/mailx-skills
/plugin install email-deliverability@mailx-skills

Claude.ai (web)

First enable Code Execution and File Creation under Settings → Capabilities (skills require them). Then download email-deliverability.zip, go to Settings → Capabilities → Skills, click Upload, and select the file.

Direct URL

The live SKILL.md is always available at:

https://themailx.com/skills/email-deliverability/SKILL.md

Point any agent that supports skills at this URL. It updates dynamically as tools are added or modified.

Discovery Endpoints

Agents and clients can auto-discover the MCP server and skill via these standard endpoints: