instantly-cli
Advanced tools
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
Instantly.ai is the leading cold email and outbound sales platform. It handles everything needed to run high-volume outbound at scale:
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.
npm install -g instantly-cli
npx instantly-cli campaigns list
git clone https://github.com/bcharleson/instantly-cli.git
cd instantly-cli
npm install && npm run build
npm link
Three ways to authenticate, checked in this order:
--api-key flag — pass on any command: instantly campaigns list --api-key <key>export INSTANTLY_API_KEY=your-keyinstantly login to save your key to ~/.instantly/config.jsonGet your API key from app.instantly.ai/app/settings/integrations.
Set the environment variable — no interactive prompts, no config files:
export INSTANTLY_API_KEY=your-key
instantly campaigns list
instantly login
# Prompts for your API key, validates it, saves to ~/.instantly/config.json
# 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":"cto@startup.com","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
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
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 "a@b.com" # 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
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 "a@b.com" --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":"a@b.com"}]' # 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
Connect and manage sending accounts — SMTP/IMAP, Google, or Microsoft.
instantly accounts list # List all sending accounts
instantly accounts get <id> # Get account details
instantly accounts create --email "..." --smtp-host "..." # Connect SMTP/IMAP account
instantly accounts update <email> --daily-limit 50 # Update account settings
instantly accounts warmup-enable --account-ids "id1,id2" # Start warmup
instantly accounts warmup-disable --account-ids "id1,id2" # Stop warmup
instantly accounts test-vitals <id> # Run DNS/SMTP/IMAP health checks
instantly accounts pause <email> # Pause an account
instantly accounts resume <email> # Resume a paused account
instantly accounts mark-fixed <email> # Clear error flags
instantly accounts ctd-status # Check click-to-deliver status
instantly accounts delete <id> # Remove account
Read and respond to emails across all sending accounts.
instantly email list # List all emails
instantly email list --campaign-id <id> --is-read false # Unread replies for a campaign
instantly email get <id> # Get email content
instantly email reply --reply-to-uuid <id> --eaccount "user@domain.com" --subject "Re: Hello" --body-text "Thanks!"
instantly email forward --forward-uuid <id> --eaccount "user@domain.com" --to "team@co.com"
instantly email update <id> --is-read true # Update email properties
instantly email delete <id> # Delete an email
instantly email mark-read <thread-id> # Mark entire thread as read
instantly email unread-count # Count unread emails
Measure campaign performance at every level.
instantly analytics campaign # Stats for all campaigns
instantly analytics campaign --id <id> # Stats for one campaign
instantly analytics campaign-overview # Aggregated overview
instantly analytics daily-campaign --campaign-id <id> # Day-by-day breakdown
instantly analytics campaign-steps --campaign-id <id> # Per-step sequence analytics
instantly analytics daily-account # Daily sending volume per account
instantly analytics warmup --emails "user@domain.com" # Warmup performance
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
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
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
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
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 "spam@domain.com" # Block an email/domain
instantly blocklist update <id> --value "new@domain.com" # Update entry
instantly blocklist delete <id> # Remove from blocklist
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
instantly custom-tag-mappings list # List tag-to-resource mappings
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
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 "new@co.com" # Transfer ownership
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 "user@co.com" --role admin
instantly workspace-members update <id> --role member # Change role
instantly workspace-members delete <id> # Remove member
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
instantly workspace-billing plan-details # View current plan
instantly workspace-billing subscription-details # View subscription info
Multi-branch sequences that trigger based on lead behavior.
instantly subsequences list --campaign-id <id> # List subsequences
instantly subsequences create --campaign-id <id> --name "Follow-up" --conditions '{}' --schedule '{}' --sequences '[]'
instantly subsequences update <id> --name "New Name" # Update subsequence
instantly subsequences duplicate <id> --campaign-id <target-id> --name "Copy"
instantly subsequences pause <id> # Pause sending
instantly subsequences resume <id> # Resume sending
instantly subsequences sending-status <id> # Check sending status
instantly subsequences delete <id> # Delete subsequence
Monitor async bulk operations.
instantly background-jobs list # List jobs
instantly background-jobs list --status completed --type import
instantly background-jobs get <id> # Get job details
Verify email addresses before sending.
instantly email-verification verify --email "john@example.com"
instantly email-verification status <email> # Check verification result
instantly account-mappings get <email> # See which campaigns use an account
instantly audit-logs list # List workspace activity
instantly audit-logs list --start-date 2025-01-01 --end-date 2025-03-01
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
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 "seed@test.com"
instantly inbox-placement update <id> --name "Updated"
instantly inbox-placement esp-options # List ESP options
instantly inbox-placement delete <id> # Delete test
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
instantly inbox-placement-reports list # List reports
instantly inbox-placement-reports get <id> # Get report details
instantly crm-actions list-phone-numbers # List phone numbers
instantly crm-actions delete-phone-number <id> # Delete phone number
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
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
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
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
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
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
When you configure instantly mcp as an MCP server in Claude, Cursor, VS Code, or Windsurf, your AI assistant can:
Every CommandDefinition in the codebase powers both a CLI subcommand and an MCP tool — one source of truth, two interfaces.
Add to your MCP settings (Claude Desktop, Cursor, VS Code, Windsurf):
{
"mcpServers": {
"instantly": {
"command": "npx",
"args": ["instantly-cli", "mcp"],
"env": {
"INSTANTLY_API_KEY": "your-api-key"
}
}
}
}
This registers 156 tools across 31 groups:
| Group | Tools | Examples |
|---|---|---|
| Campaigns | 11 | campaigns_list, campaigns_activate, campaigns_duplicate |
| Leads | 12 | leads_list, leads_create, leads_bulk_add, leads_merge |
| Accounts | 12 | accounts_list, accounts_warmup_enable, accounts_pause |
| 8 | email_list, email_reply, email_forward, email_update | |
| Analytics | 6 | analytics_campaign, analytics_warmup, analytics_daily_campaign |
| Webhooks | 8 | webhooks_list, webhooks_create, webhooks_update |
| Webhook Events | 4 | webhook_events_list, webhook_events_summary |
| Lead Lists | 6 | lead_lists_list, lead_lists_create, lead_lists_verification_stats |
| Enrichment | 10 | enrichment_enrich, enrichment_ai, enrichment_preview |
| Blocklist | 5 | blocklist_list, blocklist_create, blocklist_update |
| Custom Tags | 6 | custom_tags_list, custom_tags_create, custom_tags_toggle |
| Custom Tag Mappings | 1 | custom_tag_mappings_list |
| Lead Labels | 6 | lead_labels_list, lead_labels_create, lead_labels_test_ai |
| Workspace | 6 | workspace_get, workspace_update, workspace_whitelabel_create |
| Workspace Members | 5 | workspace_members_list, workspace_members_create |
| Workspace Group Members | 5 | workspace_group_members_list, workspace_group_members_create |
| Workspace Billing | 2 | workspace_billing_plan_details, workspace_billing_subscription_details |
| Subsequences | 8 | subsequences_list, subsequences_create, subsequences_pause |
| Background Jobs | 2 | background_jobs_list, background_jobs_get |
| Email Verification | 2 | email_verification_verify, email_verification_status |
| Account Mappings | 1 | account_mappings_get |
| Audit Logs | 1 | audit_logs_list |
| API Keys | 3 | api_keys_create, api_keys_list, api_keys_delete |
| Inbox Placement | 6 | inbox_placement_list, inbox_placement_create |
| Inbox Placement Analytics | 5 | inbox_placement_analytics_list, inbox_placement_analytics_insights |
| Inbox Placement Reports | 2 | inbox_placement_reports_list, inbox_placement_reports_get |
| CRM Actions | 2 | crm_actions_list_phone_numbers, crm_actions_delete_phone_number |
| DFY Orders | 7 | dfy_orders_list, dfy_orders_create, dfy_orders_cancel |
| Custom Prompt Templates | 5 | custom_prompt_templates_list, custom_prompt_templates_create |
| Sales Flow | 5 | sales_flow_list, sales_flow_create, sales_flow_delete |
| Email Templates | 5 | email_templates_list, email_templates_create |
export INSTANTLY_API_KEY=your-key
# Create the campaign
CAMPAIGN=$(instantly campaigns create --name "Q2 SaaS Outreach" | jq -r '.id')
# Import leads
instantly leads bulk-add --campaign-id "$CAMPAIGN" \
--leads '[
{"email":"cto@startup.com","first_name":"Alex","company_name":"Startup Inc"},
{"email":"vp@growth.co","first_name":"Jordan","company_name":"Growth Co"}
]'
# Launch
instantly campaigns activate "$CAMPAIGN"
# Check status
instantly campaigns sending-status "$CAMPAIGN"
# 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 "sender@yourdomain.com" \
--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>"
# 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 "sender1@domain.com,sender2@domain.com"
# Run an inbox placement test
TEST=$(instantly inbox-placement create \
--name "March Deliverability Check" \
--type 0 --sending-method 0 \
--subject "Test email" \
--body "Hello from Instantly" \
--emails "seed@test.com" | jq -r '.id')
# Check results
instantly inbox-placement-analytics insights --test-id "$TEST"
# Daily campaign health report (add to crontab)
0 9 * * * INSTANTLY_API_KEY=your-key instantly analytics campaign-overview >> /var/log/instantly-daily.json
# Alert on unread replies
*/5 * * * * INSTANTLY_API_KEY=your-key instantly email unread-count | jq '.count'
The CLI uses a CommandDefinition pattern where every API endpoint is defined as a single object that powers both the CLI subcommand and the MCP tool:
src/
├── core/
│ ├── client.ts # HTTP client with retry, rate limiting, pagination
│ ├── auth.ts # API key resolution (flag → env → config)
│ ├── output.ts # JSON output formatting
│ └── types.ts # CommandDefinition interface
├── commands/
│ ├── campaigns/ # 11 commands
│ ├── leads/ # 12 commands
│ ├── accounts/ # 12 commands
│ └── ... # 28 more groups
└── mcp/
└── server.ts # MCP server (auto-registers all commands as tools)
Adding a new API endpoint = creating one file. The command is automatically available in both CLI and MCP.
Retry-After headersAuthError, NotFoundError, RateLimitError, ValidationError, ServerErrorgit 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)
MIT
FAQs
CLI and MCP server for the Instantly.ai cold email platform
The npm package instantly-cli receives a total of 73 weekly downloads. As such, instantly-cli popularity was classified as not popular.
We found that instantly-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.