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.emai

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<{ steps: 

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() {
  con

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 — structured sche

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
• INSTANTLYAPIKEY environment variable set

Webhook Event Types