Instantly

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

1. Get your API key from Instantly Dashboard → Settings → API Key
2. 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

Leads

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)

Account Status:

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

Analytics

Lead Lists

Emails (Unibox)

Webhooks

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