Instantly Data Handling

Overview

Manage leads, lead lists, block lists, and regulatory compliance in Instantly API v2. Covers lead CRUD operations, list management, bulk import patterns, unsubscribe handling, GDPR right-to-deletion, CAN-SPAM compliance, and block list automation. Cold email has specific legal requirements — this skill ensures your integrations are compliant.

Prerequisites

• Completed instantly-install-auth setup
• API key with leads:all scope
• Understanding of CAN-SPAM / GDPR requirements for cold outreach

Instructions

Step 1: Lead List Management

import { InstantlyClient } from "./src/instantly/client";
const client = new InstantlyClient();

// Create a lead list (container for leads outside campaigns)
async function createLeadList(name: string) {
  const list = await client.request<{ id: string; name: string }>("/lead-lists", {
    method: "POST",
    body: JSON.stringify({
      name,
      has_enrichment_task: false,
    }),
  });
  console.log(`Created list: ${list.name} (${list.id})`);
  return list;
}

// List all lead lists
async function getLeadLists() {
  return client.request<Array<{
    id: string; name: string; timestamp_created: string;
  }>>("/lead-lists?limit=50");
}

// Delete a lead list
async function deleteLeadList(listId: string) {
  await client.request(`/lead-lists/${listId}`, { method: "DELETE" });
}

Step 2: Lead Import with Validation

interface LeadImport {
  email: string;
  first_name?: string;
  last_name?: string;
  company_name?: string;
  website?: string;
  phone?: string;
  custom_variables?: Record<string, string>;
}

async function importLeads(
  campaignId: string,
  leads: LeadImport[],
  options = { skipDuplicates: true, verifyEmails: true }
) {
  const results = { added: 0, skipped: 0, failed: 0, errors: [] as string[] };

  for (const lead of leads) {
    try {
      // Validate email format
      if (!lead.email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(lead.email)) {
        results.failed++;
        results.errors.push(`Invalid email: ${lead.email}`);
        continue;
      }

      // Check against block list patterns
      const domain = lead.email.split("@")[1];
      if (BLOCKED_PATTERNS.some((p) => domain.includes(p))) {
        results.skipped++;
        continue;
      }

      await client.request("/leads", {
        method: "POST",
        body: JSON.stringify({
          campaign: campaignId,
          email: lead.email,
          first_name: lead.first_name,
          last_name: lead.last_name,
          company_name: lead.company_name,
          website: lead.website,
          phone: lead.phone,
          custom_variables: lead.custom_variables,
          skip_if_in_worksp

Instantly Debug Bundle

Overview

Collect a comprehensive debug bundle from your Instantly workspace: campaign state, account health, warmup metrics, lead stats, webhook delivery status, and recent errors. Output is a JSON report suitable for support tickets or internal audits.

Prerequisites

• Completed instantly-install-auth setup
• API key with all:read scope (or individual read scopes for each resource)

Instructions

Step 1: Collect Full Debug Bundle

import { instantly } from "./src/instantly";
import { writeFileSync } from "fs";

interface DebugBundle {
  timestamp: string;
  workspace: unknown;
  campaigns: unknown[];
  accounts: unknown[];
  warmup_analytics: unknown[];
  webhooks: unknown[];
  webhook_event_summary: unknown;
  background_jobs: unknown[];
  lead_count_by_campaign: Record<string, number>;
  errors: string[];
}

async function collectDebugBundle(): Promise<DebugBundle> {
  const bundle: DebugBundle = {
    timestamp: new Date().toISOString(),
    workspace: null,
    campaigns: [],
    accounts: [],
    warmup_analytics: [],
    webhooks: [],
    webhook_event_summary: null,
    background_jobs: [],
    lead_count_by_campaign: {},
    errors: [],
  };

  // Workspace info
  try {
    bundle.workspace = await instantly("/workspaces/current");
  } catch (e: any) {
    bundle.errors.push(`workspace: ${e.message}`);
  }

  // All campaigns with status
  try {
    bundle.campaigns = await instantly("/campaigns?limit=100");
  } catch (e: any) {
    bundle.errors.push(`campaigns: ${e.message}`);
  }

  // All email accounts
  try {
    bundle.accounts = await instantly("/accounts?limit=100");
  } catch (e: any) {
    bundle.errors.push(`accounts: ${e.message}`);
  }

  // Warmup analytics for all accounts
  try {
    const accounts = bundle.accounts as Array<{ email: string }>;
    if (accounts.length > 0) {
      bundle.warmup_analytics = await instantly("/accounts/warmup-analytics", {
        method: "POST",
        body: JSON.stringify({ emails: accounts.map((a) => a.email) }),
      });
    }
  } catch (e: any) {
    bundle.errors.push(`warmup_analytics: ${e.message}`);
  }

  // Webhooks
  try {
    bundle.webhooks = await instantly("/webhooks?limit=50");
  } catch (e: any) {
    bundle.errors.push(`webhooks: ${e.message}`);
  }

  // Webhook event delivery summary
  try {
    bundle.webhook_event_summary = await instantly("/webhook-events/summary");
  } catch (e: any) {
    bundle.errors.push(`webhook_events: ${e.message}`);
  }

  // Recent background jobs
  try {
    bundle.background_jobs = await instantly("/background-jobs?limit=20");
  } catch (e: any) {
    bundle.errors.push(`background_jobs: ${e.message}`);
  }

  // Lead counts per campaign
  for (const c of (bund

Instantly Deploy Integration

Overview

Deploy Instantly API v2 integrations — primarily webhook receivers and automation services — to cloud platforms. Instantly webhooks require a public HTTPS endpoint that responds within 30 seconds (3 retries on failure). This skill covers Vercel serverless functions, Google Cloud Run containers, and Fly.io deployments.

Prerequisites

• Completed instantly-install-auth setup
• Working Instantly integration tested locally (see instantly-local-dev-loop)
• Cloud platform account (Vercel, GCP, or Fly.io)
• Domain or HTTPS URL for webhook endpoint

Instructions

Option A: Vercel Serverless Functions

// api/webhooks/instantly.ts — Vercel serverless function
import type { VercelRequest, VercelResponse } from "@vercel/node";

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  // Validate webhook secret
  const secret = req.headers["x-webhook-secret"];
  if (secret !== process.env.INSTANTLY_WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const { event_type, data } = req.body;

  // Respond immediately — Instantly expects 2xx within 30s
  res.status(200).json({ received: true });

  // Process event asynchronously
  try {
    switch (event_type) {
      case "reply_received":
        await syncReplyToCRM(data);
        break;
      case "email_bounced":
        await handleBounce(data);
        break;
      case "lead_interested":
        await notifySalesTeam(data);
        break;
      case "lead_unsubscribed":
        await addToBlockList(data);
        break;
    }
  } catch (err) {
    console.error(`Webhook processing error: ${event_type}`, err);
  }
}

async function addToBlockList(data: { lead_email: string }) {
  await fetch("https://api.instantly.ai/api/v2/block-lists-entries", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.INSTANTLY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ bl_value: data.lead_email }),
  });
}

# Deploy to Vercel
vercel env add INSTANTLY_API_KEY
vercel env add INSTANTLY_WEBHOOK_SECRET
vercel deploy --prod

Option B: Google Cloud Run

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 8080
ENV PORT=8080
CMD ["node", "dist/server.js

Instantly Enterprise RBAC

Overview

Manage workspace access control in Instantly API v2. Covers workspace member management, API key governance with scoped permissions, workspace group management (for agencies), custom tag-based resource isolation, and audit logging. Instantly uses workspace-level isolation — each workspace is a separate tenant with its own data and API keys.

Prerequisites

• Instantly Hypergrowth plan or higher
• Workspace admin access
• API key with all:all scope (for admin operations)

Instructions

Step 1: Workspace Member Management

import { InstantlyClient } from "./src/instantly/client";
const client = new InstantlyClient();

// List workspace members
async function listMembers() {
  const members = await client.request<Array<{
    id: string;
    email: string;
    role: string;
    timestamp_created: string;
  }>>("/workspace-members");

  console.log("Workspace Members:");
  for (const m of members) {
    console.log(`  ${m.email} — role: ${m.role} (joined: ${m.timestamp_created})`);
  }
  return members;
}

// Invite new member
async function inviteMember(email: string) {
  const member = await client.request<{ id: string; email: string }>("/workspace-members", {
    method: "POST",
    body: JSON.stringify({ email }),
  });
  console.log(`Invited: ${member.email} (${member.id})`);
  return member;
}

// Update member role
async function updateMemberRole(memberId: string, role: string) {
  await client.request(`/workspace-members/${memberId}`, {
    method: "PATCH",
    body: JSON.stringify({ role }),
  });
}

// Remove member
async function removeMember(memberId: string) {
  await client.request(`/workspace-members/${memberId}`, { method: "DELETE" });
  console.log(`Removed member: ${memberId}`);
}

Step 2: API Key Governance

// Create scoped API keys for different team roles
async function createScopedKeys() {
  // Analytics-only key for the marketing team
  const analyticsKey = await client.request<{ id: string; key: string; name: string }>(
    "/api-keys",
    {
      method: "POST",
      body: JSON.stringify({
        name: "Marketing — Analytics Read Only",
        scopes: ["campaigns:read", "accounts:read"],
      }),
    }
  );
  console.log(`Analytics key: ${analyticsKey.name} (${analyticsKey.id})`);

  // Campaign management key for SDR team
  const sdrKey = await client.request<{ id: string; key: string; name: string }>(
    "/api-keys",
    {
      method: "POST",
      body: JSON.stringify({
        name: "SDR — Campaign Management",
        scopes: ["campaigns:all", "leads:all"],
      }),
    }
  );
  console.log(`SDR key: $

Instantly Hello World

Overview

Minimal working example that lists your campaigns, checks email account health, and pulls campaign analytics — all using real Instantly API v2 endpoints.

Prerequisites

• Completed instantly-install-auth setup
• At least one email account connected in Instantly
• INSTANTLY_API_KEY environment variable set

Instructions

Step 1: List Your Campaigns

import { instantly } from "./src/instantly";

interface Campaign {
  id: string;
  name: string;
  status: number; // 0=Draft, 1=Active, 2=Paused, 3=Completed
}

const STATUS_LABELS: Record<number, string> = {
  0: "Draft", 1: "Active", 2: "Paused", 3: "Completed",
  4: "Running Subsequences", [-99]: "Suspended",
  [-1]: "Accounts Unhealthy", [-2]: "Bounce Protect",
};

async function listCampaigns() {
  const campaigns = await instantly<Campaign[]>("/campaigns?limit=10");

  console.log(`Found ${campaigns.length} campaigns:\n`);
  for (const c of campaigns) {
    console.log(`  ${c.name} [${STATUS_LABELS[c.status] ?? c.status}] — ${c.id}`);
  }
  return campaigns;
}

Step 2: Check Email Account Health

interface Account {
  email: string;
  status: number;
  warmup_status: string;
  daily_limit: number | null;
}

async function checkAccounts() {
  const accounts = await instantly<Account[]>("/accounts?limit=5");

  console.log(`\nEmail Accounts (${accounts.length}):`);
  for (const a of accounts) {
    console.log(`  ${a.email} — status: ${a.status}, warmup: ${a.warmup_status}, daily_limit: ${a.daily_limit}`);
  }

  // Test vitals for the first account
  if (accounts.length > 0) {
    const vitals = await instantly("/accounts/test/vitals", {
      method: "POST",
      body: JSON.stringify({ accounts: [accounts[0].email] }),
    });
    console.log(`\nVitals for ${accounts[0].email}:`, JSON.stringify(vitals, null, 2));
  }
}

Step 3: Pull Campaign Analytics

async function getAnalytics(campaignId: string) {
  const stats = await instantly<{
    campaign_id: string;
    total_leads: number;
    leads_contacted: number;
    emails_sent: number;
    emails_opened: number;
    emails_replied: number;
    emails_bounced: number;
  }>(`/campaigns/analytics?id=${campaignId}`);

  console.log(`\nCampaign Analytics:`);
  console.log(`  Leads: ${stats.total_leads} total, ${stats.leads_contacted} contacted`);
  console.log(`  Sent: ${stats.emails_sent}`);
  console.log(`  Opened: ${stats.emails_opened} (${((stats.emails_opened / stats.emails_sent) * 100).toFixed(1)}%)`);
  console.log(`  Replied: ${stats.emails_replied} (${((stats.emails_replied / stats.emails_sent) * 100).toFix

Instantly Incident Runbook

Overview

Structured incident response procedures for Instantly.ai integration failures. Covers campaign pause cascades, account health crises, bounce protect triggers, webhook delivery failures, and API outages.

Severity Levels

Incident: All Campaigns in Accounts Unhealthy (-1)

Triage

import { InstantlyClient } from "./src/instantly/client";
const client = new InstantlyClient();

async function triageCampaignHealth() {
  console.log("=== P1 TRIAGE: Campaign Health ===\n");

  // 1. Get all campaigns and their statuses
  const campaigns = await client.campaigns.list(100);
  const statusCounts: Record<number, number> = {};
  for (const c of campaigns) {
    statusCounts[c.status] = (statusCounts[c.status] || 0) + 1;
  }
  console.log("Campaign status distribution:", statusCounts);

  const unhealthy = campaigns.filter((c) => c.status === -1);
  console.log(`Unhealthy campaigns: ${unhealthy.length}`);

  // 2. Test ALL account vitals
  const accounts = await client.accounts.list(200);
  const vitals = await client.accounts.testVitals(accounts.map((a) => a.email));

  const broken = (vitals as any[]).filter((v) => v.smtp_status !== "ok" || v.imap_status !== "ok");
  const healthy = (vitals as any[]).filter((v) => v.smtp_status === "ok" && v.imap_status === "ok");

  console.log(`\nAccounts: ${accounts.length} total, ${healthy.length} healthy, ${broken.length} broken`);

  if (broken.length > 0) {
    console.log("\nBroken accounts:");
    for (const v of broken) {
      console.log(`  ${v.email}: SMTP=${v.smtp_status} IMAP=${v.imap_status} DNS=${v.dns_status}`);
    }
  }

  return { unhealthy, broken, healthy };
}

Mitigation

async function mitigateBrokenAccounts() {
  const { broken, healthy } = await triageCampaignHealth();

  // Step 1: Pause broken accounts
  for (const v of broken) {
    try {
      await client.accounts.pause(v.email);
      console.log(`Paused broken account: ${v.email}`);
    } catch (e: any) {
      console.log(`Failed to pause ${v.email}: ${e.message}`);
    }
  }

  // Step 2: 

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

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>;
}
<

Instantly Local Dev Loop

Overview

Set up a local development workflow for Instantly integrations. Instantly provides a mock server at `` for testing without sending real emails or consuming API limits. This skill covers mock server usage, integration testing, and local webhook development.

Prerequisites

• Completed instantly-install-auth setup
• Node.js 18+ with TypeScript
• A separate Instantly API key for dev/test (recommended)

Instructions

Step 1: Configure Dev Environment

// src/config.ts
import "dotenv/config";

interface Config {
  baseUrl: string;
  apiKey: string;
  useMock: boolean;
}

export function getConfig(): Config {
  const useMock = process.env.INSTANTLY_USE_MOCK === "true";
  return {
    baseUrl: useMock
      ? "https://developer.instantly.ai/_mock/api/v2"
      : process.env.INSTANTLY_BASE_URL || "https://api.instantly.ai/api/v2",
    apiKey: process.env.INSTANTLY_API_KEY || "",
    useMock,
  };
}

# .env.development
INSTANTLY_API_KEY=your-dev-api-key
INSTANTLY_BASE_URL=https://api.instantly.ai/api/v2
INSTANTLY_USE_MOCK=true

# .env.production
INSTANTLY_API_KEY=your-prod-api-key
INSTANTLY_BASE_URL=https://api.instantly.ai/api/v2
INSTANTLY_USE_MOCK=false

Step 2: Build a Testable API Client

// src/instantly.ts
import { getConfig } from "./config";

const config = getConfig();

export async function instantly<T = unknown>(
  path: string,
  options: RequestInit = {}
): Promise<T> {
  const url = `${config.baseUrl}${path}`;
  const res = await fetch(url, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${config.apiKey}`,
      ...options.headers,
    },
  });

  if (res.status === 429) {
    const retryAfter = parseInt(res.headers.get("retry-after") || "2", 10);
    console.warn(`Rate limited. Retrying in ${retryAfter}s...`);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return instantly<T>(path, options);
  }

  if (!res.ok) {
    const body = await res.text();
    throw new InstantlyError(res.status, path, body);
  }

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

class InstantlyError extends Error {
  constructor(
    public status: number,
    public path: string,
    public body: string
  ) {
    super(`Instantly API ${status} on ${path}: ${body}`);
    this.name = "InstantlyError";
  }
}

Step 3: Write Integration Tests

// tests/instantly.test.ts
import { describe, it, expect, beforeAll } from "vitest";
import { instantly } from "../src/instantly";

describe("Instantly API Integration", () => {
  it("

Instantly Migration Deep Dive

Overview

Strategies for migrating to/from Instantly or consolidating multiple outreach tools into Instantly. Covers data migration (leads, campaigns, templates), account migration (email infrastructure), analytics preservation, and parallel-run strategies with zero-downtime cutover.

Migration Scenarios

Instructions

Step 1: Pre-Migration Audit

import { InstantlyClient } from "./src/instantly/client";
const client = new InstantlyClient();

interface MigrationPlan {
  sourceLeadCount: number;
  sourceCampaignCount: number;
  sourceTemplateCount: number;
  emailAccountsToMigrate: string[];
  estimatedDuration: string;
  risks: string[];
}

async function preMigrationAudit(): Promise<MigrationPlan> {
  // Check current Instantly workspace state
  const existingCampaigns = await client.campaigns.list(100);
  const existingAccounts = await client.accounts.list(100);

  console.log("=== Current Instantly Workspace ===");
  console.log(`Campaigns: ${existingCampaigns.length}`);
  console.log(`Accounts: ${existingAccounts.length}`);

  // Check warmup status
  if (existingAccounts.length > 0) {
    const warmup = await client.accounts.warmupAnalytics(
      existingAccounts.map((a) => a.email)
    );
    console.log(`Accounts with warmup: ${(warmup as any[]).length}`);
  }

  console.log("\n=== Migration Checklist ===");
  console.log("[ ] Export leads from source platform (CSV)");
  console.log("[ ] Export campaign templates and sequences");
  console.log("[ ] Document sending schedules and daily limits");
  console.log("[ ] Export analytics/historical data for reference");
  console.log("[ ] Identify email accounts to migrate (IMAP/SMTP creds)");
  console.log("[ ] Map custom fields to Instantly custom_variables");
  console.log("[ ] Create block list from source platform unsubscribes");
  console.log("[ ] Plan warmup period (14+ days for new accounts)");

  return {
    sourceLeadCount: 0, // fill from source audit
    sourceCampaignCount: 0,
    sourceTemplateCount: 0,
    emailAccountsToMigrate: [],
    estimatedDuration: "2 weeks",
    risks: [
      "Warmup period delays campaign launch by 14+ days",
      "Custom field mapping may lose data if not 1:1",
      "Sending reputation doesn't transfer between platforms

Instantly Multi-Environment Setup

Overview

Configure Instantly API v2 integrations across development, staging, and production environments. Instantly uses workspace-level isolation — each workspace has its own accounts, campaigns, leads, and API keys. This skill covers workspace separation, environment-specific configuration, mock server for dev, and safe promotion workflows.

Environment Strategy

Instructions

Step 1: Environment Configuration

// src/config.ts
import "dotenv/config";

type Env = "development" | "staging" | "production";

interface InstantlyConfig {
  env: Env;
  apiKey: string;
  baseUrl: string;
  webhookSecret: string;
  useMock: boolean;
  dailyLimitCap: number;
  enableRealSending: boolean;
}

export function getConfig(): InstantlyConfig {
  const env = (process.env.NODE_ENV || "development") as Env;

  const configs: Record<Env, InstantlyConfig> = {
    development: {
      env: "development",
      apiKey: process.env.INSTANTLY_API_KEY_DEV || "mock-key",
      baseUrl: "https://developer.instantly.ai/_mock/api/v2",
      webhookSecret: "dev-secret",
      useMock: true,
      dailyLimitCap: 5,
      enableRealSending: false,
    },
    staging: {
      env: "staging",
      apiKey: process.env.INSTANTLY_API_KEY_STAGING || "",
      baseUrl: "https://api.instantly.ai/api/v2",
      webhookSecret: process.env.INSTANTLY_WEBHOOK_SECRET_STAGING || "",
      useMock: false,
      dailyLimitCap: 10,
      enableRealSending: true,
    },
    production: {
      env: "production",
      apiKey: process.env.INSTANTLY_API_KEY_PROD || "",
      baseUrl: "https://api.instantly.ai/api/v2",
      webhookSecret: process.env.INSTANTLY_WEBHOOK_SECRET_PROD || "",
      useMock: false,
      dailyLimitCap: 100,
      enableRealSending: true,
    },
  };

  const config = configs[env];
  if (!config.useMock && !config.apiKey) {
    throw new Error(`INSTANTLY_API_KEY_${env.toUpperCase()} is required for ${env}`);
  }

  return config;
}

Step 2: Environment-Specific .env Files

# .env.development
NODE_ENV=development
INSTANTLY_API_KEY_DEV=mock-key
INSTANTLY_BASE_URL=https://developer.inst

Instantly Observability

Overview

Build monitoring and alerting for Instantly integrations. Covers campaign health checks, account warmup monitoring, webhook delivery tracking, deliverability alerts, and performance dashboards. Uses Instantly API v2 analytics endpoints combined with webhook events for real-time awareness.

Prerequisites

• Completed instantly-install-auth setup
• API key with campaigns:read, accounts:read, and all:read scopes
• Notification channel (Slack, email, PagerDuty, etc.)

Instructions

Step 1: Campaign Health Monitor

import { InstantlyClient } from "./src/instantly/client";

const client = new InstantlyClient();

interface HealthCheck {
  check: string;
  status: "ok" | "warning" | "critical";
  message: string;
}

async function campaignHealthCheck(): Promise<HealthCheck[]> {
  const checks: HealthCheck[] = [];
  const campaigns = await client.campaigns.list(100);

  for (const campaign of campaigns.filter((c) => c.status === 1)) { // Active only
    const analytics = await client.campaigns.analytics(campaign.id);
    const sent = analytics.emails_sent || 1;

    // Bounce rate check (critical if > 5%)
    const bounceRate = (analytics.emails_bounced / sent) * 100;
    if (bounceRate > 5) {
      checks.push({
        check: `bounce_rate:${campaign.name}`,
        status: "critical",
        message: `Bounce rate ${bounceRate.toFixed(1)}% exceeds 5% threshold. Campaign may be auto-paused.`,
      });
    } else if (bounceRate > 3) {
      checks.push({
        check: `bounce_rate:${campaign.name}`,
        status: "warning",
        message: `Bounce rate ${bounceRate.toFixed(1)}% approaching 5% threshold.`,
      });
    }

    // Reply rate check (warning if < 1%)
    const replyRate = (analytics.emails_replied / sent) * 100;
    if (replyRate < 1 && sent > 100) {
      checks.push({
        check: `reply_rate:${campaign.name}`,
        status: "warning",
        message: `Reply rate ${replyRate.toFixed(1)}% is below 1% after ${sent} sends. Review email copy.`,
      });
    }

    // Open rate check (warning if < 20%)
    const openRate = (analytics.emails_opened / sent) * 100;
    if (openRate < 20 && sent > 100) {
      checks.push({
        check: `open_rate:${campaign.name}`,
        status: "warning",
        message: `Open rate ${openRate.toFixed(1)}% below 20%. Check subject lines and deliverability.`,
      });
    }
  }

  // Campaign status checks
  const unhealthy = campaigns.filter((c) => c.status === -1);
  const bounceProtected = campaigns.filter((c) => c.status === -2);

  if (unhealthy.length > 0) {
    checks.push({
      check: "unhealthy_campaigns",
      status: "critical",
   

Instantly Performance Tuning

Overview

Optimize Instantly API v2 integrations for speed and throughput. Key areas: caching analytics data, batching lead operations, concurrent request management, efficient pagination, and connection reuse. The email listing endpoint has a strict 20 req/min limit that requires special handling.

Prerequisites

• Completed instantly-install-auth setup
• Working Instantly integration
• Understanding of async patterns and caching strategies

Instructions

Step 1: Cache Analytics Data

Campaign analytics don't change every second — cache them for 5-15 minutes to avoid redundant API calls.

class InstantlyCache {
  private cache = new Map<string, { data: unknown; expiry: number }>();

  get<T>(key: string): T | null {
    const entry = this.cache.get(key);
    if (!entry || Date.now() > entry.expiry) {
      this.cache.delete(key);
      return null;
    }
    return entry.data as T;
  }

  set(key: string, data: unknown, ttlMs: number) {
    this.cache.set(key, { data, expiry: Date.now() + ttlMs });
  }
}

const cache = new InstantlyCache();

async function getCachedAnalytics(campaignId: string) {
  const cacheKey = `analytics:${campaignId}`;
  const cached = cache.get<CampaignAnalytics>(cacheKey);
  if (cached) return cached;

  const data = await instantly<CampaignAnalytics>(
    `/campaigns/analytics?id=${campaignId}`
  );
  cache.set(cacheKey, data, 5 * 60 * 1000); // 5 min TTL
  return data;
}

// Cache campaign list (changes infrequently)
async function getCachedCampaigns() {
  const cacheKey = "campaigns:all";
  const cached = cache.get<Campaign[]>(cacheKey);
  if (cached) return cached;

  const campaigns = await instantly<Campaign[]>("/campaigns?limit=100");
  cache.set(cacheKey, campaigns, 15 * 60 * 1000); // 15 min TTL
  return campaigns;
}

Step 2: Batch Lead Operations with Controlled Concurrency

interface BatchResult<T> {
  succeeded: T[];
  failed: Array<{ input: unknown; error: string }>;
  duration: number;
}

async function batchAddLeads(
  campaignId: string,
  leads: Array<{ email: string; first_name?: string; company_name?: string }>,
  options = { concurrency: 5, delayMs: 200, retries: 3 }
): Promise<BatchResult<Lead>> {
  const start = Date.now();
  const succeeded: Lead[] = [];
  const failed: Array<{ input: unknown; error: string }> = [];
  let active = 0;

  const addWithRetry = async (lead: typeof leads[0]) => {
    for (let attempt = 0; attempt <= options.retries; attempt++) {
      try {
        const result = await instantly<Lead>("/leads", {
          method: "POST",
          body: JSON.stringify({
            campaign: campaignId,
            email: lead.

Instantly Production Checklist

Overview

Pre-flight checklist for launching Instantly cold email campaigns in production. Covers account warmup verification, deliverability testing, lead list hygiene, campaign configuration, webhook setup, and monitoring. Skip any step that doesn't apply to your use case.

Prerequisites

• Completed instantly-install-auth setup
• Email accounts connected and warmed up (minimum 14 days recommended)
• Lead list prepared with verified emails

Production Launch Checklist

Phase 1: Account Health (2-4 weeks before launch)

import { instantly } from "./src/instantly";

async function phase1AccountHealth() {
  console.log("=== Phase 1: Account Health ===\n");

  // 1. Verify all accounts have healthy SMTP/IMAP
  const accounts = await instantly<Array<{ email: string }>>(
    "/accounts?limit=100"
  );
  const vitals = await instantly("/accounts/test/vitals", {
    method: "POST",
    body: JSON.stringify({ accounts: accounts.map((a) => a.email) }),
  }) as Array<{ email: string; smtp_status: string; imap_status: string }>;

  const broken = vitals.filter((v) => v.smtp_status !== "ok" || v.imap_status !== "ok");
  console.log(`Accounts: ${accounts.length} total, ${broken.length} broken`);
  if (broken.length > 0) {
    console.log("FIX THESE FIRST:");
    broken.forEach((v) => console.log(`  ${v.email}: SMTP=${v.smtp_status} IMAP=${v.imap_status}`));
    return false;
  }

  // 2. Verify warmup is active and healthy
  const warmup = await instantly("/accounts/warmup-analytics", {
    method: "POST",
    body: JSON.stringify({ emails: accounts.map((a) => a.email) }),
  }) as Array<{ email: string; warmup_emails_landed_inbox: number; warmup_emails_sent: number }>;

  for (const w of warmup) {
    const inboxRate = (w.warmup_emails_landed_inbox / (w.warmup_emails_sent || 1)) * 100;
    const healthy = inboxRate >= 80;
    console.log(`  ${w.email}: inbox rate ${inboxRate.toFixed(1)}% ${healthy ? "OK" : "LOW — extend warmup"}`);
  }

  // 3. Check daily limits are set
  const acctDetails = await instantly<Array<{ email: string; daily_limit: number | null }>>(
    "/accounts?limit=100"
  );
  const noLimit = acctDetails.filter((a) => !a.daily_limit);
  if (noLimit.length > 0) {
    console.log(`\nWARNING: ${noLimit.length} accounts have no daily limit set`);
  }

  return broken.length === 0;
}

Phase 2: Campaign Configuration (1 week before)

async function phase2CampaignConfig(campaignId: string) {
  console.log("\n=== Phase 2: Campaign Configuration ===\n");
  const campaign = await instantly<{
    name: string;
    sequences: Array<{ ste

Instantly Rate Limits

Overview

Handle Instantly API v2 rate limits. The API returns 429 Too Many Requests when limits are exceeded. Most endpoints follow standard limits. The email listing endpoint has a stricter constraint of 20 requests per minute. Failed webhook deliveries are retried up to 3 times within 30 seconds.

Prerequisites

• Completed instantly-install-auth setup
• Understanding of exponential backoff patterns

Known Rate Limits

Instructions

Step 1: Exponential Backoff with Jitter

import { InstantlyApiError } from "./src/instantly/client";

interface RetryOptions {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

const DEFAULT_RETRY: RetryOptions = {
  maxRetries: 5,
  baseDelayMs: 1000,
  maxDelayMs: 30000,
};

async function withBackoff<T>(
  operation: () => Promise<T>,
  opts: Partial<RetryOptions> = {}
): Promise<T> {
  const { maxRetries, baseDelayMs, maxDelayMs } = { ...DEFAULT_RETRY, ...opts };

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      const isRetryable =
        err instanceof InstantlyApiError &&
        (err.status === 429 || err.status >= 500);

      if (!isRetryable || attempt === maxRetries) throw err;

      // Parse Retry-After header if available
      let delay = baseDelayMs * Math.pow(2, attempt);
      delay = Math.min(delay, maxDelayMs);

      // Add jitter (10-30% of delay)
      const jitter = delay * (0.1 + Math.random() * 0.2);
      const totalDelay = delay + jitter;

      console.warn(
        `Rate limited (attempt ${attempt + 1}/${maxRetries}). Waiting ${Math.round(totalDelay)}ms...`
      );
      await new Promise((r) => setTimeout(r, totalDelay));
    }
  }
  throw new Error("Unreachable");
}

Step 2: Request Queue with Concurrency Control

class RequestQueue {
  private queue: Array<() => Promise<void>> = [];
  private running = 0;
  private readonly maxConcurrent: number;
  private readonly delayBetweenMs: number;

  constructor(maxConcurrent = 5, delayBetweenMs = 200) {
    this.maxConcurrent = maxConcurrent;
    this.delayBetweenMs = delayBetweenMs;
  }

  async add<T&g

Instantly Reference Architecture

Overview

Reference architecture for production Instantly.ai integrations. Covers project layout, API client design, event-driven webhook processing, campaign management, lead pipeline, and analytics dashboard. Designed for teams building outreach automation on top of Instantly API v2.

Architecture Diagram

                                     Instantly API v2
                                    (api.instantly.ai)
                                          |
                    ┌─────────────────────┼─────────────────────┐
                    |                     |                     |
              Campaign Mgmt         Lead Pipeline         Account Mgmt
              (create/launch/       (import/move/          (warmup/
               pause/analytics)      enrich/block)         vitals/pause)
                    |                     |                     |
                    └─────────┬───────────┘                    |
                              |                                |
                    ┌─────────┴─────────┐                     |
                    |   Your Backend    |◄────────────────────┘
                    |  (Node/Python)    |
                    └────────┬──────────┘
                             |
                    ┌────────┴──────────┐
                    |  Webhook Receiver |◄──── Instantly Webhooks
                    |  (Cloud Run /     |      (reply_received,
                    |   Vercel / Fly)   |       email_bounced, etc.)
                    └────────┬──────────┘
                             |
               ┌─────────────┼─────────────┐
               |             |             |
           CRM Sync     Slack Alerts   Analytics DB

Project Layout

instantly-integration/
├── src/
│   ├── instantly/
│   │   ├── client.ts          # API client wrapper with retry + auth
│   │   ├── types.ts           # TypeScript interfaces for API schemas
│   │   ├── pagination.ts      # Cursor-based pagination helpers
│   │   └── cache.ts           # Analytics caching layer
│   ├── campaigns/
│   │   ├── create.ts          # Campaign creation with sequences
│   │   ├── launch.ts          # Campaign activation workflow
│   │   ├── analytics.ts       # Campaign performance tracking
│   │   └── templates.ts       # Email sequence templates
│   ├── leads/
│   │   ├── import.ts          # Lead import from CSV/CRM
│   │   ├── lists.ts           # Lead list management
│   │   ├── enrich.ts          # Lead enrichment pipeline
│   │   └── blocklist.ts       # Block list management
│   ├── accounts/
│   │   ├── warmup.ts          # Warmup enable/disable/monitor
│   │   ├── health.ts          # Account vitals testing
│   │   └── rotation.ts       # Account assignment to campaigns
│   ├── webhooks/
│   │   ├── server.ts          # Express webhook receiver
│   │   ├── handlers.ts        # Event type handlers
│   │   └── validati

Instantly SDK Patterns

Overview

Production-ready patterns for Instantly API v2 integrations. Instantly has no official SDK — all integrations use direct REST calls to https://api.instantly.ai/api/v2/. These patterns provide type safety, retry logic, pagination, and multi-tenant support.

Prerequisites

• Completed instantly-install-auth setup
• Familiarity with async/await and TypeScript generics
• Understanding of REST API pagination patterns

Instructions

Step 1: Type-Safe Client with Error Classification

// src/instantly/client.ts
import "dotenv/config";

export class InstantlyClient {
  private baseUrl: string;
  private apiKey: string;

  constructor(options?: { apiKey?: string; baseUrl?: string }) {
    this.apiKey = options?.apiKey || process.env.INSTANTLY_API_KEY || "";
    this.baseUrl = options?.baseUrl || "https://api.instantly.ai/api/v2";
    if (!this.apiKey) throw new Error("INSTANTLY_API_KEY is required");
  }

  async request<T>(path: string, options: RequestInit = {}): Promise<T> {
    const url = `${this.baseUrl}${path}`;
    const res = await fetch(url, {
      ...options,
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.apiKey}`,
        ...options.headers,
      },
    });

    if (!res.ok) {
      const body = await res.text();
      throw new InstantlyApiError(res.status, path, body);
    }

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

  // Typed convenience methods
  async getCampaigns(params?: { limit?: number; status?: number; search?: string }) {
    const qs = new URLSearchParams();
    if (params?.limit) qs.set("limit", String(params.limit));
    if (params?.status !== undefined) qs.set("status", String(params.status));
    if (params?.search) qs.set("search", params.search);
    return this.request<Campaign[]>(`/campaigns?${qs}`);
  }

  async getCampaign(id: string) {
    return this.request<Campaign>(`/campaigns/${id}`);
  }

  async createCampaign(data: CreateCampaignInput) {
    return this.request<Campaign>("/campaigns", {
      method: "POST",
      body: JSON.stringify(data),
    });
  }

  async activateCampaign(id: string) {
    return this.request<void>(`/campaigns/${id}/activate`, { method: "POST" });
  }

  async pauseCampaign(id: string) {
    return this.request<void>(`/campaigns/${id}/pause`, { method: "POST" });
  }

  async getAccounts(params?: { limit?: number; status?: number }) {
    const qs = new URLSearchParams();
    if (params?.limit) qs.set("limit", String(params.limit));
    if (params?.status !== undefined) qs.set("status", String(params.status));
    return this.request<Account[]>(`/accounts?${qs}`);
  

Instantly Security Basics

Overview

Secure your Instantly.ai integration with scoped API keys, least-privilege access, secret management, webhook validation, and audit logging. Instantly API v2 uses Bearer token auth with granular scope-based permissions.

Prerequisites

• Instantly account with API access
• Understanding of environment variable management
• Access to Instantly dashboard Settings > Integrations

Instructions

Step 1: Least-Privilege API Key Scopes

Create separate API keys for different use cases with minimal required scopes.

// Key scopes follow the pattern: resource:action
// resource = campaigns, accounts, leads, etc.
// action = read, update, all

// Read-only analytics dashboard
// Scopes needed: campaigns:read, accounts:read
const ANALYTICS_KEY_SCOPES = ["campaigns:read", "accounts:read"];

// Campaign automation bot
// Scopes needed: campaigns:all, leads:all
const AUTOMATION_KEY_SCOPES = ["campaigns:all", "leads:all"];

// Webhook-only integration
// Scopes needed: leads:read (to look up lead data on events)
const WEBHOOK_KEY_SCOPES = ["leads:read"];

// AVOID: all:all gives unrestricted access — dev/test only

Step 2: Secret Management

// NEVER hardcode API keys
// BAD:
const client = new InstantlyClient({ apiKey: "sk_live_abc123" });

// GOOD: environment variables
const client = new InstantlyClient({
  apiKey: process.env.INSTANTLY_API_KEY!,
});

// BETTER: secret manager integration
import { SecretManagerServiceClient } from "@google-cloud/secret-manager";

async function getApiKey(): Promise<string> {
  const client = new SecretManagerServiceClient();
  const [version] = await client.accessSecretVersion({
    name: "projects/my-project/secrets/instantly-api-key/versions/latest",
  });
  return version.payload?.data?.toString() || "";
}

# .gitignore — always exclude secrets
.env
.env.*
*.key

Step 3: API Key Rotation

// Instantly supports multiple API keys — rotate without downtime

async function rotateApiKey() {
  

Instantly Upgrade Migration: API v1 to v2

Overview

Migrate from Instantly API v1 (deprecated January 2026) to API v2. Key changes: Bearer token auth replaces query-string API keys, REST-standard endpoints replace legacy paths, scoped API keys replace single global key, and cursor-based pagination replaces offset pagination. Existing v1 integrations via Zapier/Make continue working, but new integrations must use v2.

Prerequisites

• Existing Instantly API v1 integration
• Access to Instantly dashboard to generate v2 API keys
• Understanding of Bearer token authentication

Migration Map

Authentication Change

// v1: API key as query parameter
// DEPRECATED — do not use
const v1Url = `https://api.instantly.ai/api/v1/campaign/list?api_key=${API_KEY}`;

// v2: Bearer token in Authorization header
const v2Response = await fetch("https://api.instantly.ai/api/v2/campaigns", {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

Endpoint Migration Table

Request Body Changes

// v1: Campaign creation
const v1Body = {
  api_key: "your-key",
  name: "Campaign Name",
  // Flat structure
};

// v2: Campaign creation — structure

Instantly Webhooks & Events

Overview

Handle Instantly API v2 webhooks for real-time email outreach event notifications. Instantly fires events when emails are sent, opened, clicked, replied to, or bounced, and when leads change interest status. Webhooks require Hypergrowth plan ($97/mo) or higher. Delivery retries: 3 times within 30 seconds on failure.

Prerequisites

• Instantly Hypergrowth plan or higher (required for webhooks)
• API key with all:all or appropriate webhook scopes
• Public HTTPS endpoint for receiving webhook payloads
• INSTANTLY_API_KEY environment variable set

Webhook Event Types