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; signup, billing, screening, and real mailbox provisioning on your own account are fully self-serve and automatic — the only remaining step is mailbox send-authorization completing on our side after provisioning, and you don't wait on a queue or do anything.

On this page

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

Quickstart

curl -s -X POST https://api.coldrig.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://api.coldrig.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.1) 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.

Going live

Going live is self-serve, not a sales conversation:

curl -s -X POST https://api.coldrig.dev/checkout \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"mailboxes":5}'
# → { "mode": "stripe", "url": "https://checkout.stripe.com/...", "sessionId": "cs_..." }

POST /checkout returns a hosted Stripe payment link — open the url and pay. This endpoint is HTTP-only; it is not one of the 28 MCP tools, so an agent operating purely over MCP should hand this step to the owner (or call it directly if the agent has HTTP access). Promotion codes are entered on Stripe's own checkout page, via its "Add promotion code" link — the API deliberately has no coupon-code field of its own. The mailboxes field seeds the initial quote only — the subscription charge actually follows your provisioned mailbox count (5-mailbox floor, $10/month each beyond), which then tracks up or down as mailboxes provision or are released. After payment, real mailbox provisioning is automatic; the only remaining step is mailbox send-authorization completing on our side.

Tool reference

All 28 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`	—
`remove_mailboxes`	`POST /remove-mailboxes`	`{ count, acknowledged: true }`
`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, complaint, and unsubscribe 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 are self-serve and automatic through provisioning; mailbox send-authorization still completes on our side — 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.