# cold.md plugin

> Run your whole cold email loop from Claude Code with the open cold.md plugin. Eleven skills and one /cold command source leads, draft, send through FoxReach, run A/B tests and propose edits to your cold.md from the results.

## Overview

[cold.md](https://cold.md) is an open spec for describing your outbound as one markdown file in your repo: who you are, who you write to, the offer, your voice, the facts you may cite, the sequence, your answers to objections, and the phrases that must never appear. The **cold.md plugin** for Claude Code reads that file and runs the loop around it, with FoxReach doing the sending.

It is a different tool from the [FoxReach Claude Code plugin](/integrations/claude-code-plugin). That plugin lets you ask Claude about any FoxReach resource. The cold.md plugin is opinionated: one `/cold` command per step of the loop, a policy file you commit, and an A/B loop that proposes changes to that file when a test finds a winner. You can install both.

| Step | Command | What happens in FoxReach |
|---|---|---|
| Who to reach | `/cold icp https://your-site.com` | Nothing yet. Optionally a free Lead Finder count to check the ICP is not empty |
| Find leads | `/cold leads` | A CSV is verified and imported, or Lead Finder searches and reveals work emails |
| Write | `/cold draft` | Nothing. Drafts stay in your repo until you send |
| Send | `/cold send` | Campaign, sequence steps, mailboxes and leads are created, then the campaign starts |
| Answer | `/cold triage` | Unread replies are categorized and drafts are written; nothing is sent without your yes |
| Learn | `/cold learn` | Reply categories per A/B variant are read and tested |
| Report | `/cold report weekly` | Sends, replies, mailbox health and credits in one digest |

The plugin is open source (MIT) and the spec is CC-BY-4.0. Source: [github.com/foxreach/cold-md](https://github.com/foxreach/cold-md).

## Prerequisites

- **Claude Code** installed and signed in
- **Python 3** with `pip`, for the FoxReach CLI the sending skills call
- A **FoxReach account** with at least one connected, warmed mailbox ([connect one](/get-started/connect-email-account))
- **Lead Finder** sourcing needs a paid plan. Importing your own CSV works on every plan.

## Installation

Inside a Claude Code session:

```
/plugin marketplace add foxreach/cold-md
/plugin install cold-md@cold-md
```

Or from a terminal, which does the same through the `claude` CLI and falls back to copying the skills into `~/.claude` when the CLI is not on your PATH:

```bash
curl -fsSL https://cold.md/install | bash
```

Then install the [FoxReach CLI](/sdks/cli), which the sending skills use for every call:

```bash
pip install foxreach-cli
```

### Create an API key

In the FoxReach dashboard, open **Settings > Integrations**, expand **API Keys**, and click **Create Key**. Name it (for example `cold.md`), keep both **Read** and **Write** scopes selected, and click **Create Key**. Copy the key from the **Save your API key now** panel before you click **Done**; it is shown only once.

<Frame caption="The API Key Created dialog in FoxReach, the one place the full otr_ key is shown">
  <img src="/images/guides/api-keys-and-webhooks/create-api-key.webp" alt="The API Key Created dialog in FoxReach, the one place the full otr_ key is shown" />
</Frame>

Export it in the shell where Claude Code runs:

```bash
export FOXREACH_API_KEY="otr_your_key"
```

The key is scoped to the workspace it was created in, so the campaigns cold.md creates land in that workspace.

## Set up your repo

In your project, run:

```
/cold init
```

It asks nine short questions (where leads come from, whether to verify emails, whether to use provider matching, how big a test sample must be) and writes `.cold/config.json`. It then checks the key, lists your connected mailboxes and shows your verification and Lead Finder credit balances. If the folder has no `cold.md` yet, it starts one from the minimal template.

Commit `cold.md`, `icp.md` and the `.cold/` folder. They are your outbound policy and its history, and they travel with the repo.

## What each step uses in FoxReach

### Leads and verification

`/cold leads --csv prospects.csv` scores each row against `icp.md`, drops the ones that fail, runs the rest through [email verification](/get-started/verify-emails) and imports what is left. Addresses that come back bad are never imported. Only definite good or bad verdicts use a verification credit.

`/cold leads --finder --count 200` turns `icp.md` into Lead Finder filters, shows you the free match count, searches, scores the results, and asks you to confirm the reveal cost before any work email is revealed. A reveal is charged only when an email is found and the address is not already one of your leads. Revealed people are then added to your leads.

### Sending

`/cold send` runs pre-flight checks before anything is created:

- Every subject and body against the `## Banned` list in your `cold.md`
- Every lead against the audience and "Not for" lines
- Mailbox health: a mailbox whose inbox placement is under your floor (70 by default) is left out
- Template variables and spin syntax, so no lead receives an empty `{{firstName}}`
- Provider matching: from `foxreach campaigns esp-mix`, it turns on [provider matching](/get-started/create-campaign#how-sending-works-once-the-campaign-is-live) when your mailboxes and your leads both span Google and Microsoft

Then it creates the campaign, adds one sequence step per `## Sequence` slot in your `cold.md`, assigns mailboxes and leads, and asks before starting. With provider matching on, a new campaign can wait up to 30 minutes while recipient providers are looked up; that is expected.

### A/B tests

`/cold experiment` picks one variable to test (subject line, opener, call to action, cadence or tone) and writes the protocol down before anything sends. `/cold draft` writes the control and the variant.

The FoxReach API can read A/B variants but cannot create them yet, so one step happens in the app. `/cold send` writes the control as the sequence step, then prints the variant copy and the steps to add it: pause or open the draft campaign, go to the **Sequences** tab, click **Add A/B Test** on the step, and paste the copy into **Variant B**. See [A/B testing](/product/ab-testing) for the editor. When you say you are done, the skill reads the variant IDs back and records them in the experiment.

### Learning from replies

After the test window (7 days and 100 sends per variant by default), `/cold learn` reads reply categories per variant, compares interested-reply rates with a two-proportion z-test, and, if one variant wins, writes a proposed change to your `cold.md` as a patch. You apply it or reject it. After three approved changes in a row, it can apply them on its own; one rejection turns that off again.

Run `/cold triage` before `/cold learn`. A reply only counts as interested once it has a category, and triage is what sets it.

## Troubleshooting

**`/cold` is not available after installing**
Restart Claude Code. Plugins load when a session starts.

**"foxreach: command not found"**
Run `pip install foxreach-cli` in the environment Claude Code uses, then try again.

**Authentication errors**
Check that the key starts with `otr_`, has not been revoked under **Settings > Integrations > API Keys**, and is exported in the shell where Claude Code runs.

**`/cold send` stops at the mailbox check**
Every assigned mailbox is under your health floor, or none has enough warmup history yet. Let warmup run, or lower `guards.minAccountHealth` in `.cold/config.json`.

**Lead Finder commands return 402 or 403**
Lead Finder needs a paid plan and reveal credits. Use `/cold leads --csv` with your own list instead.