Instantly

Routing layer for Instantly v2 API work. WHAT/guardrails here; HOW in reference/endpoints.md (all 167 ops, generated from the OpenAPI spec) and the Python client lib/instantly.py.

1) Auth & config

• Base URL: https://api.instantly.ai (all v2 paths under /api/v2/...)
• Auth: Authorization: Bearer <API_KEY> — v2 key from Instantly → Settings → API.
• Secret: read from env INSTANTLY_API_KEY; never hardcode. Client raises if missing.
• Spec of record: https://api.instantly.ai/openapi/api_v2.json (167 ops, 30 schemas). Regenerate reference/endpoints.md from it when the API changes.

2) Conventions the spec revealed (don't trip on these)

• list_leads is POST /api/v2/leads/list with a filter body — not a GET.
• Bulk add is POST /api/v2/leads/add; move is POST /api/v2/leads/move.
• Cursor pagination: limit + starting_after; responses carry next_starting_after. The client's _paginate follows it (cursor in query for GET lists, in body for leads/list).
• Editing is PATCH /…/{id}. Activate/pause are POST /campaigns/{id}/activate|pause.
• Endpoints require scopes (e.g. campaigns:create, all:all) — your key must have them.

3) Approval gates (sending is real)

Instantly sends cold email. Treat these as irreversible, approval-gated actions:

1. activate_campaign starts/resumes sending immediately.
2. add_leads_bulk into an active campaign feeds people into live sending.
3. Bulk writes: pilot ONE lead/record first, show the user the request + response, get explicit go-ahead before the full batch. Default to building in a paused campaign or a lead-list, then activating only on confirmation.

4) Operations covered by the client

Typed methods for the recruiting/outreach core: campaigns (list/get/create/patch/delete/ activate/pause), campaign analytics (analytics / overview / daily), leads (create/list/get/patch/ add_bulk/move/update_interest_status), lead-lists (list/create), webhooks (list/create/delete/ event-types). For anything else in the 167-op surface, use the generic request(method, path, …) passthrough and consult reference/endpoints.md.

5) Handoff with the GTM/enrichment layer

Canonical flow: source + enrich leads (your sourcing/enrichment adapters) into a CSV → map rows to Instantly lead fields → create_lead_list → add_leads_bulk(list_id=…) → review → add_leads_bulk into a campaign (or move) → activate_campaign only after approval. Never read large CSVs into context.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

• Resolve campaign IDs from list_campaigns before any add.
• Timezone on create_campaign: don't brute-force guesses; reuse a known-good timezone from an existing campaign (get_campaign). Literal UTC is unsupported - map to a supported equivalent; e.g. use America/Detroit where the user asks for America/New_York if the exact value is rejected.
• Schedule days: numeric keys "0".."6" (sunday..saturday); out-of-range rejected.
• list_leads filters: accepts campaign/campaign_id (alias), plus list_id, in_campaign, in_list, search; omit all to list globally. (Our adapter: list_leads is POST /api/v2/leads/list.)
• Insert in controlled batches; re-check stats after writes; keep activation behind verification gates.

Callable surface — lib/instantly.py

Import: from lib.instantly import Instantly → instantiate Instantly() (reads key from env). Base: https://api.instantly.ai. Generic passthrough: request(method, path, *, params, json).

• activate_campaign(campaign_id: str) -> dict — POST /api/v2/campaigns/{id}/activate — starts/resumes sending (outreach!).
• add_leads_bulk(leads: list[dict], campaign_id: str | None = None, list_id: str | None = None, **extra) -> dict — POST /api/v2/leads/add — add leads in bulk to a campaign OR list.
• create_campaign(payload: dict) -> dict — POST /api/v2/campaigns. See reference/endpoints.md + schemas/campaign for body.
• create_lead(payload: dict) -> dict
• create_lead_list(payload: dict) -> dict
• create_webhook(payload: dict) -> dict
• delete_campaign(campaign_id: str) -> dict
• delete_webhook(webhook_id: str) -> dict
• get_campaign(campaign_id: str) -> dict
• get_campaign_analytics(**params) -> Any
• get_campaign_analytics_overview(**params) -> Any
• get_daily_campaign_analytics(**params) -> Any
• get_lead(lead_id: str) -> dict
• list_campaigns(**filters) -> Iterator[dict] — GET /api/v2/campaigns (cursor-paginated).
• list_lead_lists(**filters) -> Iterator[dict]
• list_leads(filters: dict | None = None) -> Iterator[dict] — POST /api/v2/leads/list — NOTE: list is a POST with a filter body (cursor-paginated).
• list_webhook_event_types() -> Any
• list_webhooks(**filters) -> Iterator[dict]
• move_leads(payload: dict) -> dict — POST /api/v2/leads/move — move leads to a campaign or list.
• patch_campaign(campaign_id: str, payload: dict) -> dict
• patch_lead(lead_id: str, payload: dict) -> dict
• pause_campaign(campaign_id: str) -> dict
• update_lead_interest_status(payload: dict) -> dict