--- name: instantly description: Instantly.ai cold email outreach API - manage campaigns, leads, accounts, and analytics. Use for cold email automation, lead management, campaign creation\/monitoring, and email account warmup. metadata: {"clawdbot": {"emoji": "📧", "requires": {"env": ["INSTANTLY_API_KEY"]}, "primaryEnv": "INSTANTLY_API_KEY"}} --- # 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: ```bash 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: ```bash # List campaigns \/scripts\/instantly.py campaigns list # Get campaign details \/scripts\/instantly.py campaigns get # List leads in a campaign \/scripts\/instantly.py leads list --campaign # Add a lead \/scripts\/instantly.py leads create --campaign --email "john@example.com" --first-name "John" # List email accounts \/scripts\/instantly.py accounts list # Get analytics \/scripts\/instantly.py analytics summary --campaign ``` ## Commands Reference ### Campaigns | Command | Description | |---------|-------------| | `campaigns list` | List all campaigns | | `campaigns get ` | Get campaign details | | `campaigns create --name "..." --schedule "..."` | Create new campaign | | `campaigns update --name "..."` | Update campaign | | `campaigns launch ` | Launch\/activate campaign | | `campaigns pause ` | Pause campaign | ### Leads | Command | Description | |---------|-------------| | `leads list --campaign ` | List leads in campaign | | `leads get ` | Get lead details | | `leads create --campaign --email "..."` | Add lead to campaign | | `leads update --status ` | Update lead status | | `leads delete ` | Delete lead | | `leads bulk-add --campaign --file ` | 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 ` | Get account details | | `accounts create --email "..." --imap-host "..." ...` | Add email account | | `accounts update --daily-limit 50` | Update account settings | | `accounts warmup-start ` | Start warmup | | `accounts warmup-pause ` | Pause warmup | **Account Status:** - 1 = Active - 2 = Paused - -1 = Connection Error - -2 = Soft Bounce Error - -3 = Sending Error ### Analytics | Command | Description | |---------|-------------| | `analytics summary --campaign ` | Campaign summary stats | | `analytics daily --campaign --days 7` | Daily breakdown | ### Lead Lists | Command | Description | |---------|-------------| | `lists list` | List all lead lists | | `lists get ` | Get list details | | `lists create --name "..."` | Create lead list | ### Emails (Unibox) | Command | Description | |---------|-------------| | `emails list --campaign ` | List emails in campaign | | `emails get ` | Get email details | | `emails reply --message "..."` | Send reply | ### Webhooks | Command | Description | |---------|-------------| | `webhooks list` | List webhooks | | `webhooks create --url "..." --event "..."` | Create webhook | | `webhooks delete ` | Delete webhook | **Webhook Events:** - `lead_interested` - `email_sent` - `email_opened` - `email_clicked` - `email_replied` - `lead_unsubscribed` ## Common Workflows ### Check Campaign Health ```bash # See all campaigns with status \/scripts\/instantly.py campaigns list # Get detailed analytics for underperforming campaign \/scripts\/instantly.py analytics summary --campaign # Check account health \/scripts\/instantly.py accounts list ``` ### Add Leads to Running Campaign ```bash # Single lead \/scripts\/instantly.py leads create \ --campaign \ --email "prospect@company.com" \ --first-name "Jane" \ --last-name "Doe" \ --company "ACME Inc" # Bulk from CSV (email,first_name,last_name,company_name columns) \/scripts\/instantly.py leads bulk-add \ --campaign \ --file \/path\/to\/leads.csv ``` ### Monitor Replies ```bash # List recent replies \/scripts\/instantly.py emails list --campaign --type reply # Get conversation thread \/scripts\/instantly.py emails get ``` ## Output Formats All commands support `--format` option: - `table` (default) - Human-readable table - `json` - Full JSON response - `csv` - CSV for spreadsheets Example: ```bash \/scripts\/instantly.py leads list --campaign --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