Instantly

Access the Instantly API v2 with managed authentication. Manage cold email campaigns, leads, sending accounts, and view analytics.

Reference

List Campaigns

GET /instantly/api/v2/campaigns?limit=10&status=1&search=keyword

Query parameters:

limit - Number of results (default: 10)
status - Campaign status filter (0=draft, 1=active, 2=paused, 3=completed)
search - Search by campaign name
starting_after - Cursor for pagination

Get Campaign

GET /instantly/api/v2/campaigns/{campaign_id}

Create Campaign

POST /instantly/api/v2/campaigns
Content-Type: application/json

{
  "name": "My Campaign",
  "campaign_schedule": {
    "schedules": [
      {
        "name": "My Schedule",
        "timing": {
          "from": "09:00",
          "to": "17:00"
        },
        "days": {
          "0": true,
          "1": true,
          "2": true,
          "3": true,
          "4": true
        },
        "timezone": "Etc/GMT+5"
      }
    ]
  }
}

Note: Timezone must use Etc/GMT format (e.g., "Etc/GMT+5", "Etc/GMT-8", "Etc/GMT+12").

Activate Campaign

POST /instantly/api/v2/campaigns/{campaign_id}/activate

Pause Campaign

POST /instantly/api/v2/campaigns/{campaign_id}/pause

Delete Campaign

DELETE /instantly/api/v2/campaigns/{campaign_id}

Search Campaigns by Lead Email

GET /instantly/api/v2/campaigns/search-by-contact?search=lead@example.com

Create Lead

POST /instantly/api/v2/leads
Content-Type: application/json

{
  "campaign_id": "019bb3bd-9963-789e-b776-6c6927ef3f79",
  "email": "lead@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Inc",
  "variables": {
    "custom_field": "custom_value"
  }
}

Bulk Add Leads

POST /instantly/api/v2/leads
Content-Type: application/json

{
  "campaign_id": "019bb3bd-9963-789e-b776-6c6927ef3f79",
  "leads": [
    {
      "email": "lead1@example.com",
      "first_name": "John"
    },
    {
      "email": "lead2@example.com",
      "first_name": "Jane"
    }
  ]
}

List Leads

Note: This is a POST endpoint due to complex filtering requirements.

POST /instantly/api/v2/leads/list
Content-Type: application/json

{
  "campaign_id": "019bb3bd-9963-789e-b776-6c6927ef3f79",
  "limit": 100
}

Get Lead

GET /instantly/api/v2/leads/{lead_id}

Delete Lead

DELETE /instantly/api/v2/leads/{lead_id}

Move Leads

POST /instantly/api/v2/leads/move
Content-Type: application/json

{
  "lead_ids": ["lead_id_1", "lead_id_2"],
  "to_campaign_id": "target_campaign_id"
}

List Lead Lists

GET /instantly/api/v2/lead-lists?limit=10

Create Lead List

POST /instantly/api/v2/lead-lists
Content-Type: application/json

{
  "name": "My Lead List"
}

Get Lead List

GET /instantly/api/v2/lead-lists/{list_id}

Update Lead List

PATCH /instantly/api/v2/lead-lists/{list_id}
Content-Type: application/json

{
  "name": "Updated List Name"
}

Delete Lead List

DELETE /instantly/api/v2/lead-lists/{list_id}

List Accounts

GET /instantly/api/v2/accounts?limit=10

Get Account

GET /instantly/api/v2/accounts/{email}

Create Account

POST /instantly/api/v2/accounts
Content-Type: application/json

{
  "email": "sender@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "provider_code": "google",
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "smtp_username": "sender@example.com",
  "smtp_password": "app_password",
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "imap_username": "sender@example.com",
  "imap_password": "app_password"
}

Update Account

PATCH /instantly/api/v2/accounts/{email}
Content-Type: application/json

{
  "first_name": "Jane"
}

Delete Account

DELETE /instantly/api/v2/accounts/{email}

Enable Warmup

POST /instantly/api/v2/accounts/warmup/enable
Content-Type: application/json

{
  "emails": ["account1@example.com", "account2@example.com"]
}

Disable Warmup

POST /instantly/api/v2/accounts/warmup/disable
Content-Type: application/json

{
  "emails": ["account1@example.com"]
}

List Emails

GET /instantly/api/v2/emails?limit=20

Get Email

GET /instantly/api/v2/emails/{email_id}

Reply to Email

POST /instantly/api/v2/emails/reply
Content-Type: application/json

{
  "reply_to_uuid": "email_uuid",
  "body": "Thank you for your response!"
}

Forward Email

POST /instantly/api/v2/emails/forward
Content-Type: application/json

{
  "email_uuid": "email_uuid",
  "to": "forward@example.com"
}

Mark Thread as Read

POST /instantly/api/v2/emails/threads/{thread_id}/mark-as-read

Get Unread Count

GET /instantly/api/v2/emails/unread/count

Update Email

PATCH /instantly/api/v2/emails/{email_id}
Content-Type: application/json

{
  "is_read": true
}

Delete Email

DELETE /instantly/api/v2/emails/{email_id}

Get Campaign Analytics

GET /instantly/api/v2/campaigns/analytics?id={campaign_id}

Query parameters:

id - Campaign ID (leave empty for all campaigns)
start_date - Filter start date (YYYY-MM-DD)
end_date - Filter end date (YYYY-MM-DD)
exclude_total_leads_count - Set to true for faster response

Get Campaign Analytics Overview

GET /instantly/api/v2/campaigns/analytics/overview?id={campaign_id}

Get Daily Campaign Analytics

GET /instantly/api/v2/campaigns/analytics/daily?id={campaign_id}

Get Campaign Step Analytics

GET /instantly/api/v2/campaigns/analytics/steps?id={campaign_id}

Get Warmup Analytics

POST /instantly/api/v2/accounts/warmup/analytics
Content-Type: application/json

{
  "emails": ["account@example.com"]
}

List Block List Entries

GET /instantly/api/v2/block-lists-entries?limit=100

Query parameters:

domains_only - Filter to domain entries only
search - Search entries

Create Block List Entry

POST /instantly/api/v2/block-lists-entries
Content-Type: application/json

{
  "bl_value": "blocked@example.com"
}

Or block a domain:

POST /instantly/api/v2/block-lists-entries
Content-Type: application/json

{
  "bl_value": "blockeddomain.com"
}

Delete Block List Entry

DELETE /instantly/api/v2/block-lists-entries/{entry_id}

Verify Email

GET /instantly/api/v2/email-verification/{email}

If verification takes longer than 10 seconds, status will be pending. Poll this endpoint to check status.

Response fields:

verification_status - Use this field (not status) to determine verification result

Get Background Job Status

GET /instantly/api/v2/background-jobs/{job_id}

Query parameters:

data_fields - Comma-separated fields (e.g., success_count,failed_count,total_to_process)

Get Current Workspace

GET /instantly/api/v2/workspaces/current

Toggle Tag on Resource

POST /instantly/api/v2/custom-tags/toggle-resource
Content-Type: application/json

{
  "tag_id": "tag_uuid",
  "resource_id": "campaign_or_account_id",
  "resource_type": "campaign"
}

Instantly

On this page