b2b-cold-email

Instantly Cold Email (API v2)

Create and manage Instantly.ai cold outreach campaigns: sequences, leads, sending accounts.

Many "intuitive" details are wrong. Every gotcha in Common pitfalls is something this skill author hit on a live campaign. Read that section first when something doesn't work.

API basics

• Base URL: https://api.instantly.ai/api/v2
• Auth: Authorization: Bearer $INSTANTLY_API_KEY
• Key location: env var INSTANTLY_API_KEY (Instantly → Settings → Integrations → API; never hardcode)
• Rate limit: 10 req/sec total. For bulk ops (>1000 leads) throttle to ~5 RPS.
• Pagination: cursor starting_after + next_starting_after in response.

INST_KEY=$INSTANTLY_API_KEY

Campaign creation workflow

1. Confirm sending account ready (/accounts) — daily_limit, stat_warmup_score.
2. Create campaign (POST /campaigns) with sequences + schedule.
3. Upload leads with custom vars (POST /leads/add).
4. Verify lead-campaign binding (via /leads/list search filter).
5. User activates (POST /campaigns/{id}/activate) — never auto-activate.

1) Create campaign

payload = {
  "name": "Cold — Offer A — 2026-05",
  "email_list": ["[email protected]"],
  "campaign_schedule": {
    "schedules": [{
      "name": "BC weekday hours",
      "timing": {"from": "09:00", "to": "17:00"},
      "days":   {"1": True, "2": True, "3": True, "4": True, "5": True},
      "timezone": "America/Dawson"
    }]
  },
  "sequences": [{
    "steps": [
      {"type":"email","delay":3,"variants":[{"subject":"{{subjectLine}}","body": STEP1_HTML}]},
      {"type":"email","delay":3,"variants":[{"subject":"",               "body": STEP2_HTML}]},
      {"type":"email","delay":0,"variants":[{"subject":"",               "body": STEP3_HTML}]}
    ]
  }]
}
requests.post(f"{API}/campaigns", headers=H, json=payload)

Key points:

• campaign_schedule is an object {schedules: [...]}, not a bare array. Inner: timing.from/to (24h "HH:MM"), days is a {"1": true, ...} dict (Monday=1), timezone (see timezone whitelist).
• type is lowercase "email" (uppercase 400s).
• Subject + body live inside variants: [{subject, body}], not flat on the step.
• delay semantics — see step delay below. Set delay on the LAST step to 0; setting first step delay to 0 fires step 2 immediately = duplicate spam.
• Empty subject: "" on follow-up steps = reply thread (same subject as step 1).
• Only sequences[0] is used. Don't add more.