This file helps AI agents (GPT, Claude, Gemini, open-source models, etc.) install, authenticate, and use the Instantly CLI to manage cold email campaigns, leads, email accounts, and more via the Instantly.ai platform.
# Install globally
npm install -g instantly-cli
# Authenticate (non-interactive — best for agents)
export INSTANTLY_API_KEY="your-api-key-here"
# Verify it works
instantly campaigns listRequirements: Node.js 18+
Set your API key via environment variable — no interactive login needed:
export INSTANTLY_API_KEY="your-api-key-here"Or pass it per-command:
instantly campaigns list --api-key "your-api-key-here"API keys are generated from: https://app.instantly.ai/app/settings/integrations
All commands output JSON to stdout by default — ready for parsing:
# Default: compact JSON
instantly campaigns list
# → [{"id":"abc-123","name":"Q1 Outreach","status":"active",...}]
# Pretty-printed JSON
instantly campaigns list --output pretty
# Select specific fields
instantly campaigns list --fields id,name,status
# Suppress output (exit code only)
instantly campaigns list --quietExit codes: 0 = success, 1 = error. Errors go to stderr as JSON:
{"error":"Missing required option(s): --host","code":"UNKNOWN_ERROR"}# List all command groups
instantly --help
# List subcommands in a group
instantly campaigns --help
# Get help for a specific subcommand (shows required options + examples)
instantly leads bulk-add --helpIf you use a wrong subcommand, the CLI tells you what's available:
error: unknown command 'get' for 'workspace-billing'
Available commands: plan-details, subscription-details
Manage outbound email campaigns.
list List campaigns (paginated)
get Get a campaign by ID
create Create a new campaign
update Update a campaign
delete Delete a campaign
activate Start sending a campaign
pause Pause a campaign
duplicate Clone a campaign
search-by-contact Find campaigns containing a specific lead email
count-launched Count active/launched campaigns
sending-status Diagnose sending issues for a campaign
bulk-activate Activate multiple campaigns at once
bulk-pause Pause multiple campaigns at once
Manage prospects inside campaigns.
list List leads (paginated)
get Get a lead by email
create Create a single lead
update Update a lead
delete Delete a lead
bulk-add Add up to 1,000 leads at once
bulk-delete Delete leads in bulk
bulk-assign Assign leads to sending accounts
move Move leads between campaigns
merge Merge duplicate leads
update-interest-status Set lead interest level
remove-from-subsequence Remove lead from a subsequence
Manage sending email accounts.
list List email accounts
get Get account by email address
create Create a new email account
update Update an email account
delete Delete an email account
warmup-enable Enable warmup for an account
warmup-disable Disable warmup for an account
test-vitals Run DNS/SMTP/IMAP health checks
pause Pause an account
resume Resume a paused account
mark-fixed Mark a flagged account as fixed
ctd-status Check custom tracking domain status (requires --host)
Read and reply to emails in the unified inbox.
list List emails (filter by --campaign-id, --email-type, --is-read, --eaccount)
get Get a specific email
update Update email metadata
delete Delete an email
reply Reply to an email thread (use --to to validate recipient)
forward Forward an email (use --expect-from to validate sender)
mark-read Mark an email thread as read
unread-count Count unread emails
Measure campaign and account performance.
campaign Per-campaign stats (sent, opens, clicks, replies, bounces)
campaign-overview Aggregated stats across all campaigns
daily-campaign Day-by-day breakdown for a campaign
campaign-steps Per-step breakdown in a sequence
daily-account Daily sending volume per account
warmup Warmup performance stats (requires --emails)
Subscribe to real-time events.
list List webhooks
get Get a webhook by ID
create Create a webhook
update Update a webhook
delete Delete a webhook
test Fire a test payload
event-types List available event type names
resume Re-enable a suspended webhook
Manage reusable lead lists.
list List lead lists
get Get a lead list by ID
create Create a lead list
update Update a lead list
delete Delete a lead list
verification-stats Email verification status breakdown
Enrich lead data with company/contact intelligence.
enrich Enrich leads
count Count enrichable leads
get Get enrichment by ID
run Run enrichment
create Create enrichment config
update-settings Update enrichment settings
ai AI-powered enrichment
ai-progress Check AI enrichment progress
history View enrichment history
preview Preview matching leads
Prevent sending to specific domains or emails.
list List blocklist entries
get Get a blocklist entry
create Add to blocklist
update Update a blocklist entry
delete Remove from blocklist
Organize campaigns and leads with tags.
list List tags
get Get a tag by ID
create Create a tag
update Update a tag
delete Delete a tag
toggle Toggle a tag on/off for a resource
AI-powered labeling for reply intent.
list List labels
get Get a label by ID
create Create a label
update Update a label
delete Delete a label
test-ai Test AI classifier against a sample reply
get Get workspace info
update Update workspace settings
whitelabel-create Create a whitelabel domain
whitelabel-get Get whitelabel domain info
whitelabel-delete Delete whitelabel domain
change-owner Transfer workspace ownership
Multi-branch sequences triggered by lead behavior.
list List subsequences
create Create a subsequence
update Update a subsequence
delete Delete a subsequence
duplicate Clone a subsequence
pause Pause a subsequence
resume Resume a subsequence
sending-status Check if subsequence is actively sending
list List async bulk operations and their status
get Get job details by ID
verify Verify a single email address
status Get result of a previous verification
get See which sending accounts are assigned to a campaign
list Retrieve workspace activity log
list List workspace members
get Get a member by ID
create Invite a member
update Update member permissions
delete Remove a member
list List API keys
create Create an API key
delete Delete an API key
Test where emails land (inbox, spam, promotions).
list List placement tests
get Get a test by ID
create Create a placement test
update Update a test
delete Delete a test
esp-options List ESP options
Inspect webhook delivery history.
list List webhook events
get Get a webhook event by ID
summary Event summary
summary-by-date Event summary by date
list List group members
get Get a group member
create Add a group member
delete Remove a group member
get-admin Get group admin
list List tag-to-resource mappings
plan-details Get workspace plan details
subscription-details Get subscription details
list-phone-numbers List phone numbers
delete-phone-number Delete a phone number
Manage Done-For-You email account orders.
create Create a DFY order
list List DFY orders
similar-domains Find similar domains
check-domains Check domain availability
pre-warmed List pre-warmed accounts
list-accounts List accounts from orders
cancel Cancel an order
list List analytics
get Get analytics by ID
stats-by-test Stats grouped by test
stats-by-date Stats grouped by date
insights Deliverability insights
list List reports (requires --test-id)
get Get a report by ID
list List prompt templates
get Get a template by ID
create Create a template
update Update a template
delete Delete a template
list List sales flows
get Get a flow by ID
create Create a flow
update Update a flow
delete Delete a flow
list List email templates
get Get a template by ID
create Create a template
update Update a template
delete Delete a template
# 1. Create the campaign
instantly campaigns create --name "Q1 Outreach" --schedule '{"timezone":"America/New_York"}'
# 2. Add leads to it
instantly leads bulk-add --campaign-id "<campaign-id>" --leads '[{"email":"lead@example.com","first_name":"Jane"}]'
# 3. Start sending
instantly campaigns activate --id "<campaign-id>"# Check unread count
instantly email unread-count
# Fetch unread emails
instantly email list --is-read false
# Fetch only replies (excludes campaign sends and manual emails)
instantly email list --email-type reply
# Replies for a specific campaign
instantly email list --email-type reply --campaign-id "<id>"
# Reply to a thread (--to validates recipient before sending)
instantly email reply --reply-to-uuid "<email-id>" --to "lead@example.com" \
--eaccount "me@domain.com" --subject "Re: Hello" --body-text "Thanks for your interest!"# Search across all leads
instantly leads list --search "lead@example.com"
# Search within a specific campaign
instantly leads list --campaign-id "<id>" --search "lead@example.com"
# Find which campaigns contain a lead
instantly campaigns search-by-contact "lead@example.com"# Activate multiple campaigns
instantly campaigns bulk-activate --ids "id1,id2,id3"
# Pause multiple campaigns
instantly campaigns bulk-pause --ids "id1,id2,id3"
# Also works with JSON arrays
instantly campaigns bulk-activate --ids '["id1","id2","id3"]'# List all accounts
instantly accounts list
# Test a specific account
instantly accounts test-vitals --email "sender@domain.com"
# Enable warmup on a cold account
instantly accounts warmup-enable --email "sender@domain.com"# High-level overview
instantly analytics campaign-overview
# Per-campaign breakdown
instantly analytics campaign --campaign-id "<id>"
# Day-by-day trends
instantly analytics daily-campaign --campaign-id "<id>"# See available event types
instantly webhooks event-types
# Create a webhook
instantly webhooks create --event-type "email_sent" --webhook-url "https://your-endpoint.com/hook"
# Test it
instantly webhooks test --id "<webhook-id>"The CLI manages webhooks but doesn't run an HTTP listener. Here are two approaches depending on your capabilities:
Approach 1: Polling (recommended for most agents)
No server required — just poll on an interval:
# Check for unread replies every 60 seconds
instantly email unread-count
# → {"count":3}
# If count > 0, fetch the new emails
instantly email list --is-read false --limit 20
# Process each reply, then mark as read
instantly email mark-read <thread-id>
# Or check lead interest status changes
instantly leads list --campaign-id "<id>" --interest-status "positive" --limit 50Approach 2: Webhooks (real-time, requires a listener endpoint)
If you can receive HTTP POST requests (e.g., you have a server, tunnel, or serverless function):
# Step 1: See all available event types
instantly webhooks event-types
# Common events: reply_received, email_sent, lead_interested,
# email_opened, link_clicked, email_bounced, email_unsubscribed
# Step 2: Register a webhook for replies
instantly webhooks create \
--event-type "reply_received" \
--webhook-url "https://your-agent-endpoint.com/instantly-hook"
# Step 3: Verify it works
instantly webhooks test --id "<webhook-id>"
# Step 4: Check delivery history if events seem missing
instantly webhook-events list --webhook-id "<webhook-id>"
instantly webhook-events summary --webhook-id "<webhook-id>"When Instantly sends a POST to your endpoint, the payload includes the event type and relevant data (lead email, campaign ID, thread ID, etc.). Your agent can then react by running more CLI commands.
Approach 3: Polling webhook event history (hybrid)
If you registered webhooks elsewhere but want to audit delivery:
# Check what events were fired recently
instantly webhook-events list --webhook-id "<id>" --limit 20
# Get summary counts by event type
instantly webhook-events summary --webhook-id "<id>"
# Daily breakdown
instantly webhook-events summary-by-date --webhook-id "<id>"List commands support cursor-based pagination:
# First page
instantly campaigns list --limit 10
# Next page (use the last item's ID as cursor)
instantly campaigns list --limit 10 --starting-after "<last-id>"The CLI also includes a built-in MCP server exposing all 156 commands as tools:
# Start the MCP server
instantly mcpMCP config for your AI assistant:
{
"mcpServers": {
"instantly": {
"command": "npx",
"args": ["instantly-cli", "mcp"],
"env": { "INSTANTLY_API_KEY": "your-key" }
}
}
}Instantly renders email bodies as HTML. Plain text with \n newlines will render as a single unbroken block in recipients' email clients.
The CLI auto-converts plain text to HTML in email reply, email forward, and leads bulk-add (for custom_variables with body in the key name). But if you're building bodies yourself, follow these rules:
- Each paragraph →
<div>paragraph text</div> - Blank line →
<div><br /></div> - Never use raw
\nnewlines in email body strings - Template variables
{{first_name}}and spin syntax{{RANDOM|a|b}}pass through untouched
# The CLI auto-converts this plain text in --body-text:
instantly email reply --reply-to-uuid <id> --eaccount "me@domain.com" \
--subject "Re: Hello" --body-text "Hi Sarah,
Worth it?
Mark"
# → Automatically generates HTML: <div>Hi Sarah,</div><div><br /></div><div>Worth it?</div>...
# For leads bulk-add, plain text in body custom_variables is auto-converted:
instantly leads bulk-add --campaign-id <id> --leads '[{
"email": "lead@example.com",
"custom_variables": {
"email_1_body": "Hi {{first_name}},\n\nWorth a quick chat?\n\nMark"
}
}]'
# → email_1_body auto-converted to HTML for proper rendering- Always use
--helpon a group before guessing subcommand names - Parse JSON output directly — it's the default format
- Check exit codes — 0 means success, 1 means error
- Required options are enforced with clear error messages before API calls
- Rate limits are handled automatically (100 req/10s, 600 req/min) with retry
- Use
--fieldsto reduce output size when you only need specific data - Use
--quietwhen you only care about success/failure - Use
--prettyfor human-readable JSON (shorthand for--output pretty) - Use
--email-type replyto filter email list to only replies (excludes campaign sends) - Use
leads list --searchto find a lead by email — no need to know the lead ID - Use
campaigns search-by-contactto find which campaigns a lead is in — accepts email as positional arg - Use
--toon email reply and--expect-fromon email forward to validate recipients before sending - Use
bulk-activate/bulk-pauseto manage multiple campaigns at once