Docs

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

Live in production The hosted MCP endpoint, HTTP API, npm CLI, fault-injecting sandbox, and real sending (Gmail API, HTTPS/443) are all live. A public signup by default creates an isolated demo tenant that cannot reach vendor adapters; activating real sending on your own account runs through a short concierge step while self-serve activation rolls out.

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":"[email protected]"}'
# → { "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 and per-token scoped — one config line, no OAuth dance. It is live in production; demo tenants run against sandbox vendors, and activated tenants reach real ones — see the status banner above.

CLI usage

npx agent-cold-email demo                 # run the full pipeline against the live sandbox, no signup
npx agent-cold-email signup --brand Acme --email [email protected]
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 published on npm (v0.2.0 registry-verified 2026-07-15) and is a thin twin over the same HTTP facade documented below. Every subcommand maps to a tool in the tool reference; the package remains the permanent machine handle for Coldrig.

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 24 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`	—
`list_campaigns`	`GET /campaigns`	—
`pause`	`POST /campaigns/{id}/pause`	—
`pause_all`	`POST /campaigns/pause-all`	—
`metrics`	`GET /metrics`	—
`activity`	`GET /activity`	`?limit&cursor&kind=event\|deliverability` (all optional)
`inbox`	`GET /inbox`	—
`thread`	`GET /threads/{id}`	—
`reply`	`POST /threads/{id}/reply`	`{ body }`
`mark`	`POST /threads/{id}/mark`	`{ status: "read"\|"unread"\|"archived" }`
`label_thread`	`POST /threads/{id}/label`	`{ label: string\|null }`
`account`	`GET /account`	—
`get_dashboard`	`GET /dashboard/views`, `GET /dashboard/views/{id}`	—
`configure_dashboard`	`POST/PUT/DELETE /dashboard/views[/{id}]`, `POST /dashboard/views/{id}/default`	`{ name, layout, note }` (per action)
`get_webhooks`	`GET /webhook-subscriptions`, `GET /webhook-subscriptions/{id}`	—
`configure_webhook`	`POST /webhook-subscriptions`, `PUT/DELETE /webhook-subscriptions/{id}`	`{ action, url, eventTypes, secret, active }` (per action)
`get_byo_domains`	`GET /byo-domains`, `GET /byo-domains/{id}`	—
`configure_byo_domain`	`POST /byo-domains`, `POST /byo-domains/{id}/poll-dns`, `POST /byo-domains/{id}/consent`, `POST /byo-domains/{id}/managed-mailboxes`, `POST /byo-domains/{id}/connect-mailbox`	`{ action, domain, domainRelationship, id, acknowledged, count, personaSlug, email, transport }` (per action)
`suppress_lead`	`POST /leads/suppress`	`{ email, reason, note }`
`update_lead`	`POST /leads/disposition`	`{ email, interestStatus, notes, tags }`
`list_leads`	`GET /leads`	`?campaign&interestStatus&suppressed&replied&cursor&limit` (all optional)

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

Webhook boundary: real push webhooks are live. get_webhooks/configure_webhook deliver reply, bounce, soft_bounce, and complaint events (HMAC-SHA256 signed, header X-Coldrig-Signature) to your own HTTPS endpoint; URLs must be a public HTTPS host. activity remains available as a pollable alternative for the same event classes.

BYO domain boundary: domain registration, the pre-flight scan, and consent tracking via get_byo_domains/configure_byo_domain are live, reachable tools today. Real DNS delegation, live reputation checks, and platform-provisioned mailboxes on your own domain activate through the same concierge step as real sending generally — see the BYO domain page.

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.