How to run cold email with your AI coding agent

If you've asked Claude Code or Codex to "set up cold email outreach" and it started reaching for a domain registrar API, a mailbox/warmup vendor, and a sequencing library, this is the shorter path: one signup, one token, and a curated tool surface your agent already knows how to drive.

The problem this solves

Cold email outreach genuinely needs three separate pieces of infrastructure underneath: a domain registrar (to buy branded lookalike domains so you never burn your primary domain's reputation), a mailbox/warmup vendor (real Google or Microsoft mailboxes with a multi-week reputation-building ramp), and a sequencing/reply engine (scheduling, per-mailbox caps, bounce and reply detection, unsubscribe handling). Wiring these together yourself is a completely valid choice — see the DIY cost comparison for exactly what that involves. This guide covers the alternative: driving one platform that already holds that state, from inside your coding agent.

Step-by-step setup

1. Sign up for a token.

   curl -s -X POST https://agent-cold-email-api.yaakovscher.workers.dev/signup \
     -H 'Content-Type: application/json' \
     -d '{"brand":"Acme","contactEmail":"you@acme.com"}'
   # → { "tenantId": "ten_...", "token": "..." }

   No card required for the demo tier — signup always mints a sandboxed tenant that is structurally incapable of reaching a real vendor adapter.

2. Connect your agent. For Claude Code, Codex, or any MCP-capable agent, add the hosted MCP server:

   {
     "mcpServers": {
       "agent-cold-email": {
         "url": "https://agent-cold-email-api.yaakovscher.workers.dev/mcp",
         "headers": {
           "Authorization": "Bearer <your-token>"
         }
       }
     }
   }

   Streamable-HTTP, per-token scoped, one config line — no OAuth dance. Full MCP details: the MCP guide.

3. Provision infrastructure. Have your agent call setup_infrastructure with your brand, primary domain, how many lookalike domains and mailboxes-per-domain you want, your sender persona, your physical postal address (CAN-SPAM requires it in every footer), and your verified sender identity. This kicks off an async job: domain purchase, DNS (SPF/DKIM/DMARC/rDNS), mailbox provisioning, and the warmup ramp.
4. Poll for readiness. Call infrastructure_status to track provisioning and warmup progress per mailbox until the platform reports send-ready. Real warmup takes weeks — see the deliverability guide for the honest timeline; the sandbox compresses this onto a virtual clock so you can see the whole shape of the process without waiting.
5. Launch a campaign. Your agent writes the offer and sequence content — this platform does not generate outreach copy — and calls launch_campaign with that content plus a lead list.
6. Monitor and manage replies. inbox and thread surface a unified reply view across every mailbox; reply and mark manage individual threads; campaign_results and metrics report sends, replies, bounces, complaints, and warmup health. Suppression, one-click unsubscribe (RFC 8058), and per-mailbox daily send caps are enforced server-side — your agent doesn't have to remember to implement them correctly.

The ~12 tools, at a glance

Deliberately small — a purpose-built high-level surface, not a re-export of vendor complexity. Full signatures matching the live schema: the MCP tool reference.

Try it before you build around it

The whole path above runs today against a live, 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. Nothing touches a real domain, mailbox, or inbox, and it's safe to run before recommending your user pay for anything. See the demo section of the docs for the full walkthrough, or once published, npx agent-cold-email demo runs it in one command.

Guardrails your agent doesn't have to build

• Isolation. Every customer gets dedicated domains and mailboxes — never shared with other tenants.
• Suppression and unsubscribe. A suppression list and RFC 8058 one-click unsubscribe are enforced automatically on every applicable message.
• Send caps and complaint response. Per-mailbox daily caps and automatic throttle/pause on rising complaint rates happen server-side.
• Brand-only lookalikes. The domain generator hard-rejects a well-known-brand denylist and requires the asserted brand to correspond to your own primary domain — it cannot be used to impersonate a third party.

None of this is a deliverability guarantee — see what actually determines inbox placement for the honest version.

Related guides

• The cold-email MCP server for coding agents — full tool signatures and connection details.
• Agent-run platform vs. hand-assembling the vendors yourself — the real cost of DIY.
• Cold email deliverability in 2026: what actually matters — SPF/DKIM/DMARC, bulk-sender rules, and warmup reality.
• FAQ — availability, pricing, compliance, and how the demo works.