# Instantly Hello World

> Instantly Hello World is an Agent Skill for apps & automation published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create a minimal working Instantly.ai example with real API calls. Use when starting a new Instantly integration, testing your setup, or learning basic Instantly API v2 patterns. Trigger with phrases like "instantly hello world", "instantly example", "instantly quick start", "simple instantly code", "test instantly api".

- Skill name: `instantly-hello-world`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/instantly-pack/skills/instantly-hello-world/SKILL.md
- Repository: jeremylongshore/claude-code-plugins-plus-skills (2,518 GitHub stars when collected)

## SKILL.md

# 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

```typescript
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

```typescript
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

```typescript
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).toFixed(1)}%)`);
  console.log(`  Bounced: ${stats.emails_bounced}`);
}
```

### Step 4: Run It All

```typescript
async function main() {
  console.log("=== Instantly API v2 Hello World ===\n");

  const campaigns = await listCampaigns();
  await checkAccounts();

  if (campaigns.length > 0) {
    await getAnalytics(campaigns[0].id);
  }

  console.log("\nDone! Your Instantly connection is working.");
}

main().catch(console.error);
```

### Quick Test with curl

```bash
set -euo pipefail
# List campaigns
curl -s https://api.instantly.ai/api/v2/campaigns?limit=3 \
  -H "Authorization: Bearer $INSTANTLY_API_KEY" | jq '.[] | {name, status, id}'

# List email accounts
curl -s https://api.instantly.ai/api/v2/accounts?limit=3 \
  -H "Authorization: Bearer $INSTANTLY_API_KEY" | jq '.[] | {email, status}'
```

## Output

- List of campaigns with names and statuses
- Email account health overview
- Campaign analytics summary (open rate, reply rate, bounce count)
- Confirmation that Instantly API v2 is reachable

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `401 Unauthorized` | Bad API key | Regenerate in Settings > Integrations |
| `403 Forbidden` | Missing `campaigns:read` scope | Edit API key scopes |
| Empty campaign list | No campaigns created yet | Create one in the Instantly dashboard first |
| `429 Too Many Requests` | Rate limited | Wait and retry with backoff |

## Resources

- [Instantly API v2 Docs](https://developer.instantly.ai/)
- Campaign Endpoints
- Account Endpoints

## Next Steps

Proceed to `instantly-core-workflow-a` to build a full campaign launch workflow.

---

Source: https://www.openparable.com/skill/apps-automation/instantly-hello-world (OpenParable). Cite the canonical URL above.
