{
  "markdown": "# agent-cold-email\n\n**Agent-native cold-email infrastructure — run entirely by your coding agent.**\n\n`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 28 high-level tools**, not a 100+ tool vendor re-export.\n\nIf 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.\n\n[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/ys-projectcalc/agent-cold-email)\n**Listings:** [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=agent-cold-email) · [npm](https://www.npmjs.com/package/agent-cold-email) · [Smithery](https://smithery.ai/servers/yaakovscher/agent-cold-email) · [Glama](https://glama.ai/mcp/servers/YS-projectcalc/agent-cold-email)\n\n> **Live.** Real sending runs in production (Gmail API, HTTPS/443) alongside the full API/MCP/CLI and free sandbox. Signup, billing, screening, and real mailbox provisioning are fully self-serve and automatic; the only remaining step is mailbox send-authorization completing on our side after provisioning — you never wait in a queue or do anything further. 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.\n\n---\n\n## What it is\n\n- 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)).\n- Your agent calls 28 intents (`setup_infrastructure`, `launch_campaign`, `inbox`, `metrics`, ...) instead of hand-rolling registrar + mailbox-vendor + SMTP/IMAP integrations itself.\n- **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.\n- Every customer gets **isolated domains and mailboxes** — never shared with other tenants.\n- A **free sandboxed demo** (no signup, no real sends) so an agent can exercise the full pipeline before anyone pays for anything.\n\nFull design rationale: [`SPEC.md`](./SPEC.md).\n\n## Pricing\n\n**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 and live billing are both live in production (Stripe live mode, real cards). Going live is self-serve: call `POST /checkout` with `{ mailboxes }` and it returns a hosted Stripe payment link — open it and pay; the `mailboxes` field only seeds the initial quote, since the actual subscription charge follows your provisioned mailbox count (5-mailbox floor, $10/month each beyond). Promotion codes are entered on Stripe's own checkout page (\"Add promotion code\" link), not in the API. Real mailbox provisioning is then fully self-serve and automatic; the only remaining step is mailbox send-authorization completing on our side — see [Status](#status) below.\n\n**All-in cost accounting:** a true comparison sums mailbox seats, domains (registration *and* burn-replacement), warmup, the sending platform, suppression/unsubscribe/compliance infrastructure, and any per-send fee. The $99/month above is all six of those, bundled, with **$0 per-send fees**. At the 5–15 mailbox starter/solo shape, a fair self-assembled 5-mailbox stack (5 Google Workspace seats at $7/seat + a $39/month sequencer + amortized domains at ≈$2.50/mailbox at the low end) runs ≈$76.50–140/month before your own assembly/maintenance time; a competing agent-operated stack shopped directly (Salesforge) landed at $112/month all-in versus this platform's $99. This holds at the starter/solo shape only — at agency scale (dozens of mailboxes across multiple clients) this platform's current per-tenant pricing does not win, and no claim is made at that scale.\n\n## The 28 tools\n\n| Tool | What it does |\n|---|---|\n| `setup_infrastructure` | Buy branded lookalike domains, provision mailboxes, kick off warmup |\n| `infrastructure_status` | Provisioning + warmup progress, per-mailbox health, send-readiness (a boolean per mailbox and account-wide, not an ETA) |\n| `launch_campaign` | Create and activate a sequence against a lead list |\n| `campaign_results` | Per-campaign sends, replies, bounces, complaints |\n| `metrics` | Account-wide outcome totals (sent, reply, bounce, complaint, unsubscribe, failed, soft_bounce) — use `infrastructure_status` for warmup/deliverability health |\n| `inbox` | Unified reply inbox across all mailboxes |\n| `thread` | One thread's full message history |\n| `reply` | Send a reply on a thread (stop-on-reply is automatic) |\n| `mark` | Mark a thread read / unread / archived |\n| `pause` / `pause_all` | Pause one campaign or every campaign for the tenant |\n| `account` | Usage, billing, and quota |\n| `remove_mailboxes` | Downgrade: release your N newest live mailboxes now and lower the billed quantity |\n| `get_dashboard` | List/fetch the tenant's saved dashboard views (layout JSON) |\n| `configure_dashboard` | Create/update/delete a dashboard view — the agent controls the human dashboard's layout |\n| `label_thread` | Set/clear an intent label (interested, not-now, OOO, …) on a reply thread |\n| `list_campaigns` | List every campaign with id, name, status, and event counts |\n| `activity` | Unified, chronological feed of campaign events + deliverability control-loop actions |\n| `get_webhooks` | List outbound webhook subscriptions, or fetch one plus its recent delivery/attempt log |\n| `configure_webhook` | Create/update/delete an outbound webhook — push reply, bounce, soft_bounce, complaint, and unsubscribe events (HMAC-signed) to your own HTTPS endpoint |\n| `get_byo_domains` | List your bring-your-own domains, or fetch one domain's full intake detail (pre-flight scan, abuse verdict, consent status) |\n| `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 |\n| `suppress_lead` | Permanently suppress an email address tenant-wide — the manual \"stop emailing me\" path for opt-outs the typed-unsubscribe matcher misses |\n| `update_lead` | Record a contact-level disposition (interest status, notes, tags) keyed by email, visible across every campaign that lists them |\n| `list_leads` | List/export leads with their contact-level disposition, cursor-paginated — the export surface (JSON, no separate CSV endpoint) |\n| `list_messages` | List system + operator messages (setup nudges, credential-ready notices, operator notices), cursor-paginated, unacked-first |\n| `ack_message` | Acknowledge a message by id so it stops resurfacing as unacked — idempotent |\n| `contact_operator` | Reach a human operator (a support ticket + ops alert) — works in every account state, including suspended. The reply arrives via `list_messages` |\n\nThis 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.\n\n## Install\n\n**MCP (recommended for Claude Code / Codex):**\n\n```json\n{\n  \"mcpServers\": {\n    \"coldrig\": {\n      \"url\": \"https://api.coldrig.dev/mcp\"\n    }\n  }\n}\n```\n\n**Codex CLI** (`~/.codex/config.toml`, or a trusted project's `.codex/config.toml` — set `COLDRIG_TOKEN` first):\n\n```toml\n[mcp_servers.coldrig]\nurl = \"https://api.coldrig.dev/mcp\"\nbearer_token_env_var = \"COLDRIG_TOKEN\"\n```\n\nSame setup for every client (Claude Code, Cursor, Cline) at [coldrig.dev/connect](https://coldrig.dev/connect).\n\n**Claude Code plugin / agent skill:**\n\n```bash\n/plugin marketplace add YS-projectcalc/agent-cold-email\n/plugin install coldrig@coldrig\n```\n\nThe plugin connects to the same `coldrig` MCP server and prompts for your bearer token when you enable it. Or install just the skill with [skills.sh](https://skills.sh): `npx skills add YS-projectcalc/agent-cold-email`. Cursor and Codex users: see [`integrations/`](./integrations/) for a Cursor rule and an `AGENTS.md` paste-in block.\n\n**CLI twin:**\n\n```bash\nnpx agent-cold-email demo\n```\n\nThe HTTP facade **and** the hosted MCP endpoint (`/mcp` above) are **live in production** at `https://api.coldrig.dev` (the original `agent-cold-email-api.yaakovscher.workers.dev` Workers host still resolves as a legacy fallback alias) — the 28 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.1` — `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)).\n\n**What works today:** the 28 intents are real, tested HTTP endpoints behind a bearer token, live in production at `https://api.coldrig.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.\n\n## First use: the free demo\n\nThere 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.\n\n## Guardrails & compliance\n\nBuilt into the platform, not just promised in a policy:\n\n- **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.\n- **Suppression list + one-click unsubscribe (RFC 8058)**, honored automatically; unsubscribed addresses are never re-contacted.\n- **Per-mailbox daily send caps** (~40–50/mailbox/day) enforced in the engine, not left to the agent's discipline.\n- **Full CAN-SPAM opt-out flow** — conspicuous in-body opt-out, honor windows, no sale/transfer of suppressed addresses.\n- **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.\n- **Complaint-rate auto-pause** — a mailbox degrading toward Gmail's 0.30% ineligibility threshold is throttled or paused automatically.\n- **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.\n- **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).\n\nFull guardrail + abuse model: [`SPEC.md` §7](./SPEC.md#7-isolation-model-how-one-bad-customer--company-death). Legal documents (drafts, pending attorney review): [`site/terms.html`](./site/terms.html), [`site/privacy.html`](./site/privacy.html), [`site/aup.html`](./site/aup.html).\n\n## Status\n\nReal sending runs live in production alongside the full sandbox — this is no longer a test-mode-only deployment. There is currently:\n\n- ✅ A working sandboxed pipeline (provision → warm → send → reply → report) proven end-to-end against a fault-injecting simulator, with an automated test suite.\n- ✅ A public HTTP facade covering the full 28-intent surface (this repo), live at the URL above.\n- ✅ A hosted MCP endpoint (`/mcp`, JSON-RPC 2.0 over streamable HTTP) exposing the same 28 tools, live now.\n- ✅ Real sending, live in production (Gmail API, HTTPS/443) — a real send was composed, delivered, and independently IMAP-verified on 2026-07-19.\n- ✅ Real outbound push webhooks (`get_webhooks`, `configure_webhook`) — reply, bounce, soft_bounce, complaint, and unsubscribe events deliver HMAC-signed to your own HTTPS endpoint, alongside the existing pollable `activity` feed.\n- ✅ An accelerated sandbox demo — the `agent-cold-email` CLI `demo` command (published on npm: `npx agent-cold-email demo`) mints a demo tenant automatically and drives the full pipeline; the underlying `POST /demo/run` runs against that demo tenant's bearer token (get one from `POST /signup` — no card, no vendor account).\n- ✅ An optional, agent-configurable **dashboard + unified inbox** at `/app` (live; your agent controls its layout via the dashboard tools — [`SPEC.md` §19](./SPEC.md)).\n- ✅ Stripe live billing — checkout runs on live keys and charges real cards; going live is self-serve (`POST /checkout`).\n- 🚧 Real mailbox provisioning after checkout is self-serve and automatic; mailbox send-authorization still completes on our side, not instantly.\n- 🚧 No established multi-year production or deliverability track record yet — one proven send is not a track record.\n\nDetailed build state, phase-by-phase status, and session history live in [`ROADMAP.md`](./ROADMAP.md) and [`HANDOFF.md`](./HANDOFF.md) — not in this README.\n\n**Where this stands today:** the site is LIVE at [coldrig.dev](https://coldrig.dev) with the API + dashboard on Cloudflare Workers; the CLI is published on npm (`agent-cold-email@0.2.1`, including the `agent-cold-email mcp` stdio-bridge mode) and the MCP server is listed in the official MCP Registry (`io.github.YS-projectcalc/agent-cold-email`), which advertises both the hosted remote endpoint and the npm package as install options. The real send/receive engine, the per-tenant activation allowlist, and the CAN-SPAM one-click opt-out flow are all committed and proven live — a real send over the Gmail API/443 transport was composed, delivered, and independently IMAP-verified. Stripe live billing runs on live keys and charges real cards; signup, billing, screening, and real mailbox provisioning are fully self-serve and automatic. The only remaining step is mailbox send-authorization completing on our side after provisioning — you never wait in a queue or do anything further.\n\n**Try it now — free sandbox, no card, no waitlist:** `POST /signup` (get a token instantly) or `npx agent-cold-email demo` (mints its own tenant, needs nothing). Real sending is live — see [coldrig.dev/pricing](https://coldrig.dev/pricing) for the exact meter, then call `POST /checkout` with `{ mailboxes }` for a hosted Stripe payment link when you're ready to go live (that field only seeds the quote — the actual charge tracks your provisioned mailbox count).\n\n## Learn more\n\n- [Compare](https://coldrig.dev/compare) — Coldrig vs a DIY stack, vs Smartlead, vs Salesforge, vs AgentMail, vs Skyp, vs FoxReach, vs Maildoso: sourced, numbers-first comparisons.\n- [Run your cold email operation with Claude Code](https://coldrig.dev/guide-cold-email-operation-claude-code) — the flagship agent-operation guide (Cursor and Codex variants are linked from it).\n- [Should your AI agent use Coldrig?](https://coldrig.dev/for-agents) — evidence, fit, and limits, written for an evaluating agent (machine-readable twin: [`agent-evaluation.md`](https://coldrig.dev/agent-evaluation.md)).\n- [Pricing](https://coldrig.dev/pricing) · [FAQ](https://coldrig.dev/faq) · [Docs](https://coldrig.dev/docs)\n\n## License\n\nMIT — see [`LICENSE`](./LICENSE). Operated by EpiphanyMade.\n",
  "bytes": 17879,
  "sha": "69462a3db5bb20f40ca14975ba3cfb9ff5ee667f7cfad2cc8daa56156d495c89",
  "repo_slug": "ys-projectcalc/agent-cold-email",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ys_projectcalc_agent_cold_emai_62007d4f/readme"
}