Instantly.ai Skill

Manage cold email outreach via the Instantly.ai API V2. This skill provides full access to campaigns, leads, email accounts, analytics, and more.

Setup

Get your API key from Instantly Dashboard → Settings → API Key
Set the environment variable:
```
export INSTANTLY_API_KEY="your-api-key-here"
```
Or add to your shell profile / Clawdbot config.

Note: API access requires Hypergrowth plan or above.

Usage

Use the CLI script for all operations:

# List campaigns
<skill>/scripts/instantly.py campaigns list

# Get campaign details
<skill>/scripts/instantly.py campaigns get <campaign_id>

# List leads in a campaign
<skill>/scripts/instantly.py leads list --campaign <campaign_id>

# Add a lead
<skill>/scripts/instantly.py leads create --campaign <campaign_id> --email "john@example.com" --first-name "John"

# List email accounts
<skill>/scripts/instantly.py accounts list

# Get analytics
<skill>/scripts/instantly.py analytics summary --campaign <campaign_id>

Commands Reference

Campaigns

| Command | Description | |---------|-------------| | campaigns list | List all campaigns | | campaigns get <id> | Get campaign details | | campaigns create --name "..." --schedule "..." | Create new campaign | | campaigns update <id> --name "..." | Update campaign | | campaigns launch <id> | Launch/activate campaign | | campaigns pause <id> | Pause campaign |

Leads

| Command | Description | |---------|-------------| | leads list --campaign <id> | List leads in campaign | | leads get <id> | Get lead details | | leads create --campaign <id> --email "..." | Add lead to campaign | | leads update <id> --status <n> | Update lead status | | leads delete <id> | Delete lead | | leads bulk-add --campaign <id> --file <csv> | Bulk add leads from CSV |

Lead Status Codes:

1 = Active
2 = Paused
3 = Completed
-1 = Bounced
-2 = Unsubscribed
-3 = Skipped

Interest Status:

1 = Interested
2 = Meeting Booked
3 = Meeting Completed
4 = Won
0 = Out of Office
-1 = Not Interested
-2 = Wrong Person
-3 = Lost
-4 = No Show

Accounts (Email Sending Accounts)

| Command | Description | |---------|-------------| | accounts list | List all email accounts | | accounts get <email> | Get account details | | accounts create --email "..." --imap-host "..." ... | Add email account | | accounts update <email> --daily-limit 50 | Update account settings | | accounts warmup-start <email> | Start warmup | | accounts warmup-pause <email> | Pause warmup |

Account Status:

1 = Active
2 = Paused
-1 = Connection Error
-2 = Soft Bounce Error
-3 = Sending Error

Analytics

| Command | Description | |---------|-------------| | analytics summary --campaign <id> | Campaign summary stats | | analytics daily --campaign <id> --days 7 | Daily breakdown |

Lead Lists

| Command | Description | |---------|-------------| | lists list | List all lead lists | | lists get <id> | Get list details | | lists create --name "..." | Create lead list |

Emails (Unibox)

| Command | Description | |---------|-------------| | emails list --campaign <id> | List emails in campaign | | emails get <id> | Get email details | | emails reply <id> --message "..." | Send reply |

Webhooks

| Command | Description | |---------|-------------| | webhooks list | List webhooks | | webhooks create --url "..." --event "..." | Create webhook | | webhooks delete <id> | Delete webhook |

Webhook Events:

lead_interested
email_sent
email_opened
email_clicked
email_replied
lead_unsubscribed

Common Workflows

Check Campaign Health

# See all campaigns with status
<skill>/scripts/instantly.py campaigns list

# Get detailed analytics for underperforming campaign
<skill>/scripts/instantly.py analytics summary --campaign <id>

# Check account health
<skill>/scripts/instantly.py accounts list

Add Leads to Running Campaign

# Single lead
<skill>/scripts/instantly.py leads create \
  --campaign <campaign_id> \
  --email "prospect@company.com" \
  --first-name "Jane" \
  --last-name "Doe" \
  --company "ACME Inc"

# Bulk from CSV (email,first_name,last_name,company_name columns)
<skill>/scripts/instantly.py leads bulk-add \
  --campaign <campaign_id> \
  --file /path/to/leads.csv

Monitor Replies

# List recent replies
<skill>/scripts/instantly.py emails list --campaign <id> --type reply

# Get conversation thread
<skill>/scripts/instantly.py emails get <email_id>

Output Formats

All commands support --format option:

table (default) - Human-readable table
json - Full JSON response
csv - CSV for spreadsheets

Example:

<skill>/scripts/instantly.py leads list --campaign <id> --format csv > leads.csv

Error Handling

The script returns standard exit codes:

0 = Success
1 = API error (check message)
2 = Invalid arguments

API errors include the Instantly error message in stderr.

Rate Limits

Instantly API has rate limits. The script handles 429 responses with automatic retry and exponential backoff.

API Reference

Full API docs: https://developer.instantly.ai/api/v2

Base URL: https://api.instantly.ai/api/v2/ Authentication: Bearer token in Authorization header