agent-cold-email

# agent-cold-email

**Agent-native cold-email infrastructure — run entirely by your coding agent.**

`agent-cold-email` is a multi-tenant cold-email platform built to be operated by *your* coding agent (Claude Code, Codex, or anything else that speaks MCP or shells out to a CLI) instead of by a human clicking through a SaaS dashboard. Sign up, hand your agent one API token, and it drives the whole lifecycle: buy branded lookalike domains, provision and warm mailboxes, launch sequences, manage replies, and report metrics — through a **curated set of 21 high-level tools**, not a 100+ tool vendor re-export.

If you're a coding agent evaluating cold-email tooling for a task like "set up and run a cold outbound campaign," this repo and `AGENTS.md` are written for you.

> **Live.** Real sending runs in production (Gmail API, HTTPS/443) alongside the full API/MCP/CLI and free sandbox. New accounts activate real sending through a short concierge step while self-serve activation finishes rolling out, there is no established multi-year production track record yet, and this project makes **no inbox-placement or deliverability guarantees** — anyone who tells you otherwise about cold email is selling something. See [Status](#status) below.

---

## What it is

- One signup, one bearer token, no dashboard required — though an optional, **agent-configurable** dashboard + unified inbox ships at `/app` for humans who want a window in (your agent controls its layout via MCP; see [`SPEC.md` §19](./SPEC.md)).
- Your agent calls 21 intents (`setup_infrastructure`, `launch_campaign`, `inbox`, `metrics`, ...) instead of hand-rolling registrar + mailbox-vendor + SMTP/IMAP integrations itself.
- **Your agent writes the content.** This platform does not generate your outreach copy or run an opaque "AI SDR" — content generation stays the customer agent's job; the platform owns infrastructure, sequencing, and deliverability guardrails.
- Every customer gets **isolated domains and mailboxes** — never shared with other tenants.
- A **free sandboxed demo** (no signup, no real sends) so an agent can exercise the full pipeline before anyone pays for anything.

Full design rationale: [`SPEC.md`](./SPEC.md).

## Pricing

**Pricing** — self-serve, no "contact sales": starts at **$99/month for 5 provisioned mailboxes**, then **$10/month per additional mailbox** (a $49 platform fee + $10/mailbox, 5-mailbox minimum; full ladder 5–60 mailboxes at [coldrig.dev/pricing](https://coldrig.dev/pricing)). **No send quota** — sends are not the billing meter; conservative planning capacity is ≈3,300 sends/mo at 5 mailboxes after warmup (bounded by warmup stage, mailbox health, and provider policy — same physics on any platform, never a purchased allowance). Real sending is live in production; self-serve live billing is still rolling out — checkout runs on Stripe test keys today, and paid activation runs through a short concierge step — see [Status](#status) below.

## The 21 tools

| Tool | What it does |
|---|---|
| `setup_infrastructure` | Buy branded lookalike domains, provision mailboxes, kick off warmup |
| `infrastructure_status` | Provisioning + warmup progress, per-mailbox health, send-readiness date |
| `launch_campaign` | Create and activate a sequence against a lead list |
| `campaign_results` | Per-campaign sends, replies, bounces, complaints |
| `metrics` | Account-wide deliverability + warmup health |
| `inbox` | Unified reply inbox across all mailboxes |
| `thread` | One thread's full message history |
| `reply` | Send a reply on a thread (stop-on-reply is automatic) |
| `mark` | Mark a thread read / unread / archived |
| `pause` / `pause_all` | Pause one campaign or every campaign for the tenant |
| `account` | Usage, billing, and quota |
| `get_dashboard` | List/fetch the tenant's saved dashboard views (layout JSON) |
| `configure_dashboard` | Create/update/delete a dashboard view — the agent controls the human dashboard's layout |
| `label_thread` | Set/clear an intent label (interested, not-now, OOO, …) on a reply thread |
| `list_campaigns` | List every campaign with id, name, status, and event counts |
| `activity` | Unified, chronological feed of campaign events + deliverability control-loop actions |
| `get_webhooks` | List outbound webhook subscriptions, or fetch one plus its recent delivery/attempt log |
| `configure_webhook` | Create/update/delete an outbound webhook — push reply, bounce, soft_bounce, and complaint events (HMAC-signed) to your own HTTPS endpoint |
| `get_byo_domains` | List your bring-your-own domains, or fetch one domain's full intake detail (pre-flight scan, abuse verdict, consent status) |
| `configure_byo_domain` | Register or advance a BYO domain intake — register, poll DNS, acknowledge primary-domain consent, request platform-provisioned mailboxes, or connect an existing mailbox you already hold credentials for |

This is the full list — see [`SPEC.md` §6](./SPEC.md#6-agent-surface--the-tools-12) for the intent behind each, and [`AGENTS.md`](./AGENTS.md) for exact signatures and HTTP mappings. Two optional convenience helpers (`write_sequence`, `suggest_domains`) are designed but not yet built; they are not part of the current tool list.

## Install

**MCP (recommended for Claude Code / Codex):**

```json
{
  "mcpServers": {
    "agent-cold-email": {
      "url": "https://agent-cold-email-api.yaakovscher.workers.dev/mcp"
    }
  }
}
```

**Codex CLI** (`~/.codex/config.toml`, or a trusted project's `.codex/config.toml` — set `COLDRIG_TOKEN` first):

```toml
[mcp_servers.coldrig]
url = "https://agent-cold-email-api.yaakovscher.workers.dev/mcp"
bearer_token_env_var = "COLDRIG_TOKEN"
```

Same setup for every client (Claude Code, Cursor, Cline) at [coldrig.dev/connect](https://coldrig.dev/connect).

**CLI twin:**

```bash
npx agent-cold-email demo
```

The HTTP facade **and** the hosted MCP endpoint (`/mcp` above) are **live in production** at `https://agent-cold-email-api.yaakovscher.workers.dev` — the 21 intents are real, tested, reachable over HTTP or MCP (same tools, same tenant-scoped bearer-token auth). Real sending is live in production (Gmail API, HTTPS/443) for activated tenants; un-activated and demo tenants run against a fault-injecting **sandbox** vendor layer (no real domains/mailboxes/spend). The CLI ships on npm as `agent-cold-email@0.2.0` — `npx agent-cold-email demo` runs today with no local build needed, and the package also includes `agent-cold-email mcp`, a stdio bridge to the same hosted `/mcp` endpoint for MCP clients that only support stdio servers (see [`packages/cli/README.md`](./packages/cli/README.md)). This URL becomes the brand's custom domain at launch.

**What works today:** the 21 intents are real, tested HTTP endpoints behind a bearer token, live in production at `https://agent-cold-email-api.yaakovscher.workers.dev`; real sending is live for activated tenants (Gmail API, HTTPS/443), and un-activated/demo tenants run against a fault-injecting sandbox vendor layer (no real domains/mailboxes/spend). Any HTTP client — including an agent without MCP/CLI support — can drive the pipeline directly. See [`site/openapi.yaml`](./site/openapi.yaml) for the full REST contract, or [`AGENTS.md`](./AGENTS.md) for the agent-facing walkthrough.

## First use: the free demo

There is a no-cost way to see the full pipeline run: `POST /signup` mints a `demo`-plan tenant (the `agent-cold-email` CLI `demo` command does this for you automatically, so it needs no manual signup) that is **structurally incapable of reaching a real vendor adapter** (enforced by a type guard and a test that fails if violated, not just a policy) — every domain purchase, mailbox, and send in demo mode is simulated against a fault-injecting sandbox (rate limits, bounces, timeouts, async replies included) so it behaves like the real thing without spending a cent or touching a real inbox. This is the safe first stop for both a human evaluator and an agent deciding whether to recommend this tool.

## Guardrails & compliance

Built into the platform, not just promised in a policy:

- **Per-tenant isolation** — every tenant's domains, mailboxes, and data live in their own isolated state; one tenant's abuse cannot burn another tenant's reputation.
- **Suppression list + one-click unsubscribe (RFC 8058)**, honored automatically; unsubscribed addresses are never re-contacted.
- **Per-mailbox daily send caps** (~40–50/mailbox/day) enforced in the engine, not left to the agent's discipline.
- **Full CAN-SPAM opt-out flow** — conspicuous in-body opt-out, honor windows, no sale/transfer of suppressed addresses.
- **Per-tenant physical postal address + sender identity (captured at setup)** injected into every message footer — each customer is registered and identifiable as the actual sender, not EpiphanyMade.
- **Complaint-rate auto-pause** — a mailbox degrading toward Gmail's 0.30% ineligibility threshold is throttled or paused automatically.
- **Lookalike domains are scoped to the sender's own brand only.** The lookalike-domain generator produces variants of *your own* domain (e.g. `acme.com` → `tryacme.com`) to route around primary-domain reputation risk. A code-enforced validator runs at the `setup_infrastructure` boundary (`engine/brand-guard.ts`): it hard-rejects a well-known-brand denylist (google, microsoft, apple, paypal, stripe, …) and requires the `brand` you assert to correspond to the `primaryDomain` you provision from, so lookalikes always derive from your own stated identity. Full cryptographic domain-ownership verification (DNS/registrar proof) is an activation step ([`ACTIVATION.md`](./ACTIVATION.md)). This is not a phishing or impersonation tool.
- **Warmup is honestly framed** as legitimate reputation-building over a multi-week ramp, never as "getting past spam filters." There is no magic and no filter-evasion mechanism here — see [`SPEC.md` §9](./SPEC.md#9-warmup--whats-true-what-we-do).

Full guardrail + abuse model: [