Configuration
Create a v2 key in your workspace’s API settings. Keys are scoped to a workspace;
select the permissions needed for your resources. Requests use
https://api.instantly.ai/api/v2. See the
Instantly quickstart.
Connection testing lists campaigns, so the key needs campaign-read access even
when you select other resources.
Optional resources require their endpoint-specific scopes and any associated
account features. For example, audit logs require
audit_logs:read, billing
requires workspace_billing:read, and workspace members require
workspace_members:read. AI endpoints have distinct scopes: some accept
ai_agents:read, while others require ai_sdr:read, ai_sdr_replies:read,
ai_inbox_manager_analytics:read, or broader access. Consult the
endpoint reference for each selected
resource rather than granting administrative access for the core defaults.
Resources
Campaigns, accounts, leads, lead lists, and emails are selected by default. All other resources are optional. Only selected resources are written, although child reads also fetch their parents to discover IDs.
Campaigns include schedules and sequences. Lead custom data is retained in
payload and raw. Email reads request full bodies, all inbox modes, and all
messages rather than only the latest message of each thread. Account reads
include tags. No status, campaign, or lead-list filter is applied to core reads.
AI Sales Agent campaigns are explicitly included in campaigns.
Nested data stays in JSON columns, IDs are strings, and declared date-time fields
use timestamps with time zones. Every resource includes a raw column for
returned fields that are not projected separately. Warmup analytics retain the
provider’s maps of account and date metrics in a snapshot for each account.
This version does not include API-key data, background-job tracking, DFY mailbox
credentials, domain administration, OAuth connection flows, individual email
verification lookups, AI Deliverability Agents, company-list builders and members,
or SuperSearch enrichment execution/history. Some AI detail and additional
analytics endpoints are also outside this version. It reads saved searches and
the listed AI resources; it does not run agents, start tests, buy domains, send
emails, create exports, or receive webhook events. Attachments remain metadata.
Modes
All resources use full reads. Although several records contain update timestamps, their list endpoints do not expose a corresponding update-time filter. Email creation filters would miss later changes to read flags, status, and other fields. A pagination cursor is used only to walk the current result set; it is not an incremental watermark. Use full upsert for keyed resources, or full replace to remove rows no longer returned by Instantly. The following resources have no stable primary key declared and require full replace:dfy_email_account_orders, workspace_plan, workspace_subscription, account_campaign_mappings, account_warmup_analytics, account_daily_analytics, campaign_analytics_overview, campaign_steps_analytics, subsequence_analytics, subsequence_steps_analytics, ai_sales_analytics, ai_sales_opportunities, ai_inbox_analytics, ai_lead_finder_stats.
Behavior
- Auth: every request uses the workspace’s v2 API key as a Bearer token. Missing scopes, unavailable features, and other upstream errors fail the read.
- Pagination: list resources request up to 100 rows, respecting lower endpoint
maxima, and pass
next_starting_afterinto the next request. Pagination ends when that cursor is absent, empty, or null. For leads, the cursor and limit are JSON body fields on the read-onlyPOST /leads/listrequest. - Rate limiting: email listing is limited to 20 requests per minute. This connector uses a shared limit of 0.3 requests per second (18 per minute), which also slows other resources. The workspace-wide limits are 100 requests per second and 6,000 per minute, shared with other clients. HTTP 429 responses are retried; the limiter cannot reserve capacity against other integrations. See email listing and rate limits.
- Analytics: no date bounds are supplied, so endpoints use their provider defaults. Campaign daily and step analytics are requested per campaign. These are refreshed snapshots, not append-only events. Overview interest metrics use the provider’s first-occurrence behavior.
- Ordering: lead results use the provider’s cursor. Instantly notes that leads created before October 15, 2025 may not appear chronologically when sorted by ID.
- Recovery: top-level cursor reads can resume interrupted walks. Child reads restart from their parent listings. Deletes are reconciled through full replace, not emitted as deletion events.