{
  "markdown": "# Instantly CLI\n\n**Instantly.ai in your terminal.** Run cold email campaigns, manage leads, monitor deliverability, and automate every outbound motion — from a single command line.\n\n156 commands across 31 API groups. Full coverage of the [Instantly.ai](https://instantly.ai) V2 API. Built for humans, scripts, CI/CD pipelines, and AI agents.\n\n```bash\nnpm install -g instantly-cli\n```\n\n---\n\n## What is Instantly?\n\n[Instantly.ai](https://instantly.ai) is the leading cold email and outbound sales platform. It handles everything needed to run high-volume outbound at scale:\n\n- **Email infrastructure** — connect unlimited sending accounts (Google Workspace, Microsoft 365, SMTP/IMAP), auto-rotate senders, manage warmup\n- **Campaign management** — multi-step email sequences with A/B testing, scheduling, and conditional logic\n- **Lead management** — import, enrich, deduplicate, and track prospects across campaigns\n- **Deliverability** — inbox placement testing, sender reputation monitoring, blocklist management, and warmup analytics\n- **Unified inbox** — read, reply, and forward across all sending accounts from one place\n- **AI features** — AI-powered lead labeling, interest classification, and response handling\n\n## What This CLI Enables\n\nThe 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:\n\n**Campaign operations** — create campaigns, add leads, launch sequences, pause/resume, duplicate, and monitor sending status without opening a browser.\n\n**Lead lifecycle** — import leads in bulk, move them between campaigns, update interest status, merge duplicates, assign to subsequences, and manage labels — all scriptable.\n\n**Account management** — connect sending accounts, enable/disable warmup, test DNS/SMTP/IMAP health, pause underperforming senders, and monitor CTD (click-to-deliver) status.\n\n**Deliverability monitoring** — run inbox placement tests, analyze where emails land (inbox vs. spam vs. promotions), track ESP-level performance, and get actionable insights.\n\n**Analytics & reporting** — pull campaign stats, daily breakdowns, per-step sequence analytics, warmup performance, and account-level sending volumes into any reporting tool.\n\n**Team & workspace admin** — manage workspace members, API keys, billing info, audit logs, and whitelabel domains.\n\n**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.\n\n---\n\n## Install\n\n### npm (recommended)\n\n```bash\nnpm install -g instantly-cli\n```\n\n### npx (zero-install)\n\n```bash\nnpx instantly-cli campaigns list\n```\n\n### From source\n\n```bash\ngit clone https://github.com/bcharleson/instantly-cli.git\ncd instantly-cli\nnpm install && npm run build\nnpm link\n```\n\n---\n\n## Authentication\n\nDefault mode is **one workspace, one key**. Existing single-key users do not need profiles.\n\nResolve order **without** `--profile` / `INSTANTLY_PROFILE`:\n\n1. **`--api-key` flag** — pass on any command: `instantly campaigns list --api-key <key>`\n2. **Environment variable** — `export INSTANTLY_API_KEY=your-key`\n3. **cwd `.env`** — `INSTANTLY_API_KEY` in a local `.env` file\n4. **Stored config** — run `instantly login` to save your key to `~/.instantly/config.json` (mode `0600`)\n\nGet your API key from [app.instantly.ai/app/settings/integrations](https://app.instantly.ai/app/settings/integrations).\n\n### For AI agents and scripts\n\nSet the environment variable — no interactive prompts, no config files:\n\n```bash\nexport INSTANTLY_API_KEY=your-key\ninstantly campaigns list\n```\n\n### Interactive login (default / single-key)\n\n```bash\ninstantly login\n# Prompts for your API key, validates it, stamps api_key + workspace_id + workspace_name onto ~/.instantly/config.json\n```\n\n`npx instantly-cli campaigns list` keeps working with one key. `--profile` is not required for old single-key users.\n\n### Opt-in workspace profiles (agency / agent mode)\n\nProfiles are **opt-in** and live **beside** the default config, never inside it:\n\n`~/.instantly/profiles/<slug>.json` = `{ api_key, workspace_id, workspace_name }` (mode `0600`)\n\nRules, fail-closed:\n\n- One process, one workspace. There is no `--all-profiles` and no comma-separated key list.\n- `instantly login --profile acme` validates the key, GETs the live workspace, and binds that workspace UUID + name. It **does not** write or overwrite `~/.instantly/config.json`.\n- Commands accept `--profile <slug>` and/or `INSTANTLY_PROFILE=<slug>`.\n- When a profile is selected, it wins over a leftover cwd `.env` `INSTANTLY_API_KEY`.\n- Every profiled command re-fetches the live workspace. If `workspace.id` ≠ the bound id, the command aborts.\n- Write commands (campaign activate/pause, leads bulk-add, email reply/forward, and other mutations) also require `--workspace <uuid>` matching the bound id.\n- When `--workspace` is passed on any path (default or profile), the live workspace id must match or the command aborts. Omitted on the default single-key path: no extra flag required.\n\n```bash\n# Bind a client workspace to a named profile (does not touch default login)\ninstantly login --profile acme --api-key \"$ACME_KEY\"\ninstantly login --profile client-a --api-key \"$CLIENT_A_KEY\"\n\n# Read-only: profile is enough\ninstantly --profile acme campaigns list\nINSTANTLY_PROFILE=client-a instantly status\n\n# Writes must confirm the bound workspace UUID\ninstantly --profile acme --workspace 11111111-1111-4111-8111-111111111111 \\\n  campaigns activate 33333333-3333-4333-8333-333333333333\n\n# Inspect / manage profiles (never prints API keys)\ninstantly profile list\ninstantly profile whoami\ninstantly profile remove acme\n```\n\n`instantly status` / `whoami` / `profile list` always print `profile` (slug or `default`), `workspace_id`, `workspace_name`, and `source`. They never print the API key. Confirm this bound pair before campaigns, health, or writes. Agencies should `login --profile <client>` for every key, including the house org.\n\nEvery existing command group (campaigns, leads, accounts, email, analytics, health, webhooks, oauth, …) uses this same resolver. There is no second, profile-only API.\n\nAfter merge, dogfood with fake slugs `client-a` / `client-b` (your real keys stay local):\n\n```bash\ninstantly status                                          # default: profile \"default\" + bound workspace id/name\ninstantly login --profile client-a --api-key \"$CLIENT_A_KEY\"\n# confirm ~/.instantly/config.json is unchanged\ninstantly --profile client-a status                       # prints bound workspace id + name\ninstantly --profile client-a campaigns list\ninstantly --profile client-a health\ninstantly --profile client-a --workspace \"$WRONG_UUID\" campaigns activate \"$CAMPAIGN_ID\"\n# → abort; no mutation\n# two files in ~/.instantly/profiles; never one command looping both\n```\n\n---\n\n## Quick Start\n\n```bash\n# Authenticate\ninstantly login\n\n# List campaigns\ninstantly campaigns list\n\n# Create a campaign and start sending\ninstantly campaigns create --name \"Q2 Outreach\"\ninstantly leads bulk-add --campaign-id <id> --leads '[{\"email\":\"cto@startup.com\",\"first_name\":\"Alex\"}]'\ninstantly campaigns activate <id>\n\n# Check analytics\ninstantly analytics campaign --id <id>\n\n# Read replies\ninstantly email list --campaign-id <id> --is-read false\n\n# Connect a Google sending account via OAuth\ninstantly oauth connect google\n```\n\n---\n\n## Output Formats\n\nEvery command outputs JSON by default — ready for piping to `jq`, parsing in scripts, or feeding to other tools.\n\n```bash\n# Default: compact JSON\ninstantly campaigns list\n\n# Pretty-printed JSON\ninstantly campaigns list --pretty\n\n# Select specific fields\ninstantly campaigns list --fields \"id,name,status\"\n\n# Suppress output (exit code only)\ninstantly campaigns list --quiet\n```\n\n---\n\n## Commands\n\n### Profiles\n\nOpt-in named workspace profiles for agents that must isolate client keys.\n\n```bash\ninstantly login --profile acme --api-key <key>        # Bind key → workspace; does not write config.json\ninstantly profile add acme --api-key <key>            # Same persist path as login --profile\ninstantly profile list                                # Slug + workspace id/name only\ninstantly profile whoami                              # Source + profile + live workspace\ninstantly profile remove acme                         # Deletes the profile file only\n```\n\n### Health\n\nRead-only rollup of existing API data for the active profile or default key: disconnected accounts, bounce totals, warmup status, and campaign sending status.\n\n```bash\ninstantly health\ninstantly --profile acme health\n```\n\n### Campaigns (11)\n\nCreate, manage, and control outbound email campaigns.\n\n```bash\ninstantly campaigns list                              # List all campaigns (paginated)\ninstantly campaigns get <id>                          # Get full campaign details\ninstantly campaigns create --name \"Q2 Outreach\"       # Create a new campaign\ninstantly campaigns update <id> --name \"Q2 Updated\"   # Update campaign settings\ninstantly campaigns activate <id>                     # Start sending\ninstantly campaigns pause <id>                        # Pause sending\ninstantly campaigns duplicate <id>                    # Clone a campaign\ninstantly campaigns search-by-contact --email \"a@b.com\"  # Find campaigns containing a lead\ninstantly campaigns count-launched                    # Count active campaigns\ninstantly campaigns sending-status <id>               # Diagnose why a campaign isn't sending\ninstantly campaigns delete <id>                       # Delete permanently\n```\n\nInstantly delivers HTML. Pass readable copy with real line breaks in each variant body; the CLI converts plain-text newlines to `<br/>`/`<p>`. Do not write a run-on string. Existing HTML is left unchanged. Skipped when text_only.\n\nApplies to `campaigns create` / `update` and `subsequences create` (same Instantly `body` key).\n\ndelay on step N waits before step N+1. First email does not wait. Pass delay_unit (minutes|hours|days; omitted unit is set to days). Instantly uses only `sequences[0]`. A multi-step sequence with delay 0 or missing delay on a non-last step is rejected — the follow-up would send the same day. Last step delay may be 0. `email_gap` is a per-send rate limit, not the step gap. `pre_delay` is subsequence-only.\n\n```bash\n# Preferred: readable copy with real line breaks — CLI converts\ninstantly campaigns create --name \"Plain Body\" --sequences \\\n  '[{\"steps\":[{\"type\":\"email\",\"delay\":3,\"delay_unit\":\"days\",\"variants\":[{\"subject\":\"Hi {{first_name}}\",\"body\":\"Hi {{first_name}},\\n\\nWorth a quick chat?\"}]},{\"type\":\"email\",\"delay\":0,\"delay_unit\":\"days\",\"variants\":[{\"subject\":\"Re: Hi\",\"body\":\"Just bumping this.\"}]}]}]'\n\n# Already tagged HTML is stored as-is (single email: last-step delay may be 0)\ninstantly campaigns create --name \"With Sequences\" --sequences \\\n  '[{\"steps\":[{\"type\":\"email\",\"delay\":0,\"delay_unit\":\"days\",\"variants\":[{\"subject\":\"Hi {{first_name}}\",\"body\":\"<div>Hello</div>\"}]}]}]'\n```\n\n### Leads (12)\n\nImport, manage, and move prospects across campaigns.\n\n```bash\ninstantly leads list --campaign-id <id>               # List leads in a campaign\ninstantly leads get <id>                              # Get lead details\ninstantly leads create --email \"a@b.com\" --campaign-id <id>  # Add a single lead\ninstantly leads update <id> --first-name \"Jane\"       # Update lead data\ninstantly leads bulk-add --campaign-id <id> --leads '[{\"email\":\"a@b.com\"}]'  # Add up to 1,000 leads\ninstantly leads bulk-delete --campaign-id <id> --delete-all  # Remove leads in bulk\ninstantly leads bulk-assign --lead-ids \"id1,id2\" --account-id <id>  # Assign leads to senders\ninstantly leads move --lead-ids \"id1,id2\" --to-campaign-id <id>  # Move between campaigns\ninstantly leads merge --lead-ids \"id1,id2\"            # Merge duplicate leads\ninstantly leads update-interest-status --lead-id <id> --interest-status 1  # Set interest level\ninstantly leads remove-from-subsequence --lead-id <id> --subsequence-id <id>\ninstantly leads delete <id>                           # Delete a lead\n```\n\n### Email Accounts (12)\n\nConnect and manage sending accounts — SMTP/IMAP, Google, or Microsoft.\n\n```bash\ninstantly accounts list                               # List all sending accounts\ninstantly accounts get <id>                           # Get account details\ninstantly accounts create --email \"...\" --smtp-host \"...\"  # Connect SMTP/IMAP account\ninstantly accounts update <email> --daily-limit 50    # Update account settings\ninstantly accounts warmup-enable --account-ids \"id1,id2\"  # Start warmup\ninstantly accounts warmup-disable --account-ids \"id1,id2\"  # Stop warmup\ninstantly accounts test-vitals <id>                   # Run DNS/SMTP/IMAP health checks\ninstantly accounts pause <email>                      # Pause an account\ninstantly accounts resume <email>                     # Resume a paused account\ninstantly accounts mark-fixed <email>                 # Clear error flags\ninstantly accounts ctd-status                         # Check click-to-deliver status\ninstantly accounts delete <id>                        # Remove account\n```\n\n### Email / Unified Inbox (8)\n\nRead and respond to emails across all sending accounts.\n\n```bash\ninstantly email list                                  # List all emails\ninstantly email list --campaign-id <id> --is-read false  # Unread replies for a campaign\ninstantly email get <id>                              # Get email content\ninstantly email reply --reply-to-uuid <id> --eaccount \"user@domain.com\" --subject \"Re: Hello\" --body-text \"Thanks!\"\ninstantly email forward --forward-uuid <id> --eaccount \"user@domain.com\" --to \"team@co.com\"\ninstantly email update <id> --is-read true            # Update email properties\ninstantly email delete <id>                           # Delete an email\ninstantly email mark-read <thread-id>                 # Mark entire thread as read\ninstantly email unread-count                          # Count unread emails\n```\n\n### Analytics (6)\n\nMeasure campaign performance at every level.\n\n```bash\ninstantly analytics campaign                          # Stats for all campaigns\ninstantly analytics campaign --id <id>                # Stats for one campaign\ninstantly analytics campaign-overview                 # Aggregated overview\ninstantly analytics daily-campaign --campaign-id <id> # Day-by-day breakdown\ninstantly analytics campaign-steps --campaign-id <id> # Per-step sequence analytics\ninstantly analytics daily-account                     # Daily sending volume per account\ninstantly analytics warmup --emails \"user@domain.com\" # Warmup performance\n```\n\n### Webhooks (8)\n\nSubscribe to real-time events from your campaigns.\n\n```bash\ninstantly webhooks list                               # List all webhooks\ninstantly webhooks get <id>                           # Get webhook details\ninstantly webhooks create --url \"https://...\" --event-type lead_interested\ninstantly webhooks update <id> --url \"https://...\"    # Update webhook\ninstantly webhooks test <id>                          # Fire a test payload\ninstantly webhooks event-types                        # List available event types\ninstantly webhooks resume <id>                        # Re-enable a suspended webhook\ninstantly webhooks delete <id>                        # Delete webhook\n```\n\n### Webhook Events (4)\n\nInspect webhook delivery history.\n\n```bash\ninstantly webhook-events list                         # List webhook events\ninstantly webhook-events get <id>                     # Get event details\ninstantly webhook-events summary                      # Event delivery summary\ninstantly webhook-events summary-by-date              # Summary grouped by date\n```\n\n### Lead Lists (6)\n\nManage reusable lead lists for imports and enrichment.\n\n```bash\ninstantly lead-lists list                             # List all lead lists\ninstantly lead-lists get <id>                         # Get list details\ninstantly lead-lists create --name \"Q2 Prospects\"     # Create a list\ninstantly lead-lists update <id> --name \"Updated\"     # Rename a list\ninstantly lead-lists verification-stats <id>          # Email verification breakdown\ninstantly lead-lists delete <id>                      # Delete a list\n```\n\n### Enrichment / SuperSearch (10)\n\nEnrich leads with company and contact intelligence.\n\n```bash\ninstantly enrichment enrich --search-filters '{\"job_titles\":[\"CTO\"]}' --limit 100\ninstantly enrichment count --search-filters '{\"industries\":[\"SaaS\"]}'\ninstantly enrichment get <resource-id>                # Get enrichment settings\ninstantly enrichment run --resource-id <id>           # Trigger enrichment\ninstantly enrichment create --name \"Q2\" --search-filters '{}' --enrichment-settings '{}'\ninstantly enrichment update-settings <resource-id> --enrichment-settings '{}'\ninstantly enrichment ai --resource-id <id> --prompt \"Find CTOs in SaaS\"\ninstantly enrichment ai-progress <resource-id>        # Check AI enrichment status\ninstantly enrichment history <resource-id>            # View enrichment history\ninstantly enrichment preview --search-filters '{}'    # Preview matching leads\n```\n\n### Blocklist (5)\n\nPrevent sending to specific domains or email addresses.\n\n```bash\ninstantly blocklist list                              # List blocked entries\ninstantly blocklist get <id>                          # Get entry details\ninstantly blocklist create --value \"spam@domain.com\"  # Block an email/domain\ninstantly blocklist update <id> --value \"new@domain.com\"  # Update entry\ninstantly blocklist delete <id>                       # Remove from blocklist\n```\n\n### Custom Tags (6)\n\nOrganize campaigns, leads, and resources with tags.\n\n```bash\ninstantly custom-tags list                            # List all tags\ninstantly custom-tags get <id>                        # Get tag details\ninstantly custom-tags create --label \"High Priority\"  # Create a tag\ninstantly custom-tags update <id> --label \"Urgent\"    # Rename a tag\ninstantly custom-tags toggle --tag-ids \"t1\" --resource-ids \"r1\" --resource-type 1 --assign\ninstantly custom-tags delete <id>                     # Delete a tag\n```\n\n### Custom Tag Mappings (1)\n\n```bash\ninstantly custom-tag-mappings list                    # List tag-to-resource mappings\n```\n\n### Lead Labels (6)\n\nAI-powered labeling to categorize lead reply intent.\n\n```bash\ninstantly lead-labels list                            # List all labels\ninstantly lead-labels get <id>                        # Get label details\ninstantly lead-labels create --label \"Hot Lead\" --interest-status \"positive\"\ninstantly lead-labels update <id> --label \"Warm Lead\" # Update label\ninstantly lead-labels test-ai --reply-text \"Yes, I'm interested\"  # Test AI classification\ninstantly lead-labels delete <id>                     # Delete label\n```\n\n### Workspace (6)\n\nManage workspace settings and whitelabel configuration.\n\n```bash\ninstantly workspace get                               # Get workspace info\ninstantly workspace update --name \"My Workspace\"      # Update workspace\ninstantly workspace whitelabel-create --domain \"mail.example.com\"\ninstantly workspace whitelabel-get                    # Get whitelabel domain\ninstantly workspace whitelabel-delete                 # Remove whitelabel\ninstantly workspace change-owner --email \"new@co.com\" # Transfer ownership\n```\n\n### Workspace Members (5)\n\nManage team access and roles.\n\n```bash\ninstantly workspace-members list                      # List team members\ninstantly workspace-members get <id>                  # Get member details\ninstantly workspace-members create --email \"user@co.com\" --role admin\ninstantly workspace-members update <id> --role member # Change role\ninstantly workspace-members delete <id>               # Remove member\n```\n\n### Workspace Group Members (5)\n\nManage workspace group membership.\n\n```bash\ninstantly workspace-group-members list                # List group members\ninstantly workspace-group-members get <id>            # Get member details\ninstantly workspace-group-members create --user-id <id> --group-id <id>\ninstantly workspace-group-members get-admin            # Get admin info\ninstantly workspace-group-members delete <id>         # Remove from group\n```\n\n### Workspace Billing (2)\n\n```bash\ninstantly workspace-billing plan-details              # View current plan\ninstantly workspace-billing subscription-details      # View subscription info\n```\n\n### Subsequences (8)\n\nMulti-branch sequences that trigger based on lead behavior.\n\n```bash\ninstantly subsequences list --campaign-id <id>        # List subsequences\ninstantly subsequences create --campaign-id <id> --name \"Follow-up\" --conditions '{}' --schedule '{}' --sequences '[]'\ninstantly subsequences update <id> --name \"New Name\"  # Update subsequence\ninstantly subsequences duplicate <id> --campaign-id <target-id> --name \"Copy\"\ninstantly subsequences pause <id>                     # Pause sending\ninstantly subsequences resume <id>                    # Resume sending\ninstantly subsequences sending-status <id>            # Check sending status\ninstantly subsequences delete <id>                    # Delete subsequence\n```\n\n### Background Jobs (2)\n\nMonitor async bulk operations.\n\n```bash\ninstantly background-jobs list                        # List jobs\ninstantly background-jobs list --status completed --type import\ninstantly background-jobs get <id>                    # Get job details\n```\n\n### Email Verification (2)\n\nVerify email addresses before sending.\n\n```bash\ninstantly email-verification verify --email \"john@example.com\"\ninstantly email-verification status <email>           # Check verification result\n```\n\n### Account-Campaign Mappings (1)\n\n```bash\ninstantly account-mappings get <email>                # See which campaigns use an account\n```\n\n### Audit Logs (1)\n\n```bash\ninstantly audit-logs list                             # List workspace activity\ninstantly audit-logs list --start-date 2025-01-01 --end-date 2025-03-01\n```\n\n### API Keys (3)\n\n```bash\ninstantly api-keys list                               # List API keys\ninstantly api-keys create --name \"CI/CD Key\" --scopes \"campaigns:read,leads:read\"\ninstantly api-keys delete <id>                        # Revoke an API key\n```\n\n### Inbox Placement (6)\n\nTest where your emails land — inbox, spam, or promotions.\n\n```bash\ninstantly inbox-placement list                        # List placement tests\ninstantly inbox-placement get <id>                    # Get test results\ninstantly inbox-placement create --name \"Q2 Test\" --type 0 --sending-method 0 --subject \"Test\" --body \"Hello\" --emails \"seed@test.com\"\ninstantly inbox-placement update <id> --name \"Updated\"\ninstantly inbox-placement esp-options                  # List ESP options\ninstantly inbox-placement delete <id>                 # Delete test\n```\n\n### Inbox Placement Analytics (5)\n\nDeep-dive into deliverability data.\n\n```bash\ninstantly inbox-placement-analytics list              # List analytics records\ninstantly inbox-placement-analytics get <id>          # Get analytics detail\ninstantly inbox-placement-analytics stats-by-test --test-ids \"id1,id2\"\ninstantly inbox-placement-analytics stats-by-date --test-id <id>\ninstantly inbox-placement-analytics insights --test-id <id>  # Deliverability insights\n```\n\n### Inbox Placement Reports (2)\n\n```bash\ninstantly inbox-placement-reports list                # List reports\ninstantly inbox-placement-reports get <id>            # Get report details\n```\n\n### CRM Actions (2)\n\n```bash\ninstantly crm-actions list-phone-numbers             # List phone numbers\ninstantly crm-actions delete-phone-number <id>       # Delete phone number\n```\n\n### DFY Orders (7)\n\nManage Done-For-You email account orders.\n\n```bash\ninstantly dfy-orders list                             # List orders\ninstantly dfy-orders create --items '[...]'           # Place an order\ninstantly dfy-orders similar-domains --domain \"example.com\"  # Find similar domains\ninstantly dfy-orders check-domains --domains \"a.com,b.com\"   # Check domain availability\ninstantly dfy-orders pre-warmed                       # List pre-warmed domains\ninstantly dfy-orders list-accounts                    # List DFY accounts\ninstantly dfy-orders cancel --account-ids \"id1,id2\"   # Cancel accounts\n```\n\n### Custom Prompt Templates (5)\n\nManage AI prompt templates for personalized outreach.\n\n```bash\ninstantly custom-prompt-templates list                # List templates\ninstantly custom-prompt-templates get <id>            # Get template\ninstantly custom-prompt-templates create --name \"Opener\" --prompt \"Write an opener...\"\ninstantly custom-prompt-templates update <id> --name \"Updated\"\ninstantly custom-prompt-templates delete <id>         # Delete template\n```\n\n### Sales Flow (5)\n\nManage automated sales workflows.\n\n```bash\ninstantly sales-flow list                             # List sales flows\ninstantly sales-flow get <id>                         # Get flow details\ninstantly sales-flow create --name \"Inbound Flow\"     # Create flow\ninstantly sales-flow update <id> --name \"Updated\"     # Update flow\ninstantly sales-flow delete <id>                      # Delete flow\n```\n\n### Email Templates (5)\n\nManage reusable email templates.\n\n```bash\ninstantly email-templates list                        # List templates\ninstantly email-templates get <id>                    # Get template\ninstantly email-templates create --name \"Welcome\" --subject \"Hello\" --body \"...\"\ninstantly email-templates update <id> --name \"Updated\"\ninstantly email-templates delete <id>                 # Delete template\n```\n\n### OAuth (connect email accounts)\n\nConnect Google Workspace and Microsoft 365 accounts without SMTP credentials.\n\n```bash\ninstantly oauth connect google                        # Opens browser for Google OAuth\ninstantly oauth connect microsoft                     # Opens browser for Microsoft OAuth\ninstantly oauth status <session-id>                   # Check connection status\n```\n\n---\n\n## MCP Server\n\nThe CLI doubles as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, giving AI assistants direct access to all 156 Instantly tools as native function calls.\n\n```bash\ninstantly mcp\n```\n\n### What this means\n\nWhen you configure `instantly mcp` as an MCP server in Claude, Cursor, VS Code, or Windsurf, your AI assistant can:\n\n- Create and launch campaigns mid-conversation\n- Look up lead data and analytics on demand\n- Reply to emails, manage accounts, and run enrichment\n- Automate multi-step outbound workflows end-to-end\n\nEvery `CommandDefinition` in the codebase powers both a CLI subcommand and an MCP tool — one source of truth, two interfaces.\n\n### Configuration\n\nAdd to your MCP settings (Claude Desktop, Cursor, VS Code, Windsurf):\n\n```json\n{\n  \"mcpServers\": {\n    \"instantly\": {\n      \"command\": \"npx\",\n      \"args\": [\"instantly-cli\", \"mcp\"],\n      \"env\": {\n        \"INSTANTLY_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\nEvery MCP tool description says pass `profile` for agency. Mutating tools require `profile` + `workspace_id` matching the bound pair. Use `INSTANTLY_PROFILE` for a single-profile agent process. Call `status` first. There is no “run across all profiles” tool.\n\n```json\n{\n  \"mcpServers\": {\n    \"instantly-acme\": {\n      \"command\": \"npx\",\n      \"args\": [\"instantly-cli\", \"mcp\"],\n      \"env\": {\n        \"INSTANTLY_PROFILE\": \"acme\"\n      }\n    }\n  }\n}\n```\n\nThis registers 156 tools across 31 groups:\n\n| Group | Tools | Examples |\n|-------|-------|---------|\n| Campaigns | 11 | `campaigns_list`, `campaigns_activate`, `campaigns_duplicate` |\n| Leads | 12 | `leads_list`, `leads_create`, `leads_bulk_add`, `leads_merge` |\n| Accounts | 12 | `accounts_list`, `accounts_warmup_enable`, `accounts_pause` |\n| Email | 8 | `email_list`, `email_reply`, `email_forward`, `email_update` |\n| Analytics | 6 | `analytics_campaign`, `analytics_warmup`, `analytics_daily_campaign` |\n| Webhooks | 8 | `webhooks_list`, `webhooks_create`, `webhooks_update` |\n| Webhook Events | 4 | `webhook_events_list`, `webhook_events_summary` |\n| Lead Lists | 6 | `lead_lists_list`, `lead_lists_create`, `lead_lists_verification_stats` |\n| Enrichment | 10 | `enrichment_enrich`, `enrichment_ai`, `enrichment_preview` |\n| Blocklist | 5 | `blocklist_list`, `blocklist_create`, `blocklist_update` |\n| Custom Tags | 6 | `custom_tags_list`, `custom_tags_create`, `custom_tags_toggle` |\n| Custom Tag Mappings | 1 | `custom_tag_mappings_list` |\n| Lead Labels | 6 | `lead_labels_list`, `lead_labels_create`, `lead_labels_test_ai` |\n| Workspace | 6 | `workspace_get`, `workspace_update`, `workspace_whitelabel_create` |\n| Workspace Members | 5 | `workspace_members_list`, `workspace_members_create` |\n| Workspace Group Members | 5 | `workspace_group_members_list`, `workspace_group_members_create` |\n| Workspace Billing | 2 | `workspace_billing_plan_details`, `workspace_billing_subscription_details` |\n| Subsequences | 8 | `subsequences_list`, `subsequences_create`, `subsequences_pause` |\n| Background Jobs | 2 | `background_jobs_list`, `background_jobs_get` |\n| Email Verification | 2 | `email_verification_verify`, `email_verification_status` |\n| Account Mappings | 1 | `account_mappings_get` |\n| Audit Logs | 1 | `audit_logs_list` |\n| API Keys | 3 | `api_keys_create`, `api_keys_list`, `api_keys_delete` |\n| Inbox Placement | 6 | `inbox_placement_list`, `inbox_placement_create` |\n| Inbox Placement Analytics | 5 | `inbox_placement_analytics_list`, `inbox_placement_analytics_insights` |\n| Inbox Placement Reports | 2 | `inbox_placement_reports_list`, `inbox_placement_reports_get` |\n| CRM Actions | 2 | `crm_actions_list_phone_numbers`, `crm_actions_delete_phone_number` |\n| DFY Orders | 7 | `dfy_orders_list`, `dfy_orders_create`, `dfy_orders_cancel` |\n| Custom Prompt Templates | 5 | `custom_prompt_templates_list`, `custom_prompt_templates_create` |\n| Sales Flow | 5 | `sales_flow_list`, `sales_flow_create`, `sales_flow_delete` |\n| Email Templates | 5 | `email_templates_list`, `email_templates_create` |\n\n---\n\n## Example Workflows\n\n### Launch a campaign from scratch\n\n```bash\nexport INSTANTLY_API_KEY=your-key\n\n# Create the campaign\nCAMPAIGN=$(instantly campaigns create --name \"Q2 SaaS Outreach\" | jq -r '.id')\n\n# Import leads\ninstantly leads bulk-add --campaign-id \"$CAMPAIGN\" \\\n  --leads '[\n    {\"email\":\"cto@startup.com\",\"first_name\":\"Alex\",\"company_name\":\"Startup Inc\"},\n    {\"email\":\"vp@growth.co\",\"first_name\":\"Jordan\",\"company_name\":\"Growth Co\"}\n  ]'\n\n# Launch\ninstantly campaigns activate \"$CAMPAIGN\"\n\n# Check status\ninstantly campaigns sending-status \"$CAMPAIGN\"\n```\n\n### Monitor and respond to replies\n\n```bash\n# How many unread replies?\ninstantly email unread-count\n\n# Fetch unread emails for a campaign\ninstantly email list --campaign-id \"$CAMPAIGN\" --is-read false\n\n# Reply to a lead\ninstantly email reply \\\n  --reply-to-uuid \"<email-uuid>\" \\\n  --eaccount \"sender@yourdomain.com\" \\\n  --subject \"Re: Quick question\" \\\n  --body-text \"Thanks for your interest! Let's schedule a call.\"\n\n# Mark thread as read\ninstantly email mark-read \"<thread-id>\"\n```\n\n### Health-check your sending infrastructure\n\n```bash\n# List all accounts with their status\ninstantly accounts list\n\n# Run DNS, SMTP, and IMAP diagnostics\ninstantly accounts test-vitals \"<account-id>\"\n\n# Enable warmup on cold accounts\ninstantly accounts warmup-enable --account-ids \"id1,id2,id3\"\n\n# Check warmup analytics\ninstantly analytics warmup --emails \"sender1@domain.com,sender2@domain.com\"\n```\n\n### Test deliverability\n\n```bash\n# Run an inbox placement test\nTEST=$(instantly inbox-placement create \\\n  --name \"March Deliverability Check\" \\\n  --type 0 --sending-method 0 \\\n  --subject \"Test email\" \\\n  --body \"Hello from Instantly\" \\\n  --emails \"seed@test.com\" | jq -r '.id')\n\n# Check results\ninstantly inbox-placement-analytics insights --test-id \"$TEST\"\n```\n\n### Automate with cron\n\n```bash\n# Daily campaign health report (add to crontab)\n0 9 * * * INSTANTLY_API_KEY=your-key instantly analytics campaign-overview >> /var/log/instantly-daily.json\n\n# Alert on unread replies\n*/5 * * * * INSTANTLY_API_KEY=your-key instantly email unread-count | jq '.count'\n```\n\n---\n\n## Architecture\n\nThe 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:\n\n```\nsrc/\n├── core/\n│   ├── client.ts      # HTTP client with retry, rate limiting, pagination\n│   ├── auth.ts        # API key resolution (flag → env → .env → config; opt-in --profile)\n│   ├── output.ts      # JSON output formatting\n│   └── types.ts       # CommandDefinition interface\n├── commands/\n│   ├── campaigns/     # 11 commands\n│   ├── leads/         # 12 commands\n│   ├── accounts/      # 12 commands\n│   └── ...            # 28 more groups\n└── mcp/\n    └── server.ts      # MCP server (auto-registers all commands as tools)\n```\n\nAdding a new API endpoint = creating one file. The command is automatically available in both CLI and MCP.\n\n### HTTP Client Features\n\n- **Auto-retry** with exponential backoff on 429 (rate limit) and 5xx errors\n- **Rate limit awareness** — respects `Retry-After` headers\n- **Cursor-based pagination** — handles both UUID and datetime cursors\n- **30-second timeout** with configurable retries (default: 3)\n- **Typed errors** — `AuthError`, `NotFoundError`, `RateLimitError`, `ValidationError`, `ServerError`\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/bcharleson/instantly-cli.git\ncd instantly-cli\nnpm install\n\nnpm run dev -- campaigns list    # Run in dev mode (tsx)\nnpm run build                    # Build with tsup\nnpm test                         # Run tests (138 tests, vitest)\nnpm run typecheck                # Type-check (tsc --noEmit)\n```\n\n### Tech Stack\n\n- **TypeScript** (ESM, Node 20+)\n- **Commander.js** — CLI framework\n- **Zod** — schema validation (shared between CLI and MCP)\n- **@modelcontextprotocol/sdk** — MCP server\n- **tsup** — bundler\n- **vitest** — test runner\n\n---\n\n## License\n\nMIT\n",
  "bytes": 33975,
  "sha": "2d139edc17e2b7ead0999ff9c1afdb7821ca6d18ecc1a61f3b77cbeba52d8315",
  "repo_slug": "bcharleson/instantly-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_bcharleson_instantly_cli_478336dd/readme"
}