# Unofficial Smartlead Cli

> Complete CLI and MCP server for Smartlead — 270+ commands, reverse-engineered internal endpoints, and Claude Code skills. Built by GTM engineers, free for the community.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mattsezgin-unofficial-smartlead-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MattSezgin](https://agentstack.voostack.com/s/mattsezgin)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MattSezgin](https://github.com/MattSezgin)
- **Source:** https://github.com/MattSezgin/unofficial-smartlead-cli
- **Website:** https://github.com/MattSezgin/unofficial-smartlead-cli

## Install

```sh
agentstack add mcp-mattsezgin-unofficial-smartlead-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 📬 unofficial-smartlead-cli

### The complete CLI for [Smartlead](https://smartlead.ai)
*Built by a GTM engineer who got tired of clicking.*

[](LICENSE)
[](https://github.com/MattSezgin/unofficial-smartlead-cli/stargazers)
[](https://claude.com/claude-code)
[](https://nodejs.org)

### 🚀
**270+ commands**

Every public Smartlead endpoint, mapped to a CLI subcommand

### 🤖
**Native Claude Code**

11 ready-to-use slash commands — just type `/` and pick

### 🔓
**Reverse-engineered API**

`bulk-update` · `GraphQL` · `agents-api` · `Smart Delivery`

### 📚
**Production playbook**

The deliverability lessons Smartlead's own docs don't cover

> **Run it in your shell, or use it inside Claude Code.** Same tool, two ways to talk to it.

---

## 🚀 Quick start

### Use it in Claude Code (recommended)

```bash
git clone https://github.com/MattSezgin/unofficial-smartlead-cli.git
cd unofficial-smartlead-cli
npm install && npm run build
```

Open the folder in Claude Code. Type:

```
/smartlead-onboarding
```

That's it. Claude walks you through getting your API key set up. Then **11 slash commands** are available — just type `/` and pick.

### 🚀 Run a campaign

| Skill | What it does |
|---|---|
| `/create-campaign` | Full campaign wizard — name, schedule, sequences, mailboxes, leads |
| `/upload-leads` | CSV upload with dedup + 100-batch pagination |
| `/launch-campaign` | Pre-flight checks, then start |
| `/clone-campaign` | Duplicate a campaign via the 6-step API recipe |

### 📬 Mailbox infrastructure

| Skill | What it does |
|---|---|
| `/warmup-mailboxes` | Apply verified production warmup config to N mailboxes |
| `/audit-mailbox-config` | Verify mailbox settings against the golden standard |

### 📊 Diagnose & report

| Skill | What it does |
|---|---|
| `/check-deliverability` | Full audit — bounce rate, ESP routing, warmup health |
| `/spam-test` | Smart Delivery spam test, parse DKIM/SPF/DMARC + inbox % |
| `/weekly-report` | Performance digest across all campaigns |
| `/compare-campaigns` | Head-to-head A/B with significance check |
| `/smartlead-onboarding` | First-time API key + JWT setup (you'll only run this once) |

### Or use it as a CLI

```bash
npm install -g unofficial-smartlead-cli
export SMARTLEAD_API_KEY="your-key"

smartlead campaigns list
smartlead leads list 
smartlead accounts warmup  --enable --daily 20 --rampup 5 --reply-rate 60
```

```bash
smartlead --help          # see all 23 command families
smartlead  --help # drill into one
```

---

## 🧠 What's actually in here

Three things that don't exist anywhere else, all free:

### 1. The complete API surface

23 command families covering everything Smartlead's docs cover — and a bunch they don't. Public REST, internal JWT endpoints, GraphQL (`fe-gql.smartlead.ai`), Smart Delivery, Smart Senders, Smart Prospect, wallet, agents-api.

[Full command list →](docs/api-coverage.md)

### 2. Claude Code skills

`.claude/skills/` ships with 6 ready-to-go slash commands. Clone the repo, open in Claude Code, start typing `/`.

### 3. Hard-won learnings — the stuff Smartlead's docs don't tell you

The reverse-engineering finds that took months to figure out. All in [`docs/learnings/`](docs/learnings/):

- 🔓 **[The undocumented bulk-update endpoint](docs/learnings/bulk-update-endpoint.md)** — the only API path that exposes every UI-controllable field
- 🗺️ **[JWT vs api_key map](docs/learnings/jwt-vs-apikey-map.md)** — which endpoints really need which auth (Smartlead's docs lie about this)
- 🚧 **[The rate limit](docs/learnings/rate-limits.md)** — the undocumented ~200-GETs-then-HTML wall
- ✉️ **[ESP matching analysis](docs/learnings/esp-matching-analysis.md)** — why "AI ESP matching" costs you +11pp on Google Workspace bounces
- 🌡️ **[Mailbox warmup best practices](docs/learnings/mailbox-warmup-best-practices.md)** — a verified production-grade config
- 🏷️ **[`warmup_key_id` format](docs/learnings/warmup-key-id-format.md)** — what the UI enforces vs. what the API accepts
- 🔧 **[Settings API quirks](docs/learnings/settings-api-quirks.md)** — three places POST and GET disagree
- 📋 **[Campaign cloning runbook](docs/learnings/campaign-cloning-runbook.md)** — the 6-step recipe Smartlead never documented

---

## 🛠️ Install options

| Setup | Command |
|---|---|
| Global CLI | `npm install -g unofficial-smartlead-cli` |
| Project local | `npm install unofficial-smartlead-cli` |
| From source | `git clone` + `npm install && npm run build` |
| As MCP server | See [MCP setup](#mcp-server) below |

### Authentication

Set these as env vars or write to `~/.smartleadrc`:

```bash
export SMARTLEAD_API_KEY="your-public-api-key"
export SMARTLEAD_JWT_TOKEN="..."     # optional, for internal endpoints
export SMARTLEAD_SL_API_KEY="..."    # optional, for agents-api host
```

Or run `/smartlead-onboarding` in Claude Code and it'll do this for you.

### MCP server

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "smartlead": {
      "command": "smartlead-mcp",
      "env": {
        "SMARTLEAD_API_KEY": "your-key"
      }
    }
  }
}
```

Then Claude Code, Cursor, Continue, etc. can call Smartlead operations as native tools.

---

## 👀 What it looks like

```bash
$ smartlead campaigns list --output table

  ID        NAME                          STATUS    LEADS  SENT  REPLIES
  ────────  ────────────────────────────  ────────  ─────  ────  ───────
  1234567   Q1 Outbound — Founders        DRAFTING    142     0        0
  1234568   Q1 Outbound — Founders V2     ACTIVE      298   276        9
  1234569   Industry Event Follow-up      PAUSED      540   540       17
```

```bash
$ smartlead accounts warmup 99887 --enable --daily 20 --rampup 5 --reply-rate 60 --warmup-key acme1-pool1
✓ Warmup enabled for account 99887
✓ Settings: 1 → 20/day, +5/day rampup, 60% reply rate
✓ Pool: acme1-pool1
```

---

## 🤝 Contributing

Bug reports, new commands, doc improvements, and reverse-engineering finds all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## 📜 License

MIT — see [LICENSE](LICENSE).

## 👥 Maintainer

**[Matt Sezgin](https://www.linkedin.com/in/m-sezgin/)** — GTM Engineer · creator & maintainer

[](https://www.linkedin.com/in/m-sezgin/)

> Shoutout to my friends at **[GTM Cafe](https://gtmcafe.com/)** — the biggest GTM community on the internet. 🙌

---

> **Unofficial** means: this project is built around the Smartlead API but is not maintained by, endorsed by, or affiliated with Smartlead. Smartlead's API may change at any time. Use at your own discretion.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MattSezgin](https://github.com/MattSezgin)
- **Source:** [MattSezgin/unofficial-smartlead-cli](https://github.com/MattSezgin/unofficial-smartlead-cli)
- **License:** MIT
- **Homepage:** https://github.com/MattSezgin/unofficial-smartlead-cli

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mattsezgin-unofficial-smartlead-cli
- Seller: https://agentstack.voostack.com/s/mattsezgin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.