MailOdds MCP Server

"The Autonomous Deliverability Architect"

Plug MailOdds into any AI agent (Claude, Cursor, Windsurf, custom) and let it autonomously manage the full Trust Cycle: auditing DNS with DMARC monitoring, enforcing validation policies, executing safe transactional sends via the Email Sending API, running spam checks, monitoring blacklist status, tracking email analytics, and syncing e-commerce product catalogs without writing a single line of integration code.

Tools (190 total, highlights below)

| Pillar | Tools | |---|---| | Onboarding | onboarding_probe | | Validation | validate_email, validate_batch | | Stateful Jobs | validate_and_watch (long-poll + progress), create_bulk_job, get_job_status, get_job_results, list_jobs, cancel_job | | Consultative Identity | remediate_domain (copy-paste DNS records), get_identity_score, list_sending_domains, add_sending_domain, get_sending_stats | | Policy Engine | enforce_policy, create_policy_from_preset, test_policy, list_policies, delete_policy | | Suppression | check_suppression, add_suppression, remove_suppression, suppression_audit, suppression_stats | | Safe Sending | safe_deliver (auto AI summary + validate_first), batch_deliver | | Subscriber Lifecycle | create_subscriber_list, list_subscribers, unsubscribe | | Telemetry & Guardian | get_telemetry (ETag-cached), watch_telemetry (threshold observer), subscribe_guardian, unsubscribe_guardian, get_guardian_status | | Store Connections | list_stores, connect_store, disconnect_store, sync_store, get_store_status | | Product Queries | query_products, get_product | | OAuth Apps | list_oauth_apps, create_oauth_app | | Profile Management | add_profile, switch_profile, list_profiles | | Health | health_check |

Resources

| URI | Description | |---|---| | mailodds://telemetry/realtime | Live 1h validation metrics | | mailodds://audit/suppression | Last 50 suppression change events | | mailodds://domains/health | All domains with identity scores |

Requirements

• Node.js >= 18 (zero external npm dependencies)
• A MailOdds API key (get one at mailodds.com/dashboard)

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | MAILODDS_API_KEY | Yes | -- | Your MailOdds API key (mo_live_ or mo_test_ prefix) | | MAILODDS_API_BASE | No | https://api.mailodds.com | Override API base URL | | MAILODDS_MCP_TRANSPORT | No | stdio | stdio, streamable-http, or sse (legacy) | | MAILODDS_MCP_PORT | No | 3741 | Port for HTTP/SSE transport | | MAILODDS_MCP_SSE_BIND | No | 127.0.0.1 | Bind address for HTTP/SSE transport | | MAILODDS_MCP_SSE_TOKEN | No | -- | Bearer token to protect legacy SSE endpoints | | MAILODDS_MCP_ALLOWED_ORIGINS | No | -- | Additional allowed Origin headers (comma-separated) | | MAILODDS_PROFILES | No | -- | Pre-load named profiles: name1:mo_live_xxx,name2:mo_test_yyy |

Quickstart

Prerequisites

1. Get your API key from the MailOdds dashboard (starts with mo_live_ or mo_test_)
2. Node.js >= 18 installed

Cursor / VS Code

Open Settings > MCP (or .cursor/mcp.json / .vscode/mcp.json) and add:

{
  "mcpServers": {
    "mailodds": {
      "command": "npx",
      "args": ["-y", "@mailodds/mcp-server"],
      "env": {
        "MAILODDS_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mailodds": {
      "command": "npx",
      "args": ["-y", "@mailodds/mcp-server"],
      "env": {
        "MAILODDS_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio -e MAILODDS_API_KEY=your_key_here mailodds \
  -- npx -y @mailodds/mcp-server

Remote MCP (Streamable HTTP with OAuth)

For cloud-hosted agents (claude.ai, hosted deployments), use the Streamable HTTP transport with OAuth 2.0 authentication:

MCP Server URL: https://mcp.mailodds.com/mcp

The server supports OAuth 2.0 authorization code flow with PKCE. When connecting from claude.ai, authentication happens via browser login -- no API key needed. The OAuth metadata is discoverable at https://mcp.mailodds.com/.well-known/oauth-authorization-server.

Dynamic Client Registration (RFC 7591) is supported for MCP clients that need to auto-register.

Streamable HTTP (self-hosted)

MAILODDS_MCP_TRANSPORT=streamable-http \
MAILODDS_MCP_PORT=3741 \
MAILODDS_API_KEY=your_key_here \
node index.js

# MCP endpoint:  POST/GET/DELETE http://127.0.0.1:3741/mcp
# Health:        GET  http://127.0.0.1:3741/health
# OAuth metadata: GET http://127.0.0.1:3741/.well-known/oauth-authorization-server

SSE (legacy, backward compatible)

MAILODDS_MCP_TRANSPORT=sse \
MAILODDS_MCP_PORT=3741 \
MAILODDS_API_KEY=your_key_here \
node index.js

# SSE stream:  GET  http://127.0.0.1:3741/sse
# Send msgs:   POST http://127.0.0.1:3741/message

Docker

FROM node:20-alpine
WORKDIR /app
COPY index.js .
ENV MAILODDS_MCP_TRANSPORT=streamable-http
ENV MAILODDS_MCP_PORT=3741
ENV MAILODDS_MCP_SSE_BIND=0.0.0.0
EXPOSE 3741
CMD ["node", "index.js"]

Set MAILODDS_API_KEY at runtime via docker run -e.

Verification

After installation, ask your AI agent:

"List my MailOdds sending domains and tell me their identity grades."

If it returns your domains and scores, you are connected.

Troubleshooting

| Symptom | Fix | |---|---| | npx: command not found | Install Node.js >= 18 | | 401 Unauthorized on every tool call | Check MAILODDS_API_KEY starts with mo_live_ or mo_test_ | | Tools timeout after 30s | The server connects to api.mailodds.com -- check your network/firewall | | SSE endpoint returns 401 | Set Authorization: Bearer <MAILODDS_MCP_SSE_TOKEN> header |

Key Tool Behaviours

onboarding_probe

Zero-click discovery. Call on first connect. Returns:

{
  "greeting": "Connected to MailOdds. Here is your account health snapshot:",
  "account_summary": { "sending_domains": 2, "reject_rate_24h": "3.2%" },
  "domain_health": [{ "domain": "mail.acme.com", "grade": "C", "score": 65 }],
  "recommendations": [
    { "priority": "critical", "action": "Run remediate_domain on 'mail.acme.com' -- grade C." }
  ],
  "suggested_first_action": "Run remediate_domain on 'mail.acme.com'..."
}

remediate_domain

Consultative DNS diagnosis. Returns copy-paste DNS records for every failing check:

{
  "grade": "C",
  "score": 55,
  "urgency": "high",
  "summary": "Domain mail.acme.com scored 55/100 (C). 2 issue(s)...",
  "issues": [
    {
      "check": "DMARC",
      "severity": "high",
      "impact": "Without DMARC, spoofed emails can impersonate your domain...",
      "points_lost": 20
    }
  ],
  "dns_records_to_add": [
    {
      "check": "DMARC",
      "type": "TXT",
      "host": "_dmarc.acme.com",
      "value": "v=DMARC1; p=quarantine; rua=mailto:[email protected]; ...",
      "ttl": 3600,
      "note": "Start with p=none to monitor before enforcing."
    }
  ]
}

validate_and_watch

Long-polling job manager with live progress:

-> "I'm validating your list now (23% complete)..."
-> "Validating 4,500 / 10,000 emails (45%)..."
-> "Validated 10,000 emails. Valid: 8,102, Invalid: 1,203, Do-Not-Mail: 695. Suppression policy created (ID: 42)."

With auto_suppress_high_risk: true, automatically creates a domain blocklist policy for domains with 3+ invalid or disposable emails (top 20). If an auto-suppress policy already exists from a previous job, it merges the new domains into it instead of creating duplicates.

watch_telemetry

Long-polling threshold observer. Polls metrics every 30 seconds for a configurable duration (1-60 minutes). Compares rates against your thresholds and emits MCP progress notifications on breaches:

{
  "watch_id": "a1b2c3d4-...",
  "snapshots_taken": 12,
  "breach_count": 3,
  "breaches": [
    { "timestamp": "2026-03-11T14:30:00Z", "metric": "reject_rate", "value": 0.08, "threshold": 0.05, "snapshot": 4 }
  ],
  "last_rates": { "reject": 0.08, "deliverable": 0.85, "unknown": 0.04, "suppressed": 0.03 }
}

Guardian Mode (subscribe_guardian, unsubscribe_guardian, get_guardian_status)

Persistent background monitoring. Runs independently of tool calls -- once subscribed, the guardian polls telemetry and domain health on a configurable interval (30s-5min, default 60s) and emits notifications/guardian alerts when:

• Telemetry rates breach thresholds (reject/unknown/suppressed above, deliverable below)
• Any domain grade drops below the minimum (default B)
• Any domain DNS status matches alert list (default: pending_dns, dns_partial)

Alerts are deduplicated within a configurable window (default 5 min). Auto-pauses after 10 consecutive API failures. Idempotent: re-subscribing updates config and preserves history.

{
  "guardian_key": "guardian:a1b2c3d4",
  "profile": "production",
  "alert": {
    "type": "telemetry_breach",
    "metric": "reject_rate",
    "value": 0.12,
    "threshold": 0.05,
    "direction": "above"
  }
}

API call budget per tick: 1 (telemetry) + 1 (domains) + N (identity scores, capped at 20) = max 22 calls. At 60s interval = 22 req/min, well within the 100/min rate limit.

Multi-Profile (add_profile, switch_profile, list_profiles)

Manage multiple API keys for different accounts. Pre-load via env var or add at runtime:

MAILODDS_PROFILES="prod:mo_live_abc123,staging:mo_test_xyz789" node index.js

Keys are masked in all responses (mo_live_****c123). Switching profiles immediately affects all subsequent tool calls.

safe_deliver

Always runs with validate_first: true. Auto-generates ai_summary from HTML if not provided -- every email is AI-inbox-optimised before hitting the send pipeline.

Agent Instructions

Copy-paste the block below into your AI agent's system prompt or instruction field.

AGENT MISSION: AUTONOMOUS DELIVERABILITY ARCHITECT

You are an expert Email Deliverability Engineer powered by MailOdds. Your goal is to maintain a Grade A sender reputation for the user.

CORE OPERATING PROCEDURES:

1. PROBE FIRST: Always run onboarding_probe upon initial connection.
2. FIX DNS: If any domain grade is below B, run remediate_domain and provide the copy-paste DNS records to the user immediately.
3. BULK SAFETY: For lists over 100 emails, use validate_and_watch. Always set auto_suppress_high_risk: true to protect the sender reputation.
4. AI-OPTIMIZE: When sending via safe_deliver, ensure the ai_summary is descriptive to help the recipient AI prioritize the message.
5. MULTI-ACCOUNT: If the user manages multiple accounts, use add_profile and switch_profile to switch between them. Always confirm which profile is active before performing destructive operations.
6. MONITOR: Use watch_telemetry for short-term monitoring (1-60 min). Set thresholds based on their stated tolerance (e.g. "alert if reject > 5%").
7. GUARDIAN: Use subscribe_guardian for persistent background monitoring. Recommend it when users ask about ongoing monitoring, alerting, or reputation tracking. Guardian runs independently and emits alerts via notifications/guardian.
8. STORE SYNC: Use connect_store + sync_store to import product catalogs from e-commerce platforms. Use query_products to find products for campaign content.
9. OAUTH: Use create_oauth_app when users want to build integrations that authenticate via OAuth 2.0 instead of API keys.

First-Run Guide

Give your users these three prompts to experience the full pipeline:

1. Account Health Check

Prompt: "Analyze my MailOdds account health and tell me the first three things I should do to improve my deliverability."

Triggers: onboarding_probe -> domain grades, reject rate, policy audit, prioritized action list.

2. DNS Fixer

Prompt: "My emails to Gmail are bouncing. Check my sending domains and give me the exact DNS records I need to add."

Triggers: remediate_domain -> per-check severity, copy-paste DNS records (SPF, DKIM, DMARC, MX, Return Path, BIMI).

3. Protected List Upload

Prompt: "I have a list of 5,000 leads. Validate them, keep me updated on progress, and automatically block any toxic domains you find."

Triggers: validate_and_watch(auto_suppress_high_risk: true) -> live progress notifications -> auto-creates domain blocklist policy.

More Examples

"Why is my email bouncing from mail.acme.com?"
-> AI calls: remediate_domain
-> Returns: SPF missing + copy-paste DNS record

"Validate this 50,000-row list and block the bad domains we find"
-> AI calls: validate_and_watch(auto_suppress_high_risk: true)
-> Streams progress, then creates a suppression policy automatically

"What's our deliverability look like today? Any red flags?"
-> AI calls: get_telemetry(window: "24h") + suppression_audit
-> Returns: reject rates, top reasons, recent suppression events

"Send a welcome email to [email protected] -- but only if it's clean"
-> AI calls: safe_deliver(validate_first: true)
-> Returns: queued + pre-send validation result

Architecture

AI Agent (Claude / Cursor / custom)
    |  JSON-RPC 2.0
    |  stdio (local)  --------+
    |  Streamable HTTP (remote)+-- POST/GET/DELETE /mcp
    |  SSE (legacy)  ---------+
    v                         v
@mailodds/mcp-server  (Node.js, zero deps)
    |  HTTPS + Bearer token (API key or OAuth JWT)
    v
api.mailodds.com/v1

Design principles

• Zero dependencies -- only Node.js built-ins (https, crypto, readline, http)
• ETag caching on telemetry -- avoids wasted API calls across agent turns
• Auto idempotency keys -- every bulk job gets a UUID idempotency_key
• Auto AI summary -- safe_deliver strips HTML -> generates ai_summary automatically
• Progress notifications -- validate_and_watch emits notifications/progress every 4s
• Consultative outputs -- remediate_domain and onboarding_probe return human-readable guidance, not raw API responses
• Policy deduplication -- auto-suppress merges into existing policies instead of creating duplicates
• Guardian Mode -- persistent background monitoring with deduplicated alerts and auto-pause on failures
• Environment safety -- destructive tools label responses with _environment (test/live) and _profile

Security

• API key read from environment variable only -- never hardcoded, never logged
• API key format validated on startup (warns if prefix does not match mo_live_ or mo_test_)
• Bearer token injected per-request, not stored in memory beyond process lifetime
• SSE transport binds to 127.0.0.1 by default -- set MAILODDS_MCP_SSE_BIND=0.0.0.0 to expose
• Optional MAILODDS_MCP_SSE_TOKEN enforces Bearer auth on SSE endpoints

MailOdds Platform

MailOdds provides a complete email deliverability platform accessible through this MCP server:

• Email Validation API - Real-time email verification with 25+ checks
• Bulk Email Validation - Validate lists up to 500,000 emails
• Email Deliverability Platform - End-to-end deliverability management
• Email Suppression List - Automated bounce and complaint suppression
• Sender Reputation - Real-time sender health scoring
• API Reference - Complete API documentation
• Guides: Email Authentication - SPF, DKIM, and DMARC setup guides
• Security - Platform security practices

Why MailOdds

MailOdds is a complete email deliverability platform built for developers. Every email validated or sent through MailOdds passes through 25+ real-time checks including syntax verification, DNS and MX validation, SMTP mailbox probing, disposable domain detection, and role account identification.

The platform maintains sub-200ms median response times for single validations, 99.9% API uptime, and processes bulk lists of up to 500,000 emails per job. MailOdds supports 11 language SDKs, an MCP server for AI agent integration, a CLI for local development, and a WordPress plugin for no-code deployments.

All email sending uses DKIM dual signing with automated key rotation, and the deliverability monitoring stack covers DMARC aggregate reports, blacklist surveillance across 80+ DNSBLs, and real-time sender health scoring.

Prompts (Guided Workflows)

The server provides 5 guided prompts for common deliverability workflows:

| Prompt | Description | |--------|-------------| | diagnose-domain-health | Full email authentication audit with copy-paste DNS fix records | | clean-email-list | Validate a list and auto-suppress risky domains | | monitor-sender-reputation | Start persistent Guardian monitoring with breach alerts | | send-safe-email | Send a transactional email through the safety pipeline | | setup-dmarc-monitoring | Add a domain to DMARC monitoring and get upgrade recommendations |

Usage Examples

Example 1: Domain Health Audit

User prompt: "Check my domain's email authentication and tell me what DNS records I need to add."

What happens: The agent calls onboarding_probe to get the account health snapshot, identifies domains with grades below B, then calls remediate_domain for each. Returns a prioritized list of failing checks (SPF, DKIM, DMARC, MX, Return Path) with severity ratings and exact DNS records to copy-paste into the DNS provider.

Expected outcome:

• Domain grades (A-F) for all sending domains
• Per-check severity breakdown (critical/high/medium/low)
• Copy-paste DNS records with host, type, value, and TTL for every failing check
• Next-step recommendation (e.g., "Add these records, then re-run to verify")

Example 2: List Cleaning with Auto-Suppression

User prompt: "I have a list of 2,000 subscriber emails. Validate them and automatically block any risky domains."

What happens: The agent calls validate_and_watch with auto_suppress_high_risk: true. The server creates a bulk validation job and polls it every 4 seconds, emitting live progress notifications ("Validating 800 / 2,000 emails (40%)..."). After completion, it automatically creates a domain-filter suppression policy blocking domains with 3+ invalid or disposable emails.

Expected outcome:

• Live progress updates during validation
• Final summary: deliverable count, invalid count, risky count, unknown count
• Name and ID of the suppression policy created
• List of blocked domains with rejection counts

Example 3: Sender Reputation Monitoring

User prompt: "Start monitoring my sender reputation and alert me if my reject rate goes above 5%."

What happens: The agent calls subscribe_guardian with a reject_rate threshold of 0.05 and domain grade minimum of B. Guardian starts polling telemetry and domain health every 60 seconds in the background. When the reject rate exceeds 5% or any domain grade drops below B, it emits a notifications/guardian alert.

Expected outcome:

• Confirmation that Guardian is active with the configured thresholds
• Explanation of what alerts will look like (telemetry breach, domain grade drop, DNS status change)
• Current rates as a baseline snapshot
• Instructions for checking status (get_guardian_status) or stopping (unsubscribe_guardian)

Tool Discovery

For programmatic tool and scope discovery, the backend exposes a public capabilities endpoint:

GET https://api.mailodds.com/v1/mcp/capabilities

Returns all 190 tools organized by pillar, with required OAuth scopes for each tool.

Privacy and Support

• Privacy Policy: mailodds.com/privacy
• Support: GitHub Issues or email [email protected]
• Documentation: mailodds.com/docs
• Status: status.mailodds.com

Other SDKs

| Language | Package | Source | |----------|---------|--------| | Python | PyPI | GitHub | | TypeScript | npm | GitHub | | PHP | Packagist | GitHub | | Java | GitHub | GitHub | | Go | pkg.go.dev | GitHub | | C# / .NET | GitHub | GitHub | | Ruby | RubyGems | GitHub | | Kotlin | GitHub | GitHub | | Rust | crates.io | GitHub | | Swift | GitHub | GitHub | | Dart / Flutter | pub.dev | GitHub |

Resources

• Documentation
• Developer Quickstart
• All SDKs
• Security
• Pricing

License

MIT