Agent skill

instantly

Instantly.ai API for cold email campaigns. Use when user mentions "Instantly", "cold email", "email campaign", or outreach automation.

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/instantly

SKILL.md

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
bash
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)

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
curl -s "https://api.instantly.ai/api/v2/campaigns" -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" | jq '.items[] | {id, name, status}'

With filters:

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

Status values: ACTIVE, PAUSED, COMPLETED, DRAFTED

2. Get Single Campaign

Get campaign details by ID. Replace <your-campaign-id> with the actual campaign ID:

bash
curl -s "https://api.instantly.ai/api/v2/campaigns/<your-campaign-id>" -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" | jq '{id, name, status, daily_limit}'

3. Create Campaign

Create a new campaign (requires campaign_schedule):

Write to /tmp/instantly_request.json:

json
{
  "name": "My New Campaign",
  "daily_limit": 50,
  "campaign_schedule": {
    "schedules": [
      {
        "name": "Weekday Schedule",
        "timezone": "America/Chicago",
        "days": {
          "monday": true,
          "tuesday": true,
          "wednesday": true,
          "thursday": true,
          "friday": true,
          "saturday": false,
          "sunday": false
        },
        "timing": {
          "from": "09:00",
          "to": "17:00"
        }
      }
    ]
  }
}

Then run:

bash
curl -s "https://api.instantly.ai/api/v2/campaigns" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" -H "Content-Type: application/json" -d @/tmp/instantly_request.json

4. Pause/Activate Campaign

Control campaign status. Replace <your-campaign-id> with the actual campaign ID:

bash
# Pause campaign
curl -s "https://api.instantly.ai/api/v2/campaigns/<your-campaign-id>/pause" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)"

# Activate campaign
curl -s "https://api.instantly.ai/api/v2/campaigns/<your-campaign-id>/activate" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)"

5. List Leads

List leads (POST endpoint due to complex filters):

Write to /tmp/instantly_request.json:

json
{
  "limit": 10
}

Then run:

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

Filter by campaign:

Write to /tmp/instantly_request.json:

json
{
  "campaign_id": "your-campaign-id",
  "limit": 20
}

Then run:

bash
curl -s "https://api.instantly.ai/api/v2/leads/list" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" -H "Content-Type: application/json" -d @/tmp/instantly_request.json | jq '.items[] | {email, status}'

6. Create Lead

Add a single lead:

Write to /tmp/instantly_request.json:

json
{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Corp",
  "campaign_id": "your-campaign-id"
}

Then run:

bash
curl -s "https://api.instantly.ai/api/v2/leads" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" -H "Content-Type: application/json" -d @/tmp/instantly_request.json

With custom variables:

Write to /tmp/instantly_request.json:

json
{
  "email": "jane@example.com",
  "first_name": "Jane",
  "campaign_id": "your-campaign-id",
  "custom_variables": {
    "role": "CTO",
    "industry": "SaaS"
  }
}

Then run:

bash
curl -s "https://api.instantly.ai/api/v2/leads" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" -H "Content-Type: application/json" -d @/tmp/instantly_request.json

7. Get Single Lead

Get lead by ID. Replace <your-lead-id> with the actual lead ID:

bash
curl -s "https://api.instantly.ai/api/v2/leads/<your-lead-id>" -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)"

8. Update Lead

Update lead information:

Write to /tmp/instantly_request.json:

json
{
  "first_name": "Updated Name",
  "custom_variables": {
    "notes": "High priority"
  }
}

Then run. Replace <your-lead-id> with the actual lead ID:

bash
curl -s "https://api.instantly.ai/api/v2/leads/<your-lead-id>" -X PATCH -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" -H "Content-Type: application/json" -d @/tmp/instantly_request.json

9. List Lead Lists

Get all lead lists:

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

10. Create Lead List

Create a new lead list:

Write to /tmp/instantly_request.json:

json
{
  "name": "Q1 Prospects"
}

Then run:

bash
curl -s "https://api.instantly.ai/api/v2/lead-lists" -X POST -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" -H "Content-Type: application/json" -d @/tmp/instantly_request.json

11. List Email Accounts

Get connected sending accounts:

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

12. Test API Key

Verify your API key is valid:

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

Pagination

List endpoints support pagination:

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

# Next page (replace <your-cursor> with the next_starting_after value from the previous response)
curl -s "https://api.instantly.ai/api/v2/campaigns?limit=10&starting_after=<your-cursor>" -H "Authorization: Bearer $(printenv INSTANTLY_API_KEY)" | jq '.items[] | {id, name}'

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

vm0-ai/vm0-skills

brave-search

Brave Search API for web search. Use when user says "search web", "Brave search", or asks to "find on web" without specifying Google.

50 8
Explore
vm0-ai/vm0-skills

supadata

Supadata API for YouTube/web data. Use when user mentions "Supadata", "YouTube data", "channel stats", or web scraping data.

50 8
Explore
vm0-ai/vm0-skills

roadmap-planning

Build and prioritize product roadmaps using scoring models like RICE, ICE, and value-effort matrices. Activate when creating a product roadmap, prioritizing features, sequencing initiatives, mapping dependencies, balancing team capacity, choosing between Now/Next/Later or quarterly planning, or communicating roadmap tradeoffs to executives and stakeholders.

50 8
Explore
vm0-ai/vm0-skills

qdrant

Qdrant API for vector search. Use when user mentions "Qdrant", "vector database", "semantic search", or embeddings storage.

50 8
Explore
vm0-ai/vm0-skills

calendly

Calendly scheduling API. Use when user mentions "Calendly", "calendly.com", "schedule a meeting", "booking link", "event types", or asks about interview scheduling.

50 8
Explore
vm0-ai/vm0-skills

stripe

Stripe API for payments. Use when user mentions "Stripe", "payment", "subscription", "billing", "invoice", or asks about payment processing.

50 8
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results