Feature 04 — MCP & API

Your AI agents get deliverability as a native tool.

SimplyWarmup runs as a Model Context Protocol (MCP) server. That means your AI agents — whether they're Claude, GPT-4, or custom — can query inbox health, halt campaigns, and provision inboxes directly from within the agent runtime.

Read Docs All Features

mcp-config.json

{
  "mcpServers": {
    "simplywarmup": {
            "type": "streamable-http",
            "url": "https://simplywarmup.com/mcp",
            "headers": {
                "Authorization":
                    "Bearer sw_live_*******************"
      }
    }
  }
}

What the MCP server exposes.

These tools are available directly to any MCP-compatible agent. They are namespaced to mirror the API domains, so reporting lives under reports.* and inbox operations live under inboxes.*.

Available MCP Tools

Tools your AI agents can invoke natively via the MCP protocol.

Tool Name	Description	Agent Use Case
reports.get	Returns the full reporting overview for the authenticated tenant	Top-level reporting snapshot
reports.summary.get	Returns summary metrics for volume, health, and active inboxes	Quick readiness check
reports.attention_required.get	Returns the inboxes that currently need operator or agent attention first	Escalation queue
reports.deliverability_trend.get	Returns the recent day-by-day deliverability trend for the tenant	Trend monitoring
inboxes.list	Returns all connected inboxes for the authenticated tenant with current health and pacing configuration	Fleet health monitoring
inboxes.get	Returns metrics and warmup details for a specific inbox	Inspect one sender
inboxes.health.get	Returns numerical health score (0–100) and current outreach safety state for a connected inbox	Check before campaign send
inboxes.providers.authorize_url.get	Returns the provider authorization URL and state token for Google Workspace or Microsoft 365 onboarding	Start OAuth inbox connection
inboxes.providers.connect	Completes the provider OAuth callback and returns the connected inbox details	Finish OAuth onboarding
inboxes.direct.connect	Validates and stores direct IMAP or POP plus SMTP credentials for a mailbox	Manual inbox onboarding
inboxes.pause	Pauses warmup activity on a specific inbox without disconnecting it	Agent-triggered risk halt
inboxes.resume	Resumes warmup activity on a paused inbox	Auto-resume after cooldown
inboxes.warmup.get_config	Returns current pacing configuration, target volume, and reply rate for an inbox	Inspect warmup parameters
inboxes.warmup.update	Updates pacing targets and reply rate for an inbox	Dynamic pacing adjustment

The Safety Interlock pattern.

The most common use case for the MCP integration is an AI sales agent querying inbox health before executing a large outbound campaign. If reputation has dipped — perhaps due to a provider issue or recent negative signals — the agent can halt or reroute the campaign and let warmup continue.

This pattern helps protect domains from deeper reputation damage during high-volume send events. In a fully autonomous AI outbound stack, it acts as a circuit breaker that reduces the chance of one degraded inbox pulling the rest of the system in the wrong direction.

Health threshold recommendation: halt campaigns if inbox score drops below 90.

agent-sdr.ts — Safety Interlock

// Before each campaign send cycle
async function runCampaignSafely(inboxId: number) {

    const health = await mcp.callTool("inboxes.health.get", { inboxId });

    if (health.structuredContent.healthScore < 90) {
    // Reputation at risk — do not send
        await mcp.callTool("inboxes.pause", { inboxId });
        await notifyTeam(`Score: ${health.structuredContent.healthScore} — paused`);
    return;
  }

  // Health confirmed — proceed with campaign
  await sendCampaignEmails(inboxId);
}

REST API for non-MCP workflows.

All MCP tools are also available as authenticated REST endpoints for teams not yet using an MCP-compatible agent runtime.

GET /api/v1/inboxes List all connected inboxes with health scores

GET /api/v1/inboxes/{'{id}'}/health Health score & status for a specific inbox

POST /api/v1/inboxes/{'{id}'}/pause Pause warmup for a specific inbox

POST /api/v1/inboxes/{'{id}'}/resume Resume a paused inbox

PUT /api/v1/inboxes/{'{id}'}/warmup-config Update warmup pacing configuration

Full API Documentation AI Agent Use Cases

FAQ

Common questions about MCP integration

What is MCP and why does it matter for email infrastructure?

MCP (Model Context Protocol) is an open standard that lets AI language models communicate with external tools and services in a structured, authenticated way. For email infrastructure, this means an AI agent running outbound campaigns can directly query inbox health, pause campaigns when reputation drops, and resume when health recovers — all without human intervention. SimplyWarmup exposes a native MCP server so AI agents have first-class access to deliverability data.

Can AI agents safely run autonomous cold email campaigns?

Yes — when they have access to real-time inbox health data. The risk in autonomous email sending is not the AI itself but the absence of circuit-breakers. If an agent continues sending from an at-risk inbox, it can worsen domain reputation quickly. SimplyWarmup's MCP tools expose health scores and reputation status so agents can implement pause and resume logic before the inbox degrades further. The inboxes.health.get check should be a prerequisite in any autonomous outbound workflow.

Is it safe to give an AI agent write access to warmup controls?

SimplyWarmup's API uses bearer token authentication over HTTPS. API keys are tenant-scoped and can be generated, rotated, or revoked from the developer workspace. The MCP server only controls warmup state and surfaces health metrics for the authenticated tenant; it does not access the contents of your cold email campaigns. Keep the key in server-side configuration and rotate or revoke it if agent access should change.

Does SimplyWarmup support the REST API independently of MCP?

Yes. Every capability currently exposed through the MCP server is also available through the REST API. If your automation stack doesn't support MCP yet, you can call the JSON REST endpoints directly with bearer token authentication. Today that programmatic surface is focused on reports and inbox operations, including reporting, inbox fleet management, health checks, provider connection flows, pause and resume actions, and warmup configuration updates. The customer dashboard, billing, and developer workspace still include app-only views beyond the current REST and MCP surface.

MCP server endpoint: https://simplywarmup.com/mcp — Streamable HTTP transport, compatible with MCP-compliant runtimes. Requires Bearer token auth on the Authorization header.

Related Features

Feature 01

Clean Pool Network

The high-trust pool the API exposes health data for.

Feature 02

AI Warmup Engine

Agents can inspect and update warmup configuration as inbox health changes.

Feature 03

Spam Recovery

Recovery metrics are surfaced through the health endpoint.