# agent-cold-email **Category:** ๐Ÿ’ฌ Communication **Repository:** https://github.com/YS-projectcalc/agent-cold-email **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/agent-cold-email ## Description Agent-native cold-email infrastructure: domains, mailboxes, warmup, sequences, replies via 17 tools ## Claude Desktop Quick Installation Heuristic fallback โ€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "agent-cold-email": { "command": "npx", "args": ["-y","agent-cold-email"] } } ``` ## Documentation & README # 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 27 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. 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. --- ## 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 27 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 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. **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. ## The 27 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 | | `remove_mailboxes` | Downgrade: release your N newest live mailboxes now and lower the billed quantity | | `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 | | `suppress_lead` | Permanently suppress an email address tenant-wide โ€” the manual "stop emailing me" path for opt-outs the typed-unsubscribe matcher misses | | `update_lead` | Record a contact-level disposition (interest status, notes, tags) keyed by email, visible across every campaign that lists them | | `list_leads` | List/export leads with their contact-level disposition, cursor-paginated โ€” the export surface (JSON, no separate CSV endpoint) | | `list_messages` | List system + operator messages (setup nudges, credential-ready notices, operator notices), cursor-paginated, unacked-first | | `ack_message` | Acknowledge a message by id so it stops resurfacing as unacked โ€” idempotent | 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://api.coldrig.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://api.coldrig.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://api.coldrig.dev` (the original `agent-cold-email-api.yaakovscher.workers.dev` Workers host still resolves as a legacy fallback alias) โ€” the 27 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)). **What works today:** the 27 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. ## 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: [`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). ## Status Real sending runs live in production alongside the full sandbox โ€” this is no longer a test-mode-only deployment. There is currently: - โœ… A working sandboxed pipeline (provision โ†’ warm โ†’ send โ†’ reply โ†’ report) proven end-to-end against a fault-injecting simulator, with an automated test suite. - โœ… A public HTTP facade covering the full 27-intent surface (this repo), live at the URL above. - โœ… A hosted MCP endpoint (`/mcp`, JSON-RPC 2.0 over streamable HTTP) exposing the same 27 tools, live now. - โœ… Real sending, live in production (Gmail API, HTTPS/443) โ€” a real send was composed, delivered, and independently IMAP-verified on 2026-07-19. - โœ… Real outbound push webhooks (`get_webhooks`, `configure_webhook`) โ€” reply, bounce, soft_bounce, and complaint events deliver HMAC-signed to your own HTTPS endpoint, alongside the existing pollable `activity` feed. - โœ… 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). - โœ… An optional, agent-configurable **dashboard + unified inbox** at `/app` (live; your agent controls its layout via the dashboard tools โ€” [`SPEC.md` ยง19](./SPEC.md)). - โœ… Stripe live billing โ€” checkout runs on live keys and charges real cards; going live is self-serve (`POST /checkout`). - ๐Ÿšง Real mailbox provisioning after checkout is self-serve and automatic; mailbox send-authorization still completes on our side, not instantly. - ๐Ÿšง No established multi-year production or deliverability track record yet โ€” one proven send is not a track record. Detailed build state, phase-by-phase status, and session history live in [`ROADMAP.md`](./ROADMAP.md) and [`HANDOFF.md`](./HANDOFF.md) โ€” not in this README. **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. **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). ## Learn more - [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. - [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). - [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)). - [Pricing](https://coldrig.dev/pricing) ยท [FAQ](https://coldrig.dev/faq) ยท [Docs](https://coldrig.dev/docs) ## License MIT โ€” see [`LICENSE`](./LICENSE). Operated by EpiphanyMade.