Instantly API

Use the Instantly API via direct curl calls to automate cold email outreach, manage campaigns, leads, and sending accounts.

Official docs: https://developer.instantly.ai/

---

When to Use

Use this skill when you need to:

• Manage email campaigns - create, launch, pause campaigns
• Handle leads - add, update, list leads in campaigns
• Manage sending accounts - list and configure email accounts
• Automate outreach - schedule sends and manage lead lists

---

Prerequisites

1. Sign up at Instantly.ai (Growth plan or above required for API)
2. Go to Settings > Integrations > API to create an API key
3. Select appropriate scopes for your use case

export INSTANTLY_API_KEY="your-api-key"

API Scopes

Create API keys with specific permissions:

• campaigns:read, campaigns:create, campaigns:update
• leads:read, leads:create, leads:update, leads:delete
• lead_lists:read, lead_lists:create
• analytics:read
• all:all (full access)

---

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

All examples below assume you have INSTANTLY_API_KEY set.

The base URL for API V2 is:

• https://api.instantly.ai/api/v2

Authentication uses Bearer token in the Authorization header.

---

1. List Campaigns

Get all campaigns:

bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '.items[] | {id, name, status}

With filters:

bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns?status=ACTIVE&limit=10" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '.items[] | {id, name}

Status values: ACTIVE, PAUSED, COMPLETED, DRAFTED

---

2. Get Single Campaign

Get campaign details by ID:

CAMPAIGN_ID="your-campaign-id"

bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns/${CAMPAIGN_ID}" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '{id, name, status, daily_limit}

---

3. Create Campaign

Create a new campaign (requires campaign_schedule):

bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{
  "name": "My New Campaign",
  "daily_limit": 50,
  "campaign_schedule": {
    "timezone": "America/New_York",
    "days": {
      "monday": [{"start": "09:00", "end": "17:00"}],
      "tuesday": [{"start": "09:00", "end": "17:00"}],
      "wednesday": [{"start": "09:00", "end": "17:00"}],
      "thursday": [{"start": "09:00", "end": "17:00"}],
      "friday": [{"start": "09:00", "end": "17:00"}]
    }
  }
}'"'"' | jq .'

---

4. Pause/Activate Campaign

Control campaign status:

CAMPAIGN_ID="your-campaign-id"

# Pause campaign
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns/${CAMPAIGN_ID}/pause" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq .

# Activate campaign
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns/${CAMPAIGN_ID}/activate" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq .

---

5. List Leads

List leads (POST endpoint due to complex filters):

bash -c 'curl -s "https://api.instantly.ai/api/v2/leads/list" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{"limit": 10}'"'"'' | jq '.items[] | {id, email, first_name, last_name}

Filter by campaign:

bash -c 'curl -s "https://api.instantly.ai/api/v2/leads/list" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{
  "campaign_id": "your-campaign-id",
  "limit": 20
}'"'"' | jq '"'"'.items[] | {email, status}'"'"''

---

6. Create Lead

Add a single lead:

bash -c 'curl -s "https://api.instantly.ai/api/v2/leads" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Corp",
  "campaign_id": "your-campaign-id"
}'"'"' | jq .'

With custom variables:

bash -c 'curl -s "https://api.instantly.ai/api/v2/leads" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{
  "email": "jane@example.com",
  "first_name": "Jane",
  "campaign_id": "your-campaign-id",
  "custom_variables": {
  "role": "CTO",
  "industry": "SaaS"
  }
}'"'"' | jq .'

---

7. Get Single Lead

Get lead by ID:

LEAD_ID="your-lead-id"

bash -c 'curl -s "https://api.instantly.ai/api/v2/leads/${LEAD_ID}" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq .

---

8. Update Lead

Update lead information:

LEAD_ID="your-lead-id"

bash -c 'curl -s "https://api.instantly.ai/api/v2/leads/${LEAD_ID}" -X PATCH -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{
  "first_name": "Updated Name",
  "custom_variables": {
  "notes": "High priority"
  }
}'"'"' | jq .'

---

9. List Lead Lists

Get all lead lists:

bash -c 'curl -s "https://api.instantly.ai/api/v2/lead-lists" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '.items[] | {id, name}

---

10. Create Lead List

Create a new lead list:

bash -c 'curl -s "https://api.instantly.ai/api/v2/lead-lists" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d '"'"'{
  "name": "Q1 Prospects"
}'"'"' | jq .'

---

11. List Email Accounts

Get connected sending accounts:

bash -c 'curl -s "https://api.instantly.ai/api/v2/accounts" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '.items[] | {email, status, warmup_status}

---

12. Test API Key

Verify your API key is valid:

bash -c 'curl -s "https://api.instantly.ai/api/v2/api-keys" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '.items[0] | {name, scopes}

---

Pagination

List endpoints support pagination:

# First page
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns?limit=10" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq '{items: .items | length, next_starting_after: .next_starting_after}

# Next page
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns?limit=10&starting_after=CURSOR" -H "Authorization: Bearer ${INSTANTLY_API_KEY}"' | jq .

---

Guidelines

1. Use API V2: V1 is deprecated, use V2 endpoints only
2. Bearer token auth: Always use Authorization: Bearer header
3. Scope your keys: Create keys with minimal required permissions
4. Custom variables: Values must be string, number, boolean, or null (no objects/arrays)
5. Leads list is POST: Due to complex filters, listing leads uses POST not GET
6. Rate limits: Respect rate limits based on your plan tier
7. Growth plan required: API access requires Growth plan or above