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:

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. If from_email and to_email are provided, the tool may attempt to send a test email. Only provide these fields if you are authorized to send from the account and intentionally want to test 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.

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.

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

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 Agent Skills format is an open standard adopted by Claude, Codex, Gemini CLI, GitHub Copilot, Cursor, VS Code, and 30+ other 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: