MCP Hosted MCP server · the agent interface to NuMail

Give your agent
a cold-email stack.

NuMail speaks the Model Context Protocol. Point Claude Code, Cursor, OpenAI Codex, or any MCP-compatible client at https://www.numail.ai/api/mcp and it can build and launch campaigns, add and suppress leads, check mailbox health, read the unibox, and send replies, by name, with no glue code, no scraping the dashboard.

30-second install →See the tool catalog

~ ▸ claude code · numail session● numail · tools loaded

▸ "Spin up a campaign for the leads in mercer.csv from tomas@mercer.com. Two steps, 3 days apart."
   list_mailboxes({ provider: "google" })
   → tomas@mercer.com · healthy
   create_campaign({
     name: "Mercer · Q3 outbound",
     mailboxIds: ["mbx_41a"],
     leads: [ … 1,204 rows from mercer.csv ],
     seqSteps: [{ delayDays: 0, … }, { delayDays: 3, … }]
   })
   ✓ cmp_7d2 created · draft

▸ "Looks good. Launch it."
   launch_campaign({ campaignId: "cmp_7d2" })
   ✓ launched · 1,204 leads enrolled

▸ "Who replied positive today? Draft short responses."
   list_replies({ classification: "positive" })
   → 6 threads · reading…
   get_thread({ threadId: "thr_2c1" })
   ✓ 6 short drafts ready for your approval

▸ Supported clients

Runs in the agent you already use.

NuMail's MCP server is hosted and speaks Streamable HTTP. If your client can reach a remote MCP server with a header, it works. Here are the ones our customers wire up most.

Claude Code

.mcp.json

Claude Desktop

connector · mcp-remote

Cursor

.cursor/mcp.json

OpenAI Codex

CLI · config.toml

Windsurf

mcp_config.json

Cline

VS Code ext.

Zed

settings.json

∞

Any MCP client

Streamable HTTP

Same https://www.numail.ai/api/mcp URL and Bearer header everywhere; only the config keys differ. Custom agent runtime? It's JSON-RPC over HTTPS POST, so any MCP SDK client connects.

▸ Install · 30 seconds

One key. One config block.

No NuMail package to install or update: the server runs at https://www.numail.ai/api/mcp and your client sends the key in a header. Claude Desktop is the one exception: it reaches the server through the open-source mcp-remote bridge, which needs Node 18 or later. Mac, Windows, Linux.

Get a scoped API key

In NuMail · Settings · MCP, click Generate key & copy config, or create a key with the mcp:* scope in Settings · API Keys. Each key reaches one workspace.

Authorization: Bearer nm_live_•••

Add the server block

Drop this into your client's MCP config (Claude Code .mcp.json shown). Cursor, Windsurf and Zed take the same URL and header; Cline also needs "type": "streamableHttp"; Codex sets them in config.toml.

{ "mcpServers": { "numail": { "type": "http", "url": "https://www.numail.ai/api/mcp", "headers": { "Authorization": "Bearer nm_live_•••" } } } }

Claude Desktop only starts local servers from claude_desktop_config.json, so it goes through the mcp-remote bridge. Settings · MCP generates this block with your key in it. Where your Claude plan offers request headers on custom connectors, you can add the URL there instead.

{ "mcpServers": { "numail": { "command": "npx", "args": ["-y", "mcp-remote", "https://www.numail.ai/api/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer nm_live_•••" } } } }

Reload & talk

Reload the client and the NuMail tools register automatically. Then just ask in plain language.

# in any connected client ▸ "What's the reply rate on my live campaigns?" → 8.3% · 104 replies over 1,247 sends ↑ best: Mercer · Q3 outbound

Claude Code, even fasterclaude mcp add --transport http numail https://www.numail.ai/api/mcp --header "Authorization: Bearer nm_live_•••"

▸ Tool catalog

Fourteen tools, callable by name.

One tool per capability, each mapped to a NuMail REST endpoint. Names are stable and self-describing, so the agent picks the right one without prompting.

Campaigns create · launch · pause · resume

list_campaigns

Browse campaigns by status or search, sorted and paged, with sent and reply totals.

maps to GET /api/v1/campaigns

create_campaign

Create a draft in one call: name, mailboxes, leads and steps with A/B variants. Can launch on create.

maps to POST /api/v1/campaigns

add_sequence_step

Append a step (subject, body, delay in days and hours) to an existing campaign.

maps to POST /api/campaigns/:id/steps

launch_campaign

Move a draft campaign to active. Sending begins.

maps to POST /api/v1/campaigns/:id/start

pause_campaign

Pause an active campaign. All sending stops until you resume it.

maps to POST /api/v1/campaigns/:id/pause

resume_campaign

Resume a paused campaign. Leads pick up from the step they were on.

maps to POST /api/v1/campaigns/:id/resume

Leads add · inspect · suppress

list_leads

Filter leads by status or search, sorted and paged.

maps to GET /api/v1/leads

get_lead

One lead in full: campaign enrollments, stats and activity timeline.

maps to GET /api/v1/leads/:id

add_lead

Add a single lead: email, name, company and title.

maps to POST /api/v1/leads

suppress_lead

Stop every active campaign for a lead and add them to the suppression list.

maps to PATCH /api/v1/leads/:id

Mailboxes & unibox health · read · reply

list_mailboxes

Every mailbox with its health and reputation, filtered by status or provider.

maps to GET /api/v1/mailboxes

list_replies

Reply threads filtered by status, classification or mailbox. Warmup traffic stays out.

maps to GET /api/v1/threads

get_thread

A full thread: every message, the lead, and the AI draft if one is waiting.

maps to GET /api/v1/threads/:id

send_reply

Send a reply in a thread: HTML body and recipient.

maps to POST /api/v1/threads/:id/reply

Every tool maps to a documented REST endpoint → see the API reference

▸ What you can hand off

Outbound, run by conversation.

Four workflows that turn into a single sentence once the MCP server is connected.

⌥

Stand up a new client in one prompt

Read the CSV, write the sequence, pick the sending mailbox, and launch. The agent chains list_mailboxes → create_campaign → launch_campaign.

“Take mercer-leads.csv, build our standard two-step sequence for Mercer, send it from tomas@mercer.com, and launch it.”

⌃

Triage the unibox over coffee

Read every positive reply since yesterday, grouped by campaign, and have a short draft waiting on each one. Approve the good ones in a single follow-up.

“Show me every positive reply from the last 24h grouped by campaign, and draft a short response for each.”

↻

Pause everything before a holiday

Friday at 4pm: pause every active campaign in the workspace, then bring them all back on Tuesday, each lead picking up where it stopped: list_campaigns → pause_campaign, then resume_campaign.

“Pause every active campaign. On Tuesday: resume everything you paused on Friday.”

⊘

Honor every “take me off” in one line

Find the replies asking to stop, read each one, and suppress the lead across every campaign: list_replies → get_thread → suppress_lead.

“Anyone who replied asking us to stop this week: suppress them everywhere.”

▸

Where the MCP server is today

The MCP server is live for every workspace at https://www.numail.ai/api/mcp, hosted by us, so there is no NuMail package to install and nothing to update. It is a thin layer over the REST API: each of the 14 tools above calls the same service code as the endpoint it maps to.

Every capability here also works over the REST API and SDKs today, so scripts and agents can share one workspace. New tools appear on the server with no change on your side. Start a trial and generate an MCP key in Settings · MCP.

Give your agenta cold-email stack.