Skip to main content
Integrations with email sequencing platforms for sending multi-touch outbound campaigns.

​
Instantly API

Instantly is a cold email automation platform for managing campaigns, uploading leads, and tracking engagement.

​
Base Configuration

​
Base URL
string
https://api.instantly.ai/api/v2
​
Authentication
header
Authorization: Bearer YOUR_API_KEY
Get your API key from the Instantly dashboard.

​
Rate Limits

  • 10 requests per second
  • 100 leads per upload request
  • Add 0.5s pause between consecutive uploads

​
Campaign Management

​
List Campaigns

GET /campaigns?limit=100&skip=0
​
items
array
Array of campaign objects
[
  {
    "id": "campaign-uuid",
    "name": "Campaign Name",
    "status": "active"
  }
]
Status values: active, paused, draft, completed

​
Create Campaign

POST /campaigns
​
name
string
required
Campaign nameExample: “PE Rollup - Blue Collar - 2026-03”
Response: 
{
  "id": "campaign-uuid",
  "name": "PE Rollup - Blue Collar - 2026-03"
}

​
Get Campaign

GET /campaigns/{campaign_id}
Returns detailed campaign information including settings and sequences.

​
Lead Management

​
Upload Leads

POST /leads
​
campaign_id
string
required
Target campaign UUID
​
skip_if_in_workspace
boolean
Skip if email exists in ANY campaign across workspaceDefault: false
​
skip_if_in_campaign
boolean
Skip only if email exists in THIS campaignDefault: false
​
leads
array
required
Array of lead objects (max 100 per request)
[
  {
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "company_name": "Acme Corp",
    "website": "acme.com",
    "personalization": "First paragraph text here",
    "custom_variables": {
      "second_paragraph": "...",
      "third_paragraph": "...",
      "fourth_paragraph": "...",
      "hypothesis": "Database blind spot"
    }
  }
]

​
Lead Object Fields

​
email
string
required
Lead email address
​
first_name
string
Lead first name
​
last_name
string
Lead last name
​
company_name
string
Company name
​
website
string
Company website
​
personalization
string
First paragraph personalization textMaps to {{personalization}} variable in email templates
​
custom_variables
object
Additional template variablesCommon fields:
  • second_paragraph
  • third_paragraph
  • fourth_paragraph
  • hypothesis
All custom variables are accessible as {{variable_name}} in templates

​
Response

​
uploaded
integer
Number of leads successfully uploaded
​
skipped
integer
Number of leads skipped due to deduplication
{
  "uploaded": 95,
  "skipped": 5
}

​
List Leads in Campaign

GET /leads?campaign_id={id}&limit=100&skip=0
Returns paginated list of leads in a campaign.

​
Delete Lead

DELETE /leads/{lead_id}
Removes a lead from the campaign.

​
Campaign Analytics

​
Get Campaign Summary

GET /campaigns/{campaign_id}/analytics/overview
​
total_leads
integer
Total leads in campaign
​
contacted
integer
Number of leads contacted
​
emails_sent
integer
Total emails sent (including follow-ups)
​
opens
integer
Number of email opens
​
replies
integer
Number of replies received
​
bounces
integer
Number of bounced emails
​
unsubscribes
integer
Number of unsubscribes
Example response: 
{
  "total_leads": 500,
  "contacted": 450,
  "emails_sent": 1200,
  "opens": 380,
  "replies": 42,
  "bounces": 15,
  "unsubscribes": 3
}

​
Filter Leads by Status

GET /leads?campaign_id={id}&status=replied
Status values:
  • not_yet_contacted
  • contacted
  • replied
  • bounced
  • unsubscribed
  • interested
  • not_interested
  • meeting_booked

​
Email Account Management

​
List Email Accounts

GET /email-accounts?limit=100
Returns all email accounts connected to workspace.

​
Check Warmup Status

GET /email-accounts/{account_id}
Check warmup status and reputation score for an email account. Response fields:
  • warmup_status: Current warmup state
  • reputation_score: Email deliverability score

​
Email Template Variables

When creating email sequences in the Instantly dashboard, reference these variables:

​
Standard Variables

{{first_name}}       → Lead first name
{{last_name}}        → Lead last name
{{company_name}}     → Company name
{{website}}          → Company website

​
Personalization Variables

{{personalization}}  → First paragraph (maps to lead.personalization)
{{second_paragraph}} → From custom_variables
{{third_paragraph}}  → From custom_variables
{{fourth_paragraph}} → From custom_variables

​
Typical Email Template Structure

Hey {{first_name}},

{{personalization}}

{{second_paragraph}}

{{third_paragraph}}

{{fourth_paragraph}}

Best,
Your name
This maps to the P1-P4 paragraph structure used in GTM Skills email generation.

​
Deduplication Options

Instantly provides flexible deduplication:
​
skip_if_in_workspace
boolean
default:false
Skip if email exists anywhere in workspaceUse when: You never want to email the same person twice across all campaigns
​
skip_if_in_campaign
boolean
default:false
Skip only if email exists in this specific campaignUse when: You want to allow the same person in different campaigns
​
Default (both false)
behavior
Always upload, even if duplicateUse when: Testing or intentionally re-uploading

​
Best Practices

​
Batch Upload Strategy

  1. Split large lists into batches of 100 leads
  2. Add 0.5s delay between requests
  3. Track uploaded vs skipped counts
  4. Log any failed uploads for retry

​
Rate Limit Handling

// Pseudo-code for batch upload
for (const batch of leadBatches) {
  await uploadLeads(batch);
  await sleep(500); // 0.5s delay
}

​
Variable Naming

Match custom variable keys in API payload to template variable names:
  • API: custom_variables.second_paragraph
  • Template: {{second_paragraph}}

Build docs developers (and LLMs) love

Get started for freeTalk to us