Open Source·AI Agent Infrastructure

Your Cold Email Stack, Controlled by Agents.

Campaigns. Sequences. Leads. Inbox. Analytics. 142 commands. Every one doubles as an MCP tool.

Smartlead.ai runs your cold email engine — but your agents can’t touch it from a terminal.
So we built smartlead-cli — the missing CLI for agents on Smartlead.

Install from npm
142
Commands
11
API Groups
CLI
+ MCP Native
OpenClaw
OpenClaw
CLI / MCP
Smartlead
Smartlead
campaigns · sequences · leads · inbox · analytics

Why smartlead-cli Exists

Without smartlead-cli

  • No official CLI — Smartlead only offers a REST API and dashboard UI
  • Agents can’t launch campaigns, manage leads, or triage replies without custom wrappers
  • Manual API auth per request — no token resolution strategy
  • No MCP support — agents can’t call Smartlead as a native tool
  • Campaign analytics and sequence data locked in the dashboard

With smartlead-cli

  • 142 commands covering the full Smartlead API surface
  • Single API key, 3-tier resolution: flag → env var → config file
  • Every command is also an MCP tool — plug into any AI agent
  • JSON-first output — pipe to jq, save to files, feed to agents
  • Full sequence management — define multi-step flows programmatically

When You Need This

🚀

Autonomous Campaign Launch

Create campaigns, write sequences, assign sending accounts, import leads, and activate — all from a single agent prompt.

📬

Reply Triage & Inbox Management

Read full message threads, reply to prospects, and update lead status across all your campaigns without opening the dashboard.

🔥

Warmup Monitoring

Pull 7-day warmup stats per account, adjust daily ramp-up targets, and catch deliverability issues before they hurt your campaigns.

📊

Campaign Analytics on Demand

Pull opens, clicks, replies, bounces, and time-series data for any date range — metrics your agent can act on immediately.

👥

Lead Lifecycle Management

Add leads in bulk, pause/resume individuals, handle unsubscribes globally or per-campaign, and block entire domains from one command.

🏢

Agency & Multi-Account

Manage client sub-accounts, generate API keys per client, and run separate campaign environments from a single CLI.

Quick Start

1. Install

Terminal
npm install -g @bcharleson/smartlead-cli

2. Get your API key

1. Log into your Smartlead workspace

2. Navigate to Settings → API Key

3. Copy your API key

3. Authenticate

Terminal
# Option A: environment variable (recommended for agents)
export SMARTLEAD_API_KEY="your-api-key"

# Option B: login command (saves to ~/.smartlead-cli/config.json)
smartlead login

# Option C: per-command flag
smartlead campaigns list --api-key "your-api-key"

4. Verify

Terminal
smartlead campaigns list --pretty
# Returns your campaigns as formatted JSON

smartlead email-accounts list --pretty
# Lists your connected sending accounts

smartlead analytics overview --pretty
# Global stats across all campaigns

What smartlead-cli Gives Your Agent

7 cmds

Campaign Management

Create, schedule, activate, pause, and stop campaigns. Full lifecycle control — from drafted to live with schedules, stop rules, tracking settings, and AI ESP matching.

2 cmds

Sequences

Get and save full multi-step sequences with variants, delays, and A/B distribution. Programmatically define every touchpoint in your outreach flow.

9 cmds

Email Accounts

Add SMTP/IMAP accounts, configure warmup ramp-up, monitor warmup stats, and assign accounts to campaigns. Full sending infrastructure management.

12 cmds

Lead Management

Add leads in bulk, pause/resume individuals, unsubscribe globally or per-campaign, block domains, and export as CSV. Full lead lifecycle from import to removal.

5 cmds

Analytics

Pull campaign stats, time-series analytics by date range, lead funnel metrics, and a global overview across all campaigns. Every metric your agent needs to act on.

MCP Server

Every command is exposed as an MCP tool. Claude, Cursor, OpenClaw, and any MCP client can call all 142 commands natively — no wrappers, no custom code.

Agent Workflows

Real prompts agents use to manage Smartlead cold email operations end-to-end.

Full Campaign Launch from Scratch

Agent Prompt

“Launch a cold email campaign targeting SaaS CTOs. Create it, schedule weekday sending EST, assign my sending account, write a 3-step sequence, import these leads, and activate it.”

Agent builds the entire campaign end-to-end: creates the shell, sets the schedule, assigns the email account, writes the sequence, imports leads, and activates — all in one autonomous run.

1
smartlead campaigns create --name "Q2 SaaS CTO Outreach"

Create campaign (starts DRAFTED)

2
smartlead campaigns schedule $ID --timezone "America/New_York" --days-of-week "[1,2,3,4,5]" --start-hour "09:00" --end-hour "17:00" --max-leads-per-day 40

Set sending schedule

3
smartlead email-accounts add-to-campaign --campaign-id $ID --account-id $ACCT

Assign sending account

4
smartlead sequences save $ID --sequences '[{"seq_number":1,...}]'

Write 3-step sequence with variants

5
smartlead leads add-to-campaign --campaign-id $ID --lead-list '[{"email":"cto@acme.com","first_name":"Alex","company_name":"Acme"}]'

Import leads

6
smartlead campaigns update-status $ID --status ACTIVE

Go live

7
smartlead analytics campaign-stats --campaign-id $ID --pretty

Verify delivery is flowing

Morning Reply Triage

Agent Prompt

“Check my campaigns for new replies overnight. Pull thread history for any interested leads and flag anyone who replied positively.”

Agent scans reply activity, reads full conversation threads for interested leads, and surfaces actionable responses — inbox triage without opening the dashboard.

1
smartlead analytics overview --pretty

Global reply count across all campaigns

2
smartlead leads list-campaign --campaign-id $ID --limit 50

Get leads with recent activity

3
smartlead inbox message-history --campaign-id $ID --lead-id $LEAD_ID

Read full thread for each reply

4
smartlead leads update --lead-id $LEAD_ID --status "Interested"

Tag interested leads for follow-up

Warmup Health Check

Agent Prompt

“Check warmup stats for all my sending accounts. Flag any that are underperforming and show me the last 7 days of warmup data.”

Agent audits every sending account, surfaces warmup performance issues before they hurt deliverability, and gives you a clear health picture across your entire infrastructure.

1
smartlead email-accounts list --pretty

List all connected accounts

2
smartlead email-accounts warmup-stats $ACCT_ID

Pull 7-day warmup stats per account

3
smartlead email-accounts update-warmup $ACCT_ID --total-warmup-per-day 30 --daily-rampup 3

Adjust warmup targets if needed

Commands Reference

campaigns (7 commands)
smartlead campaigns listList all campaigns
smartlead campaigns get <id>Get a campaign by ID
smartlead campaigns create --name <name>Create a campaign (starts DRAFTED)
smartlead campaigns update-status <id> --status ACTIVE|PAUSED|STOPPEDChange campaign status
smartlead campaigns update-settings <id> [--track-settings] [--stop-rules]Tracking, stop rules, AI ESP matching
smartlead campaigns schedule <id> --timezone <tz> --days-of-week <json>Set timezone, days, hours, max leads/day
smartlead campaigns delete <id>Delete a campaign (irreversible)
sequences (2 commands)
smartlead sequences get <campaign_id>Fetch all steps with variants and delays
smartlead sequences save <campaign_id> --sequences <json>Replace full sequence (all steps at once)
email-accounts (9 commands)
smartlead email-accounts listList all email accounts
smartlead email-accounts get <id>Get an account by ID
smartlead email-accounts create --from-email <e> --smtp-host <h>Add SMTP/IMAP account
smartlead email-accounts update <id>Update account settings
smartlead email-accounts update-warmup <id> --warmup-enabledConfigure warmup ramp-up
smartlead email-accounts warmup-stats <id>Last 7 days warmup stats
smartlead email-accounts list-campaign --campaign-id <id>List accounts for a campaign
smartlead email-accounts add-to-campaign --campaign-id <id> --account-id <id>Assign account to campaign
smartlead email-accounts remove-from-campaign --campaign-id <id> --account-id <id>Remove account from campaign
leads (12 commands)
smartlead leads get-by-email --email <e>Find lead across all campaigns
smartlead leads list-campaign --campaign-id <id>List leads in a campaign (paginated)
smartlead leads add-to-campaign --campaign-id <id> --lead-list <json>Add leads JSON array to a campaign
smartlead leads update --lead-id <id>Update lead fields
smartlead leads pause --campaign-id <id> --lead-id <id>Pause sending to a lead
smartlead leads resume --campaign-id <id> --lead-id <id>Resume a paused lead
smartlead leads unsubscribe-campaign --campaign-id <id> --lead-id <id>Unsubscribe from one campaign
smartlead leads unsubscribe-global --email <e>Globally unsubscribe (all campaigns)
smartlead leads delete --campaign-id <id> --lead-id <id>Delete lead from campaign
smartlead leads get-campaigns --email <e>Get all campaigns a lead is in
smartlead leads add-domain-block --domain <domain>Block an entire domain
smartlead leads export --campaign-id <id>Export leads as CSV
inbox (2 commands)
smartlead inbox message-history --campaign-id <id> --lead-id <id>Full email thread for a lead
smartlead inbox reply --campaign-id <id> --lead-id <id> --email-body <html>Reply to a lead via Master Inbox
analytics (5 commands)
smartlead analytics campaign-stats --campaign-id <id>Opens, clicks, replies, bounces summary
smartlead analytics campaign-analytics --campaign-id <id>Top-level performance metrics
smartlead analytics campaign-analytics-by-date --campaign-id <id> --start-date <iso> --end-date <iso>Time-series data by date range
smartlead analytics lead-stats --campaign-id <id>Lead funnel: interested, in progress, completed
smartlead analytics overviewGlobal analytics across all campaigns
webhooks (4 commands)
smartlead webhooks listList all webhooks
smartlead webhooks create --name <n> --url <url> --events <list>Create webhook for email events
smartlead webhooks update <id>Update a webhook
smartlead webhooks delete <id>Delete a webhook
clients (6 commands)
smartlead clients listList all client sub-accounts
smartlead clients save --name <n> --email <e> --password <p>Create or update a client
smartlead clients list-api-keys --client-id <id>List client API keys
smartlead clients create-api-key --client-id <id> --key-name <n>Generate a new API key
smartlead clients delete-api-key <id>Delete an API key
smartlead clients reset-api-key <id>Regenerate an API key

MCP Server Setup

Every command is available as an MCP tool. Configure once and your agent has full Smartlead access.

Claude Desktop / Cursor (~/.cursor/mcp.json or claude_desktop_config.json)
{
  "mcpServers": {
    "smartlead": {
      "command": "npx",
      "args": ["-y", "@bcharleson/smartlead-cli", "mcp"],
      "env": {
        "SMARTLEAD_API_KEY": "your-api-key"
      }
    }
  }
}

Sample MCP tools available (142 total):

campaigns_listcampaigns_createcampaigns_update_statuscampaigns_schedulesequences_getsequences_saveemail_accounts_listemail_accounts_createemail_accounts_update_warmupemail_accounts_warmup_statsleads_add_to_campaignleads_pauseleads_resumeleads_exportleads_add_domain_blockinbox_message_historyinbox_replyanalytics_campaign_statsanalytics_overviewanalytics_campaign_analytics_by_datewebhooks_createwebhooks_listclients_listclients_saveclients_create_api_key+117 more

OpenClaw Agent Setup

Give any OpenClaw agent full Smartlead access. Install once, set the API key, and the agent manages your cold email operation autonomously.

1
Install on the agent's server
npm install -g @bcharleson/smartlead-cli
2
Set API key in agent environment
export SMARTLEAD_API_KEY=your-key — or use smartlead login to save to config
3
Start MCP server
smartlead mcp — runs on stdio transport, compatible with any MCP client
4
Add cold email instructions to SOUL.md
Tell the agent how to manage campaigns, triage replies, monitor warmup health, and handle unsubscribes
5
Test from Slack
"Check reply rates on all active campaigns today" — agent calls smartlead analytics via MCP, returns stats as structured JSON

Architecture

Every API endpoint is a CommandDefinition — one source of truth powering both the CLI subcommand and the MCP tool.

src/
├── core/
│   ├── types.ts          # CommandDefinition, SmartleadClient interfaces
│   ├── client.ts         # HTTP client (?api_key=, retry, rate limit)
│   ├── auth.ts           # 3-tier API key resolution
│   ├── config.ts         # ~/.smartlead-cli/config.json
│   ├── errors.ts         # Typed error classes
│   ├── output.ts         # JSON output + --fields filtering
│   └── handler.ts        # Request builder from CommandDefinition
├── commands/
│   ├── campaigns/        # 7 commands
│   ├── sequences/        # 2 commands
│   ├── email-accounts/   # 9 commands
│   ├── leads/            # 12 commands
│   ├── inbox/            # 2 commands
│   ├── analytics/        # 5 commands
│   ├── webhooks/         # 4 commands
│   ├── clients/          # 6 commands
│   ├── crm/              # CRM integration commands
│   ├── lead-lists/       # Lead list management
│   └── smart-delivery/   # Deliverability commands
├── mcp.ts                # MCP server (auto-registers all commands)
└── index.ts              # CLI entry point

Same pattern as all TOFU CLIs

The CommandDefinition architecture is shared across instantly-cli, heyreach-cli, hubspot-cli, clay-cli, and more. One schema generates the Commander.js subcommand, the Zod schema, and the MCP tool — zero duplication.

Smartlead API Specifics

Auth via ?api_key= query param (auto-injected). Rate limit: 10 req/2s with auto-retry backoff. Base URL: server.smartlead.ai/api/v1. Sequences use a replace-all pattern — always send the full sequence array.

Ready to automate your cold email operation?

Install smartlead-cli, set your API key in 60 seconds, and your agent can launch campaigns, triage replies, monitor warmup, and manage your entire Smartlead operation autonomously.

Need agents running your cold email operation? We deploy and manage the full setup.