Docs

Quickstart, MCP setup, CLI usage, and the full tool reference — written for both a human setting this up and an agent operating it.

Early access The hosted MCP endpoint (/mcp) is live now at https://agent-cold-email-api.yaakovscher.workers.dev — in test mode: sandbox vendor adapters only, no real sends. The npm-published CLI and real sending are the remaining activation steps.

On this page

Quickstart
MCP setup
CLI usage
The free demo
Tool reference
Auth model

Quickstart

curl -s -X POST https://agent-cold-email-api.yaakovscher.workers.dev/signup \
  -H 'Content-Type: application/json' \
  -d '{"brand":"Acme","contactEmail":"you@acme.com"}'
# → { "tenantId": "ten_...", "token": "..." }

Hand the token to your agent — via MCP config, CLI env var, or directly as a bearer token if your agent talks HTTP.
Have your agent call setup_infrastructure, then poll infrastructure_status, then launch_campaign.

MCP setup

For Claude Code, Codex, or any MCP-capable agent, add a remote MCP server pointing at the hosted endpoint:

{
  "mcpServers": {
    "agent-cold-email": {
      "url": "https://agent-cold-email-api.yaakovscher.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

The hosted MCP server is streamable-HTTP, per-token scoped — one config line, no OAuth dance. It is live now in test mode (sandbox vendors, no real sends); see the status banner above.

CLI usage

# once published:
npx agent-cold-email demo                 # run the full pipeline against the live sandbox, no signup
npx agent-cold-email signup --brand Acme --email you@acme.com
npx agent-cold-email setup --brand Acme --primary-domain acme.com --domains 2 --inboxes-each 3
npx agent-cold-email status
npx agent-cold-email campaign launch --file campaign.json

The CLI is a thin twin over the same HTTP facade documented below — every subcommand maps 1:1 to a tool in the tool reference. The npm package name agent-cold-email is reserved (the permanent keyword handle — see the home page FAQ on naming); publishing is one of the last steps before general availability.

The free demo

POST /signup mints a demo-plan tenant that is structurally incapable of reaching a real vendor adapter — enforced at the type level and covered by a test that fails if the guard is ever bypassed, not just documented policy. Every domain purchase, mailbox provisioning step, warmup tick, and send in demo mode runs against a fault-injecting sandbox: simulated rate limits, timeouts, bounces, and asynchronous replies, on a virtual clock so a multi-week warmup ramp resolves in the same session instead of in real time. This is the safe way to see the whole pipeline — provision, warm, send, reply, report — before anyone pays for anything.

Tool reference

All 12 authed intents, plus the one unauthenticated bootstrap call. Full JSON Schemas: openapi.yaml.

Tool	HTTP	Body / params
`signup`	`POST /signup` (no auth)	`{ brand, contactEmail }`
`setup_infrastructure`	`POST /setup-infrastructure`	`{ brand, primaryDomain, domains, inboxesEach, persona, physicalAddress, senderIdentity }`
`infrastructure_status`	`GET /infrastructure-status`	—
`launch_campaign`	`POST /campaigns`	`{ name, offer, leads[], sequence[], timezone, sendWindow, stopOnReply }`
`campaign_results`	`GET /campaigns/{id}/results`	—
`pause`	`POST /campaigns/{id}/pause`	—
`pause_all`	`POST /campaigns/pause-all`	—
`metrics`	`GET /metrics`	—
`inbox`	`GET /inbox`	—
`thread`	`GET /threads/{id}`	—
`reply`	`POST /threads/{id}/reply`	`{ body }`
`mark`	`POST /threads/{id}/mark`	`{ status: "read"\|"unread"\|"archived" }`
`account`	`GET /account`	—

Two optional helpers (write_sequence, suggest_domains) are designed but not yet built — do not assume they exist today.

Auth model

One bearer token per tenant, minted at signup. Every authed call:

Authorization: Bearer <token>

The token resolves server-side to exactly one tenant's isolated state — there is no cross-tenant data access at any layer, and every engine query is additionally scoped by tenant ID as a second, independent check.