instantly-install-auth

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

1. Log into https://app.instantly.ai
2. Navigate to Settings > Integrations > API
3. Click Create New API Key
4. Select scopes (e.g., campaigns:read, leads:all, accounts:read)
5. Copy the key — it is shown only once

set -euo pipefail
# Create .env file with your API key
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)

// src/instantly.ts
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}: ${body}`);
  }

  return res.json() as Promise<T>;
}

Step 3: Create API Client Wrapper (Python)

# instantly_client.py
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

// verify.ts — run with: npx tsx verify.ts
import { instantly } from "./src/instantly";

interface Campaign {
  id: string;
  name: string;
  status: number;
}

async function verify() {
  // List campaigns — if this returns, auth is working
  const campaigns = await instantly<Campaign[]>("/campaigns?limit=1");
  console.log("Auth verified. Campaigns found:", campaigns.length >= 0);

  // List email accounts
  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(1);
});

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

• Instantly API v2 Docs
• API v1 to v2 Migration Guide
• Instantly Help Center

Next Steps

After successful auth, proceed to instantly-hello-world for your first API call.