MCP Server

Add a custom connector from the app — no config file needed:

1. Open Settings → Connectors and click Add custom connector.
2. Name it Unspam and set the URL to https://api.unspam.email/mcp.
3. Click Connect and complete the OAuth sign-in in the browser window that opens.

If your build does not offer custom connectors, bridge the remote server through mcp-remote in claude_desktop_config.json (Settings → Developer → Edit Config). It requires Node.js:

{
  "mcpServers": {
    "unspam": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.unspam.email/mcp"]
    }
  }
}

Restart Claude Desktop; a browser opens once to authorize, and the token is cached for future launches.

Add the server with the CLI, then authenticate from inside a session:

claude mcp add --transport http unspam https://api.unspam.email/mcp

Start Claude Code and run /mcp; select unspam and follow the OAuth prompt to sign in. Add --scope project to the command above to share the server with your team via a checked-in .mcp.json:

{
  "mcpServers": {
    "unspam": {
      "type": "http",
      "url": "https://api.unspam.email/mcp"
    }
  }
}

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "unspam": {
      "url": "https://api.unspam.email/mcp"
    }
  }
}

Open Settings → MCP, confirm unspam is listed, and click Login / Needs login to complete the OAuth flow. The Unspam tools then become available to the agent.

Remote MCP connectors are available in ChatGPT's Developer Mode (Plus, Pro, and Business plans):

1. In Settings → Connectors, enable Developer mode.
2. Click Create / Add custom connector and set the MCP server URL to https://api.unspam.email/mcp.
3. Choose OAuth as the authentication method — the Authorization, Token, and Registration URLs are discovered automatically.
4. Save, then click Connect and sign in to Unspam to approve access.
5. Enable the connector in the composer to let ChatGPT call the Unspam tools.

For Windsurf, add the server under mcpServers in ~/.codeium/windsurf/mcp_config.json using the serverUrl field, then press the refresh button in the Cascade MCP panel to trigger the OAuth login:

{
  "mcpServers": {
    "unspam": {
      "serverUrl": "https://api.unspam.email/mcp"
    }
  }
}

Any other MCP-compatible client works the same way — register a remote/streamable HTTP server pointed at https://api.unspam.email/mcp and complete the OAuth sign-in. Clients that only support stdio servers can bridge through npx -y mcp-remote https://api.unspam.email/mcp, as shown for Claude Desktop above.

Handshake. Returns the protocol version and server info.

curl -X POST https://api.unspam.email/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "unspam", "version": "1.0.0" }
  }
}

Returns the catalog of available tools, each with a JSON Schema inputSchema. This is the authoritative, machine-readable description of every tool and its parameters.

curl -X POST https://api.unspam.email/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

Invokes a tool by name with arguments. The result payload is a JSON document returned as text content.

curl -X POST https://api.unspam.email/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_spam_check_result",
      "arguments": { "id": "abc123" }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [ { "type": "text", "text": "{ \"id\": \"abc123\", \"status\": \"completed\", ... }" } ]
  }
}

Notifications (requests without an id) receive an empty 202 response.

Start a check, send your email to the returned address, then fetch the result.

# 1. Start
{ "name": "start_spam_check", "arguments": {} }
# -> { "id": "abc123", "inbox_address": "abc123@inbox.unspam.email" }

# 2. Send your email to abc123@inbox.unspam.email, wait a moment.

# 3. Fetch the result
{ "name": "get_spam_check_result", "arguments": { "id": "abc123" } }

For the smtp service, settings is required with from_name, from_email, and an smtp object. headers is optional.

{
  "name": "create_scheduled_test_sender",
  "arguments": {
    "name": "My Sender",
    "service": "smtp",
    "settings": {
      "from_name": "Admin",
      "from_email": "admin@no-reply.com",
      "smtp": {
        "host": "smtp.example.com",
        "port": 465,
        "protocol": "SSL",
        "username": "user@example.com",
        "password": "password"
      },
      "headers": {}
    }
  }
}
# -> { "id": "2ded86a5-...", "name": "My Sender", "service": "smtp", "settings": { ... }, "error_code": null }

Step 1. Create a draft test.

{ "name": "create_scheduled_test", "arguments": {} }
# -> { "id": "9b1c7e84-...", "status": "draft", "inbox_address": "test-9b1c7e84@inbox.unspam.email" }

Step 2. Send the email you want to test to the returned inbox_address, then poll until the template is captured.

{ "name": "get_scheduled_test", "arguments": { "id": "9b1c7e84-..." } }
# Wait until email_subject / email_from are no longer null.

Or skip steps 2 entirely and set the template directly from content with set_scheduled_test_email:

{
  "name": "set_scheduled_test_email",
  "arguments": {
    "id": "9b1c7e84-...",
    "subject": "Welcome to our newsletter",
    "html": "<h1>Hello!</h1><p>Thanks for subscribing.</p>",
    "from": "news@yourdomain.com",
    "headers": {
      "Reply-To": "support@yourdomain.com",
      "List-Unsubscribe": "<https://yourdomain.com/unsubscribe?id=123>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
    }
  }
}

Step 3. Configure the test. Use a sender id as sender_uuid and mailbox IDs from list_mailboxes as providers.

{
  "name": "configure_scheduled_test",
  "arguments": {
    "id": "9b1c7e84-...",
    "name": "My automatic test",
    "status": "active",
    "sender_uuid": "2ded86a5-...",
    "providers": [3, 7, 23],
    "schedule": { "start_at": "2026-06-18T10:21:00Z", "type": "week", "days": [] },
    "alert_settings": { "mode": "all", "spam_level": null }
  }
}

Schedule type is one of month, week, days, or specific_days; days (0–6) is required only for specific_days. Alert mode is all or spam_level; spam_level (0–100) is required only for spam_level.

Step 4. Trigger a run now (optional), then fetch its result.

{ "name": "dispatch_scheduled_test", "arguments": { "id": "9b1c7e84-..." } }
# -> { "status": "in_queue", "run_id": "f47ac10b-..." }

{ "name": "get_scheduled_test_run", "arguments": { "id": "9b1c7e84-...", "run_id": "f47ac10b-..." } }