home / skills / vm0-ai / vm0-skills / instantly

instantly skill

safe

This skill helps you automate cold email workflows via Instantly API using curl to manage campaigns, leads, and sending accounts.

npx playbooks add skill vm0-ai/vm0-skills --skill instantly

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

8.2 KB

---
name: instantly
description: Instantly.ai API via curl. Use this skill for cold email outreach automation, managing campaigns, leads, and email accounts.
vm0_secrets:
  - INSTANTLY_API_KEY
---

# 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](https://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)

---


> **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
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.items[] | {id, name}'
> ```

## 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
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
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. Replace `<your-campaign-id>` with the actual campaign ID:

```bash
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns/<your-campaign-id>" -H "Authorization: Bearer ${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
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 @/tmp/instantly_request.json'
```

---

### 4. Pause/Activate Campaign

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

```bash
# Pause campaign
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns/<your-campaign-id>/pause" -X POST -H "Authorization: Bearer ${INSTANTLY_API_KEY}"'

# Activate campaign
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns/<your-campaign-id>/activate" -X POST -H "Authorization: Bearer ${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
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 @/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
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 @/tmp/instantly_request.json' | jq '.items[] | {email, status}'
```

---

### 6. Create Lead

Add a single lead:

Write to `/tmp/instantly_request.json`:

```json
{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Corp",
  "campaign_id": "your-campaign-id"
}
```

Then run:

```bash
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 @/tmp/instantly_request.json'
```

With custom variables:

Write to `/tmp/instantly_request.json`:

```json
{
  "email": "[email protected]",
  "first_name": "Jane",
  "campaign_id": "your-campaign-id",
  "custom_variables": {
    "role": "CTO",
    "industry": "SaaS"
  }
}
```

Then run:

```bash
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 @/tmp/instantly_request.json'
```

---

### 7. Get Single Lead

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

```bash
bash -c 'curl -s "https://api.instantly.ai/api/v2/leads/<your-lead-id>" -H "Authorization: Bearer ${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
bash -c 'curl -s "https://api.instantly.ai/api/v2/leads/<your-lead-id>" -X PATCH -H "Authorization: Bearer ${INSTANTLY_API_KEY}" -H "Content-Type: application/json" -d @/tmp/instantly_request.json'
```

---

### 9. List Lead Lists

Get all lead lists:

```bash
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:

Write to `/tmp/instantly_request.json`:

```json
{
  "name": "Q1 Prospects"
}
```

Then run:

```bash
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 @/tmp/instantly_request.json'
```

---

### 11. List Email Accounts

Get connected sending accounts:

```bash
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
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:

```bash
# 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 (replace <your-cursor> with the next_starting_after value from the previous response)
bash -c 'curl -s "https://api.instantly.ai/api/v2/campaigns?limit=10&starting_after=<your-cursor>" -H "Authorization: Bearer ${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

Overview

This skill provides direct curl-based access to the Instantly.ai API to automate cold email outreach, manage campaigns, leads, and sending accounts. It focuses on practical command examples you can run in a shell with an INSTANTLY_API_KEY environment variable. Use it to script campaign creation, lead imports, account checks, and campaign control actions programmatically.

How this skill works

The skill issues authenticated HTTP requests (Bearer token) to Instantly API v2 endpoints using curl wrapped in bash -c to preserve environment variables when piping. It covers listing, creating, updating, pausing/activating campaigns; listing, creating, and updating leads; managing lead lists and sending accounts; and basic pagination and key testing. Example JSON payloads are written to temporary files and sent with -d @file to keep commands reproducible.

When to use it

Automate bulk cold outreach workflows and scheduling.
Create, pause, or update campaigns from CI/CD or scripts.
Import and update leads programmatically with custom variables.
Retrieve and paginate large campaign or lead lists for reporting.
Manage and audit connected sending accounts and API key scopes.

Best practices

Store INSTANTLY_API_KEY in environment variables and never hard-code secrets.
Wrap curl calls in bash -c '...' when piping to jq to avoid lost environment variables.
Create scoped API keys with the minimal permissions needed (avoid all:all).
Use API v2 endpoints exclusively; V1 is deprecated.
Respect rate limits and use pagination cursors for large datasets.

Example use cases

Create a weekday-only campaign via a JSON payload and curl POST to /campaigns.
List active campaigns and their IDs to drive downstream automation.
Add leads in bulk with custom_variables to personalize email templates.
Pause or activate campaigns as part of a deployment or A/B test run.
List connected accounts to check warmup_status and routing before sending.

FAQ

What do I need before running commands?

Sign up for Instantly on a Growth plan or above, create an API key with appropriate scopes, and export INSTANTLY_API_KEY in your shell.

Why wrap curl in bash -c '...' ?

Some shells or environments clear environment variables when commands are piped. Wrapping in bash -c preserves $INSTANTLY_API_KEY when piping output to jq or other commands.