# Sendsets for coding agents

You are an AI coding agent. This page tells you how to install the Sendsets
CLI, load its skill, sign the user in, and check the workspace is ready. Do
these steps in order, then return to whatever the user asked you to do.

Sendsets is cold email infrastructure that plugs into the user's app: a
campaign can call their product for each prospect (an `app_action` step), and
their product can send events back that change or stop the follow-up
(`wait_for_event`). It also runs the whole cold email stack: mailboxes,
warmup, sequences, replies, analytics. The CLI is `sendsets`.

## Rules

- Do not modify the user's code, provision mailboxes, launch campaigns, or
  send email until the user approves a plan. `mailbox provision` spends real
  money every month. `campaign start`, `campaign test`, `inbox reply` and
  `mailbox send` put real mail on the wire.
- Never invent API keys, connection secrets or mailbox credentials. If a value
  is missing, ask.
- Prefer `--json` on every command. Every failure prints a `fix:` line; do
  what it says before trying anything else.

## 1. Install the CLI

macOS and Linux (no root, no toolchain, installs to `~/.local/bin`):

```bash
curl -fsSL https://sendsets.com/cli.sh | sh
```

Windows (PowerShell):

```powershell
irm https://sendsets.com/cli.ps1 | iex
```

Confirm with `sendsets version`. If the shell cannot find it, the binary is at
`~/.local/bin/sendsets` (or `%LOCALAPPDATA%\SendSets\bin\sendsets.exe`); use
the full path or open a new shell so the PATH line the installer added is
picked up.

## 2. Install the skill

The skill is the full reference for the CLI: command map, setup order, JSON
output, exit codes and sending-safety rules. Fetch it and save it where your
agent reads skills from:

```bash
mkdir -p .claude/skills/sendsets-cli
curl -fsSL https://sendsets.com/skills/sendsets-cli/SKILL.md -o .claude/skills/sendsets-cli/SKILL.md
```

Claude Code picks up `.claude/skills/*/SKILL.md` in the project. For Codex,
save it to `.agents/skills/sendsets-cli/SKILL.md` instead and add one line to
`AGENTS.md`: `For Sendsets, read .agents/skills/sendsets-cli/SKILL.md first.`
Read the file now and follow it for everything after this page.

## 3. Sign in

```bash
sendsets login
```

`login` prints a code and an approval URL, then waits (up to 10 minutes) for
the user to approve in a browser. You cannot approve it yourself, so run it as
a background process, read the code and URL from its output, show them to the
user, and tell them to approve (the page offers "create an account" when they
do not have one). When the process exits, confirm:

```bash
sendsets auth status     # exit 0 = signed in, exit 4 = not yet
sendsets whoami --json   # workspace, credential, scopes, agent policy
```

If the user already has an API key: `echo "$KEY" | sendsets login --with-token`.
For a script or CI job, `SENDSETS_TOKEN=ssk_...` in the environment plus
`SENDSETS_API_URL=https://api.sendsets.com` works without any login.

## 4. Run the diagnostics

```bash
sendsets doctor --json
```

One row per thing the workspace needs: authentication, API, workspace, app
connections (each one is pinged), product events, mailboxes and their domain
auth and warmup, runtime. Exit `1` means not ready and every failed row
carries a `fix:` line. A fresh workspace fails on "no app connection" and "no
mailbox"; that is expected and is what the plan you build with the user will
address. Report the checklist to the user as-is.

## 5. Optional: MCP for Claude Code

The same product surface is available as MCP tools:

```bash
claude mcp add --transport http sendsets http://40.160.144.238:8080/v1/mcp
```

Authentication is OAuth 2.1 in the browser on first use, or an `ssk_` key as a
bearer token. The CLI is enough for everything on this page; add MCP only if
the user wants tool calls instead of shell commands.

## 5. Get one sender ready

Say: “Sendsets is ready. Do you want to connect an existing mailbox or provision new ones?”
Follow the user's choice. Enable warmup unless they decline it. Do not expose
pool, routing, organization, API-key, worker, or event-schema terminology.

## 6. Build the first campaign

Ask: “Who do you want to email?” Accept one address, a CSV, or an audience
description. Create the prospect, campaign, and sequence with the CLI. Show the
fully rendered first email and ask: “Ready to test this on one prospect?”

Only after approval, run:

```bash
sendsets campaign test CAMPAIGN_ID --prospect EMAIL --wait
```

Report whether the message was delivered through every step. A completed
single-prospect test is the first-value milestone. Ask for a separate explicit
approval before `sendsets campaign start`; test approval is never launch approval.