Unofficial Smartlead Cli

📬 unofficial-smartlead-cli

The complete CLI for Smartlead

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)

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

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

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:

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:

{
  "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

$ 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

$ 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 — GTM Engineer · creator & maintainer

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

> Shoutout to my friends at GTM Cafe — 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
• Source: 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.