Instantly Install & Auth
Overview
Configure Instantly.ai API v2 authentication. Instantly uses Bearer token auth with scoped API keys. There is no official SDK — all integrations use direct REST calls to https://api.instantly.ai/api/v2/.
Prerequisites
- Instantly.ai account on Hypergrowth plan ($97/mo) or higher (required for API v2 access)
- Node.js 18+ or Python 3.10+
- Access to Instantly dashboard at
https://app.instantly.ai
Instructions
Step 1: Generate API Key
- Log into
https://app.instantly.ai
- Navigate to Settings > Integrations > API
- Click Create New API Key
- Select scopes (e.g.,
campaigns:read, leads:all, accounts:read)
- Copy the key — it is shown only once
set -euo pipefail
cat > .env << 'ENVEOF'
INSTANTLY_API_KEY=your-api-key-here
INSTANTLY_BASE_URL=https://api.instantly.ai/api/v2
ENVEOF
echo "Created .env with Instantly config"
Available API scopes (resource:action format):
| Scope | Access |
|---|
campaigns:read | List/get campaigns and analytics |
campaigns:update | Create, patch, activate, pause campaigns |
campaigns:all | Full campaign CRUD + analytics |
accounts:read | List/get email accounts |
accounts:update | Create, warmup, pause accounts |
leads:read | List/get leads and lead lists |
leads:update | Create, move, delete leads |
leads:all | Full lead CRUD |
all:all | Unrestricted access (dev only) |
Step 2: Create API Client Wrapper (TypeScript)
import "dotenv/config";
const BASE = process.env.INSTANTLY_BASE_URL || "https://api.instantly.ai/api/v2";
const API_KEY = process.env.INSTANTLY_API_KEY;
if (!API_KEY) throw new Error("INSTANTLY_API_KEY is required");
export async function instantly<T = unknown>(
path: string,
options: RequestInit = {}
): Promise<T> {
const url = `${BASE}${path}`;
const res = await fetch(url, {
...options,
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`,
...options.headers,
},
});
if (!res.ok) {
const body = await res.text();
throw new Error(`Instantly API ${res.status}: `);
}
res.() <T>;
}
Step 3: Create API Client Wrapper (Python)
import os
import httpx
from dotenv import load_dotenv
load_dotenv()
BASE_URL = os.getenv("INSTANTLY_BASE_URL", "https://api.instantly.ai/api/v2")
API_KEY = os.getenv("INSTANTLY_API_KEY")
if not API_KEY:
raise ValueError("INSTANTLY_API_KEY environment variable is required")
client = httpx.Client(
base_url=BASE_URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
timeout=30.0,
)
def instantly_get(path: str, params: dict = None):
r = client.get(path, params=params)
r.raise_for_status()
return r.json()
def instantly_post(path: str, json_data: dict = None):
r = client.post(path, json=json_data)
r.raise_for_status()
return r.json()
Step 4: Verify Connection
import { instantly } from "./src/instantly";
interface Campaign {
id: string;
name: string;
status: number;
}
async function verify() {
const campaigns = await instantly<Campaign[]>("/campaigns?limit=1");
console.log("Auth verified. Campaigns found:", campaigns.length >= 0);
const accounts = await instantly<{ email: string }[]>("/accounts?limit=1");
console.log("Accounts accessible:", accounts.length >= 0);
console.log("Instantly API v2 connection is working.");
}
verify().catch((err) => {
console.error("Auth failed:", err.message);
process.exit();
});
Output
.env file with INSTANTLY_API_KEY and INSTANTLY_BASE_URL- Reusable API client wrapper (
src/instantly.ts or instantly_client.py)
- Verified connection to Instantly API v2
Error Handling
| Error | Cause | Solution |
|---|
401 Unauthorized | Invalid or expired API key | Regenerate key in Settings > Integrations |
403 Forbidden | Key missing required scope | Edit key scopes or create new key with correct permissions |
429 Too Many Requests | Rate limit exceeded | Implement exponential backoff (see instantly-rate-limits) |
ECONNREFUSED | Network/firewall issue | Ensure outbound HTTPS to api.instantly.ai is allowed |
API key not found | Key was revoked | Generate a new key from the dashboard |
Resources
Next Steps
After successful auth, proceed to instantly-hello-world for your first API call.
