Instantly CI Integration Skill

Instantly CI Integration

Overview

Set up CI/CD pipelines for Instantly API v2 integrations. Covers GitHub Actions workflows for testing against the Instantly mock server, validating API key scopes, and deploying webhook receivers. Uses the mock server at https://developer.instantly.ai/_mock/api/v2/ so CI runs don't send real emails or consume production API limits.

Prerequisites

GitHub repository with Instantly integration code
INSTANTLY_API_KEY secret in GitHub repo settings (for production tests)
Node.js 18+ or Python 3.10+ in the project

Instructions

Step 1: GitHub Actions Workflow

# .github/workflows/instantly-ci.yml
name: Instantly Integration CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

env:
  INSTANTLY_USE_MOCK: "true"
  INSTANTLY_BASE_URL: "https://developer.instantly.ai/_mock/api/v2"

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - run: npm ci

      - name: Type check
        run: npx tsc --noEmit

      - name: Lint
        run: npx eslint src/ --ext .ts

      - name: Unit tests (mock server)
        run: npx vitest run --reporter=verbose
        env:
          INSTANTLY_API_KEY: "mock-key-for-ci"
          INSTANTLY_USE_MOCK: "true"

      - name: Validate API client types
        run: npx tsx scripts/validate-types.ts

  integration-test:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - run: npm ci

      - name: Integration tests (live API, read-only)
        run: npx vitest run tests/integration/ --reporter=verbose
        env:
          INSTANTLY_API_KEY: ${{ secrets.INSTANTLY_API_KEY }}
          INSTANTLY_BASE_URL: "https://api.instantly.ai/api/v2"

Step 2: API Scope Validation Script

// scripts/validate-types.ts
// Verifies the API client types match expected Instantly v2 schema

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

async function validateApiAccess() {
  const client = new InstantlyClient();

  // Validate read-only operations work
  const campaigns = await client.getCampaigns({ limit: 1 });
  console.log("campaigns: OK");

  const accounts = await client.getAccounts({ limit: 1 });
  console.log("accounts: OK");

  console.log("All API validations passed");
}

validateApiAccess().catch((err) => {
  console.error("Validation failed:", err.message);
  process.exit(1);
});

Step 3: Integration Test Suite

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

const client = new InstantlyClient();

describe("Instantly API v2 Integration", () => {
  it("should authenticate and list campaigns", async () => {
    const campaigns = await client.getCampaigns({ limit: 5 });
    expect(Array.isArray(campaigns)).toBe(true);
  });

  it("should list email accounts", async () => {
    const accounts = await client.getAccounts({ limit: 5 });
    expect(Array.isArray(accounts)).toBe(true);
  });

  it("should fetch campaign analytics", async () => {
    const campaigns = await client.getCampaigns({ limit: 1 });
    if (campaigns.length > 0) {
      const analytics = await client.getCampaignAnalytics([campaigns[0].id]);
      expect(Array.isArray(analytics)).toBe(true);
    }
  });

  it("should handle 401 on invalid key", async () => {
    const badClient = new InstantlyClient({ apiKey: "invalid-key" });
    await expect(badClient.getCampaigns({ limit: 1 })).rejects.toThrow();
  });

  it("should create and delete a lead list", async () => {
    const list = await client.request<{ id: string }>("/lead-lists", {
      method: "POST",
      body: JSON.stringify({ name: `ci-test-${Date.now()}` }),
    });
    expect(list.id).toBeDefined();

    await client.request(`/lead-lists/${list.id}`, { method: "DELETE" });
  });
});

Step 4: Deployment Workflow

# .github/workflows/deploy.yml
name: Deploy Instantly Integration

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - run: npm ci && npm run build

      - name: Deploy webhook receiver
        uses: google-github-actions/deploy-cloudrun@v2
        with:
          service: instantly-webhooks
          region: us-central1
          image: gcr.io/${{ secrets.GCP_PROJECT }}/instantly-webhooks
          env_vars: |
            INSTANTLY_API_KEY=${{ secrets.INSTANTLY_API_KEY }}
            INSTANTLY_WEBHOOK_SECRET=${{ secrets.INSTANTLY_WEBHOOK_SECRET }}

      - name: Verify deployment
        run: |
          curl -s -o /dev/null -w "%{http_code}" \
            https://instantly-webhooks-abc123.run.app/health | \
            grep -q "200" && echo "Deploy OK" || exit 1

Step 5: Pre-Commit Hook

#!/bin/bash
# .husky/pre-commit
set -euo pipefail

# Prevent committing API keys
if grep -rn "Bearer [a-zA-Z0-9_-]\{20,\}" src/ --include="*.ts" --include="*.js" 2>/dev/null; then
  echo "ERROR: Possible API key found in source code"
  exit 1
fi

# Type check
npx tsc --noEmit

# Run unit tests
npx vitest run --reporter=dot

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | CI fails on mock server | Mock schema doesn't match code | Update types to match v2 schema | | Integration tests 401 | Secret not set in GitHub | Add INSTANTLY_API_KEY to repo secrets | | Rate limited in CI | Too many parallel runs | Use mock server for PR checks | | Deploy fails | Missing env vars | Check secrets are set in deployment target |

Resources

Next Steps

For deployment to cloud platforms, see instantly-deploy-integration.

Agent Skills: Instantly CI Integration

Install this agent skill to your local

Skill Files