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 — Client fetches the list of available tools with input schemas and annotations.
4. tools/call — Client calls a tool with arguments. Server returns the result.
5. 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:

Error Handling

Tool errors 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:

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

Available Tools

SPF spf-check

Check if a domain has a valid SPF (Sender Policy Framework) DNS record. SPF specifies which mail servers are authorized to send email on behalf of a domain.

DKIM dkim-check

Check if a domain has a valid DKIM (DomainKeys Identified Mail) DNS record for a given selector. DKIM allows the receiver to verify that an email was sent by the domain owner.

DMARC dmarc-check

Check if a domain has a valid DMARC (Domain-based Message Authentication, Reporting & Conformance) DNS record. DMARC tells receiving servers what to do with emails that fail SPF or DKIM checks.

BIMI bimi-check

Check if a domain has a valid BIMI (Brand Indicators for Message Identification) DNS record. BIMI allows brands to display their logo next to authenticated emails in supporting email clients.

DMARC Generator dmarc-generate

Generate a DMARC DNS record for a domain. Returns the record name, value, and type ready to be added to DNS.

SPF Generator spf-generate

Generate an SPF DNS record for a domain based on the email provider being used. Returns the record name, value, and type ready to be added to DNS.

SMTP Checker smtp-check

Test an SMTP server connection by attempting to connect and authenticate. Optionally sends a test email to verify full sending capability.

IMAP Checker imap-check

Test an IMAP server connection by attempting to connect and authenticate. Use this to verify email receiving configuration.

SMTP Finder smtp-finder

Look up SMTP server settings (host, port, encryption) for a given email provider. Use this to find the correct SMTP configuration for services like Gmail, Outlook, SendGrid, etc.

IMAP Finder imap-finder

Look up IMAP server settings (host, port, encryption) for a given email provider. Use this to find the correct IMAP configuration for services like Gmail, Outlook, Yahoo, etc.

Blacklist Checker blacklist-check

Check if a domain or IP address is listed in popular email blacklists (DNSBLs). Being blacklisted can severely impact email deliverability.

BIMI Host bimi-host

Host and serve your BIMI SVG file for email authentication

MX Lookup mx-lookup

Look up MX (Mail Exchanger) records for a domain. Returns the mail servers and their priorities.

TXT Lookup txt-lookup

Look up all TXT records for a domain. TXT records contain SPF policies, domain verification tokens, DKIM keys, and other metadata.

CNAME Lookup cname-lookup

Look up CNAME (Canonical Name) records for a domain. Shows where a hostname aliases to.

PTR Lookup ptr-lookup

Reverse DNS lookup. Find the hostname associated with an IP address. A valid PTR record is important for email sending reputation.

DNS Lookup dns-lookup

Look up all DNS records for a domain in one query. Returns A, AAAA, CNAME, MX, NS, TXT, and SOA records.

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: https://themailx.com/mcp
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

ChatGPT Connectors (Web UI)

1. Go to Settings → Connectors (requires Plus/Pro/Team/Enterprise)
2. Click Advanced → Developer Mode
3. Add a custom MCP server with URL: https://themailx.com/mcp

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 Composer and Agent 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

from agents.mcp import MCPServerStreamableHttp
from agents import Agent

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],
    )
    # Run the agent...

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-4.1",
    "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-sonnet-4-5-20250514",
    "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 Agent Skills format is an open standard adopted by Claude, ChatGPT/Codex, Gemini CLI, GitHub Copilot, and 30+ agent products.

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

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: