Agent-native cold-email infrastructure: domains, mailboxes, warmup, sequences, replies via 17 tools

🛠️ Key Features

Multi-tenant cold-email platform operable by your coding agent
Operates entirely via MCP-based workflows and CLI interactions
Provisions lookalike domains, warms mailboxes, and manages sequences
Tracks replies and reports metrics using a curated set of 17 tools
No traditional SaaS dashboard required; agent drives lifecycle

🚀 Use Cases

Automated cold-email campaigns controlled by code agents
Domain and mailbox provisioning for scalable outreach
Warmup management and sequence execution via MCP tools
Reply handling and metrics reporting within MCP workflows

⚡ Developer Benefits

MCP-centric server designed for agent governance (Claude Code, Codex, etc.)
Toolset of 17 high-level tools for orchestration, not an overwhelming suite
Self-contained, agent-operated infrastructure suitable for automation pipelines
Clear readme guidance for integration and lifecycle management

⚠️ Limitations

Grounded in MCP and CLI-based interactions; may not suit GUI-only workflows
Depends on external token-based authentication and domain services
Readme excerpt indicates a specialized, developer-driven use case; may require agent capabilities

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 17 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.

Early access. The backend is in active build and is not yet available for real sending. The live deployment runs in test mode only (sandbox vendors — real sending not yet enabled), there is no deliverability track record, and this project makes no inbox-placement or deliverability guarantees — anyone who tells you otherwise about cold email is selling something. See 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).
Your agent calls 17 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.

The 17 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

This is the full list — see SPEC.md §6 for the intent behind each, and 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"
    }
  }
}

CLI twin:

bash

npx agent-cold-email demo

The HTTP facade and the hosted MCP endpoint (/mcp above) are live in test mode at https://agent-cold-email-api.yaakovscher.workers.dev — the 17 intents are real, tested, reachable over HTTP or MCP (same tools, same tenant-scoped bearer-token auth), running against a fault-injecting sandbox vendor layer (no real domains/mailboxes/spend, not yet available for real sending). The CLI (packages/cli) is built and works today from a local build; npx agent-cold-email itself needs an npm publish, which is an owner-hands activation step (ACTIVATION.md) — the npm handle is reserved. This test-mode URL becomes the brand's custom domain at launch.

What works today: the 17 intents are real, tested HTTP endpoints behind a bearer token, live in test mode at https://agent-cold-email-api.yaakovscher.workers.dev 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 for the full REST contract, or 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 + verified sender identity 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). 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.

Full guardrail + abuse model: SPEC.md §7. Legal documents (drafts, pending attorney review): site/terms.html, site/privacy.html, site/aup.html.

Status & early access

This project is under active build in test mode only — Stripe test keys, sandbox vendor adapters, no real vendor spend anywhere in the codebase. 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 17-intent surface (this repo), live at the URL above.
✅ A hosted MCP endpoint (/mcp, JSON-RPC 2.0 over streamable HTTP) exposing the same 17 tools, live now.
✅ An accelerated sandbox demo — the agent-cold-email CLI demo command (built; not yet npm-published) 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 in test mode; your agent controls its layout via the dashboard tools — SPEC.md §19).
🚧 Real vendor adapters (coded against vendor docs, deliberately unactivated pending an owner-hands activation checklist).
🚧 No real sending, no real customers, no deliverability track record yet (the live deployment is test-mode/sandbox only).

Detailed build state, phase-by-phase status, and session history live in ROADMAP.md and HANDOFF.md — not in this README.

Want to be notified when real sending goes live? Join the waitlist on the marketing site once deployed (site/index.html → Cloudflare Pages).

License

MIT — see LICENSE. Operated by EpiphanyMade.

brand	string	required
primaryDomain	string	required
domains	integer	required
inboxesEach	integer	required
persona	string	required
physicalAddress	string	required
senderIdentity	string	required
idempotencyKey	string	optional	Optional idempotency key: resend the SAME key when retrying this call so a dropped-response retry is not applied twice (no duplicate campaign/provision/send).

name	string	required
offer	string	required
leads	array	required
sequence	array	required
timezone	string	optional
sendWindow	object	optional
stopOnReply	boolean	optional
idempotencyKey	string	optional	Optional idempotency key: resend the SAME key when retrying this call so a dropped-response retry is not applied twice (no duplicate campaign/provision/send).

threadId	string	required	The thread id, e.g. from inbox() or campaign events.
body	string	required
idempotencyKey	string	optional	Optional idempotency key: resend the SAME key when retrying this call so a dropped-response retry is not applied twice (no duplicate campaign/provision/send).

threadId	string	required	The thread id, e.g. from inbox() or campaign events.
status	string	required

action	string	required
id	string	optional	Required for update/promote/delete.
name	string	optional	Required for create. Optional for update — pass it to rename the view; omit to leave the name unchanged.
rev	integer	optional	Required for update — the rev this edit is based on; stale vs. the view's CURRENT rev returns a structured conflict with currentRev/currentLayout to rebase onto.
layout	object	optional	Required for create/update.
note	string	optional	Optional human-readable note recorded alongside this edit (edited_by_note).

Agent Cold Email

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

setup_infrastructure

infrastructure_status

launch_campaign

campaign_results

metrics

inbox

thread

reply

mark

pause

pause_all

account

get_dashboard

configure_dashboard

label_thread

list_campaigns

activity

agent-cold-email

What it is

The 17 tools

Install

First use: the free demo

Guardrails & compliance

Status & early access

License

Install

Remote endpoint

limit	integer	optional
cursor	string	optional
mailbox	string	optional
campaign	string	optional
label	string	optional
read	boolean	optional
includeNonreply	boolean	optional
archived	string	optional