Instantly.ai in your terminal. Run cold email campaigns, manage leads, monitor deliverability, and automate every outbound motion — from a single command line.
156 commands across 31 API groups. Full coverage of the Instantly.ai V2 API. Built for humans, scripts, CI/CD pipelines, and AI agents.
npm install -g instantly-cli
CLI and MCP server for the Instantly.ai cold email platform
What is Instantly?
Instantly.ai is the leading cold email and outbound sales platform. It handles everything needed to run high-volume outbound at scale:
Unified inbox — read, reply, and forward across all sending accounts from one place
AI features — AI-powered lead labeling, interest classification, and response handling
What This CLI Enables
The Instantly CLI gives you programmatic access to the entire platform. Every action you can take in the Instantly dashboard, you can do from your terminal:
Campaign operations — create campaigns, add leads, launch sequences, pause/resume, duplicate, and monitor sending status without opening a browser.
Lead lifecycle — import leads in bulk, move them between campaigns, update interest status, merge duplicates, assign to subsequences, and manage labels — all scriptable.
Account management — connect sending accounts, enable/disable warmup, test DNS/SMTP/IMAP health, pause underperforming senders, and monitor CTD (click-to-deliver) status.
Deliverability monitoring — run inbox placement tests, analyze where emails land (inbox vs. spam vs. promotions), track ESP-level performance, and get actionable insights.
Analytics & reporting — pull campaign stats, daily breakdowns, per-step sequence analytics, warmup performance, and account-level sending volumes into any reporting tool.
Team & workspace admin — manage workspace members, API keys, billing info, audit logs, and whitelabel domains.
AI agent integration — every command works as both a CLI subcommand and an MCP tool, so AI assistants (Claude, Cursor, Windsurf) can manage your outbound directly.
Install
npm (recommended)
npm install -g instantly-cli
npx (zero-install)
npx instantly-cli campaigns list
From source
git clone https://github.com/bcharleson/instantly-cli.git
cd instantly-cli
npm install && npm run build
npm link
Authentication
Default mode is one workspace, one key. Existing single-key users do not need profiles.
Resolve order without--profile / INSTANTLY_PROFILE:
--api-key flag — pass on any command: instantly campaigns list --api-key <key>
One process, one workspace. There is no --all-profiles and no comma-separated key list.
instantly login --profile acme validates the key, GETs the live workspace, and binds that workspace UUID + name. It does not write or overwrite ~/.instantly/config.json.
When a profile is selected, it wins over a leftover cwd .envINSTANTLY_API_KEY.
Every profiled command re-fetches the live workspace. If workspace.id ≠ the bound id, the command aborts.
Write commands (campaign activate/pause, leads bulk-add, email reply/forward, and other mutations) also require --workspace <uuid> matching the bound id.
When --workspace is passed on any path (default or profile), the live workspace id must match or the command aborts. Omitted on the default single-key path: no extra flag required.
# Bind a client workspace to a named profile (does not touch default login)
instantly login --profile acme --api-key "$ACME_KEY"
instantly login --profile client-a --api-key "$CLIENT_A_KEY"
# Read-only: profile is enough
instantly --profile acme campaigns list
INSTANTLY_PROFILE=client-a instantly status
# Writes must confirm the bound workspace UUID
instantly --profile acme --workspace 11111111-1111-4111-8111-111111111111 \
campaigns activate 33333333-3333-4333-8333-333333333333
# Inspect / manage profiles (never prints API keys)
instantly profile list
instantly profile whoami
instantly profile remove acme
instantly status / whoami / profile list always print profile (slug or default), workspace_id, workspace_name, and source. They never print the API key. Confirm this bound pair before campaigns, health, or writes. Agencies should login --profile <client> for every key, including the house org.
Every existing command group (campaigns, leads, accounts, email, analytics, health, webhooks, oauth, …) uses this same resolver. There is no second, profile-only API.
After merge, dogfood with fake slugs client-a / client-b (your real keys stay local):
instantly status # default: profile "default" + bound workspace id/name
instantly login --profile client-a --api-key "$CLIENT_A_KEY"
# confirm ~/.instantly/config.json is unchanged
instantly --profile client-a status # prints bound workspace id + name
instantly --profile client-a campaigns list
instantly --profile client-a health
instantly --profile client-a --workspace "$WRONG_UUID" campaigns activate "$CAMPAIGN_ID"
# → abort; no mutation
# two files in ~/.instantly/profiles; never one command looping both
Quick Start
# Authenticate
instantly login
# List campaigns
instantly campaigns list
# Create a campaign and start sending
instantly campaigns create --name "Q2 Outreach"
instantly leads bulk-add --campaign-id <id> --leads '[{"email":"[email protected]","first_name":"Alex"}]'
instantly campaigns activate <id>
# Check analytics
instantly analytics campaign --id <id>
# Read replies
instantly email list --campaign-id <id> --is-read false
# Connect a Google sending account via OAuth
instantly oauth connect google
Output Formats
Every command outputs JSON by default — ready for piping to jq, parsing in scripts, or feeding to other tools.
# Default: compact JSON
instantly campaigns list
# Pretty-printed JSON
instantly campaigns list --pretty
# Select specific fields
instantly campaigns list --fields "id,name,status"
# Suppress output (exit code only)
instantly campaigns list --quiet
Commands
Profiles
Opt-in named workspace profiles for agents that must isolate client keys.
instantly login --profile acme --api-key <key> # Bind key → workspace; does not write config.json
instantly profile add acme --api-key <key> # Same persist path as login --profile
instantly profile list # Slug + workspace id/name only
instantly profile whoami # Source + profile + live workspace
instantly profile remove acme # Deletes the profile file only
Health
Read-only rollup of existing API data for the active profile or default key: disconnected accounts, bounce totals, warmup status, and campaign sending status.
instantly health
instantly --profile acme health
Campaigns (11)
Create, manage, and control outbound email campaigns.
instantly campaigns list # List all campaigns (paginated)
instantly campaigns get <id> # Get full campaign details
instantly campaigns create --name "Q2 Outreach" # Create a new campaign
instantly campaigns update <id> --name "Q2 Updated" # Update campaign settings
instantly campaigns activate <id> # Start sending
instantly campaigns pause <id> # Pause sending
instantly campaigns duplicate <id> # Clone a campaign
instantly campaigns search-by-contact --email "[email protected]" # Find campaigns containing a lead
instantly campaigns count-launched # Count active campaigns
instantly campaigns sending-status <id> # Diagnose why a campaign isn't sending
instantly campaigns delete <id> # Delete permanently
Instantly delivers HTML. Pass readable copy with real line breaks in each variant body; the CLI converts plain-text newlines to <br/>/<p>. Do not write a run-on string. Existing HTML is left unchanged. Skipped when text_only.
Applies to campaigns create / update and subsequences create (same Instantly body key).
delay on step N waits before step N+1. First email does not wait. Pass delay_unit (minutes|hours|days; omitted unit is set to days). Instantly uses only sequences[0]. A multi-step sequence with delay 0 or missing delay on a non-last step is rejected — the follow-up would send the same day. Last step delay may be 0. email_gap is a per-send rate limit, not the step gap. pre_delay is subsequence-only.
# Preferred: readable copy with real line breaks — CLI converts
instantly campaigns create --name "Plain Body" --sequences \
'[{"steps":[{"type":"email","delay":3,"delay_unit":"days","variants":[{"subject":"Hi {{first_name}}","body":"Hi {{first_name}},\n\nWorth a quick chat?"}]},{"type":"email","delay":0,"delay_unit":"days","variants":[{"subject":"Re: Hi","body":"Just bumping this."}]}]}]'
# Already tagged HTML is stored as-is (single email: last-step delay may be 0)
instantly campaigns create --name "With Sequences" --sequences \
'[{"steps":[{"type":"email","delay":0,"delay_unit":"days","variants":[{"subject":"Hi {{first_name}}","body":"<div>Hello</div>"}]}]}]'
Leads (12)
Import, manage, and move prospects across campaigns.
instantly leads list --campaign-id <id> # List leads in a campaign
instantly leads get <id> # Get lead details
instantly leads create --email "[email protected]" --campaign-id <id> # Add a single lead
instantly leads update <id> --first-name "Jane" # Update lead data
instantly leads bulk-add --campaign-id <id> --leads '[{"email":"[email protected]"}]' # Add up to 1,000 leads
instantly leads bulk-delete --campaign-id <id> --delete-all # Remove leads in bulk
instantly leads bulk-assign --lead-ids "id1,id2" --account-id <id> # Assign leads to senders
instantly leads move --lead-ids "id1,id2" --to-campaign-id <id> # Move between campaigns
instantly leads merge --lead-ids "id1,id2" # Merge duplicate leads
instantly leads update-interest-status --lead-id <id> --interest-status 1 # Set interest level
instantly leads remove-from-subsequence --lead-id <id> --subsequence-id <id>
instantly leads delete <id> # Delete a lead
Email Accounts (12)
Connect and manage sending accounts — SMTP/IMAP, Google, or Microsoft.
Subscribe to real-time events from your campaigns.
instantly webhooks list # List all webhooks
instantly webhooks get <id> # Get webhook details
instantly webhooks create --url "https://..." --event-type lead_interested
instantly webhooks update <id> --url "https://..." # Update webhook
instantly webhooks test <id> # Fire a test payload
instantly webhooks event-types # List available event types
instantly webhooks resume <id> # Re-enable a suspended webhook
instantly webhooks delete <id> # Delete webhook
Webhook Events (4)
Inspect webhook delivery history.
instantly webhook-events list # List webhook events
instantly webhook-events get <id> # Get event details
instantly webhook-events summary # Event delivery summary
instantly webhook-events summary-by-date # Summary grouped by date
Lead Lists (6)
Manage reusable lead lists for imports and enrichment.
instantly lead-lists list # List all lead lists
instantly lead-lists get <id> # Get list details
instantly lead-lists create --name "Q2 Prospects" # Create a list
instantly lead-lists update <id> --name "Updated" # Rename a list
instantly lead-lists verification-stats <id> # Email verification breakdown
instantly lead-lists delete <id> # Delete a list
Enrichment / SuperSearch (10)
Enrich leads with company and contact intelligence.
instantly enrichment enrich --search-filters '{"job_titles":["CTO"]}' --limit 100
instantly enrichment count --search-filters '{"industries":["SaaS"]}'
instantly enrichment get <resource-id> # Get enrichment settings
instantly enrichment run --resource-id <id> # Trigger enrichment
instantly enrichment create --name "Q2" --search-filters '{}' --enrichment-settings '{}'
instantly enrichment update-settings <resource-id> --enrichment-settings '{}'
instantly enrichment ai --resource-id <id> --prompt "Find CTOs in SaaS"
instantly enrichment ai-progress <resource-id> # Check AI enrichment status
instantly enrichment history <resource-id> # View enrichment history
instantly enrichment preview --search-filters '{}' # Preview matching leads
Blocklist (5)
Prevent sending to specific domains or email addresses.
instantly blocklist list # List blocked entries
instantly blocklist get <id> # Get entry details
instantly blocklist create --value "[email protected]" # Block an email/domain
instantly blocklist update <id> --value "[email protected]" # Update entry
instantly blocklist delete <id> # Remove from blocklist
Custom Tags (6)
Organize campaigns, leads, and resources with tags.
instantly custom-tags list # List all tags
instantly custom-tags get <id> # Get tag details
instantly custom-tags create --label "High Priority" # Create a tag
instantly custom-tags update <id> --label "Urgent" # Rename a tag
instantly custom-tags toggle --tag-ids "t1" --resource-ids "r1" --resource-type 1 --assign
instantly custom-tags delete <id> # Delete a tag
Custom Tag Mappings (1)
instantly custom-tag-mappings list # List tag-to-resource mappings
Lead Labels (6)
AI-powered labeling to categorize lead reply intent.
instantly lead-labels list # List all labels
instantly lead-labels get <id> # Get label details
instantly lead-labels create --label "Hot Lead" --interest-status "positive"
instantly lead-labels update <id> --label "Warm Lead" # Update label
instantly lead-labels test-ai --reply-text "Yes, I'm interested" # Test AI classification
instantly lead-labels delete <id> # Delete label
Workspace (6)
Manage workspace settings and whitelabel configuration.
instantly workspace get # Get workspace info
instantly workspace update --name "My Workspace" # Update workspace
instantly workspace whitelabel-create --domain "mail.example.com"
instantly workspace whitelabel-get # Get whitelabel domain
instantly workspace whitelabel-delete # Remove whitelabel
instantly workspace change-owner --email "[email protected]" # Transfer ownership
Workspace Members (5)
Manage team access and roles.
instantly workspace-members list # List team members
instantly workspace-members get <id> # Get member details
instantly workspace-members create --email "[email protected]" --role admin
instantly workspace-members update <id> --role member # Change role
instantly workspace-members delete <id> # Remove member
Workspace Group Members (5)
Manage workspace group membership.
instantly workspace-group-members list # List group members
instantly workspace-group-members get <id> # Get member details
instantly workspace-group-members create --user-id <id> --group-id <id>
instantly workspace-group-members get-admin # Get admin info
instantly workspace-group-members delete <id> # Remove from group
Workspace Billing (2)
instantly workspace-billing plan-details # View current plan
instantly workspace-billing subscription-details # View subscription info
Subsequences (8)
Multi-branch sequences that trigger based on lead behavior.
instantly background-jobs list # List jobs
instantly background-jobs list --status completed --type import
instantly background-jobs get <id> # Get job details
Email Verification (2)
Verify email addresses before sending.
instantly email-verification verify --email "[email protected]"
instantly email-verification status <email> # Check verification result
Account-Campaign Mappings (1)
instantly account-mappings get <email> # See which campaigns use an account
Audit Logs (1)
instantly audit-logs list # List workspace activity
instantly audit-logs list --start-date 2025-01-01 --end-date 2025-03-01
API Keys (3)
instantly api-keys list # List API keys
instantly api-keys create --name "CI/CD Key" --scopes "campaigns:read,leads:read"
instantly api-keys delete <id> # Revoke an API key
Inbox Placement (6)
Test where your emails land — inbox, spam, or promotions.
instantly inbox-placement list # List placement tests
instantly inbox-placement get <id> # Get test results
instantly inbox-placement create --name "Q2 Test" --type 0 --sending-method 0 --subject "Test" --body "Hello" --emails "[email protected]"
instantly inbox-placement update <id> --name "Updated"
instantly inbox-placement esp-options # List ESP options
instantly inbox-placement delete <id> # Delete test
Inbox Placement Analytics (5)
Deep-dive into deliverability data.
instantly inbox-placement-analytics list # List analytics records
instantly inbox-placement-analytics get <id> # Get analytics detail
instantly inbox-placement-analytics stats-by-test --test-ids "id1,id2"
instantly inbox-placement-analytics stats-by-date --test-id <id>
instantly inbox-placement-analytics insights --test-id <id> # Deliverability insights
Inbox Placement Reports (2)
instantly inbox-placement-reports list # List reports
instantly inbox-placement-reports get <id> # Get report details
CRM Actions (2)
instantly crm-actions list-phone-numbers # List phone numbers
instantly crm-actions delete-phone-number <id> # Delete phone number
DFY Orders (7)
Manage Done-For-You email account orders.
instantly dfy-orders list # List orders
instantly dfy-orders create --items '[...]' # Place an order
instantly dfy-orders similar-domains --domain "example.com" # Find similar domains
instantly dfy-orders check-domains --domains "a.com,b.com" # Check domain availability
instantly dfy-orders pre-warmed # List pre-warmed domains
instantly dfy-orders list-accounts # List DFY accounts
instantly dfy-orders cancel --account-ids "id1,id2" # Cancel accounts
Custom Prompt Templates (5)
Manage AI prompt templates for personalized outreach.
instantly custom-prompt-templates list # List templates
instantly custom-prompt-templates get <id> # Get template
instantly custom-prompt-templates create --name "Opener" --prompt "Write an opener..."
instantly custom-prompt-templates update <id> --name "Updated"
instantly custom-prompt-templates delete <id> # Delete template
Sales Flow (5)
Manage automated sales workflows.
instantly sales-flow list # List sales flows
instantly sales-flow get <id> # Get flow details
instantly sales-flow create --name "Inbound Flow" # Create flow
instantly sales-flow update <id> --name "Updated" # Update flow
instantly sales-flow delete <id> # Delete flow
Email Templates (5)
Manage reusable email templates.
instantly email-templates list # List templates
instantly email-templates get <id> # Get template
instantly email-templates create --name "Welcome" --subject "Hello" --body "..."
instantly email-templates update <id> --name "Updated"
instantly email-templates delete <id> # Delete template
OAuth (connect email accounts)
Connect Google Workspace and Microsoft 365 accounts without SMTP credentials.
instantly oauth connect google # Opens browser for Google OAuth
instantly oauth connect microsoft # Opens browser for Microsoft OAuth
instantly oauth status <session-id> # Check connection status
MCP Server
The CLI doubles as an MCP (Model Context Protocol) server, giving AI assistants direct access to all 156 Instantly tools as native function calls.
instantly mcp
What this means
When you configure instantly mcp as an MCP server in Claude, Cursor, VS Code, or Windsurf, your AI assistant can:
Create and launch campaigns mid-conversation
Look up lead data and analytics on demand
Reply to emails, manage accounts, and run enrichment
Automate multi-step outbound workflows end-to-end
Every CommandDefinition in the codebase powers both a CLI subcommand and an MCP tool — one source of truth, two interfaces.
Configuration
Add to your MCP settings (Claude Desktop, Cursor, VS Code, Windsurf):
Every MCP tool description says pass profile for agency. Mutating tools require profile + workspace_id matching the bound pair. Use INSTANTLY_PROFILE for a single-profile agent process. Call status first. There is no “run across all profiles” tool.
# How many unread replies?
instantly email unread-count
# Fetch unread emails for a campaign
instantly email list --campaign-id "$CAMPAIGN" --is-read false
# Reply to a lead
instantly email reply \
--reply-to-uuid "<email-uuid>" \
--eaccount "[email protected]" \
--subject "Re: Quick question" \
--body-text "Thanks for your interest! Let's schedule a call."
# Mark thread as read
instantly email mark-read "<thread-id>"
Health-check your sending infrastructure
# List all accounts with their status
instantly accounts list
# Run DNS, SMTP, and IMAP diagnostics
instantly accounts test-vitals "<account-id>"
# Enable warmup on cold accounts
instantly accounts warmup-enable --account-ids "id1,id2,id3"
# Check warmup analytics
instantly analytics warmup --emails "[email protected],[email protected]"
git clone https://github.com/bcharleson/instantly-cli.git
cd instantly-cli
npm install
npm run dev -- campaigns list # Run in dev mode (tsx)
npm run build # Build with tsup
npm test # Run tests (138 tests, vitest)
npm run typecheck # Type-check (tsc --noEmit)
Tech Stack
TypeScript (ESM, Node 20+)
Commander.js — CLI framework
Zod — schema validation (shared between CLI and MCP)
@modelcontextprotocol/sdk — MCP server
tsup — bundler
vitest — test runner
License
MIT
I
Instantly Cli
bcharleson·38 ดาว·
CLI and MCP server for the Instantly.ai cold email platform