Get Campaign Leads

# Get replied leads
curl "https://server.smartlead.ai/api/v1/campaigns/123/leads?api_key=YOUR_KEY&emailStatus=is_replied&limit=100"

import requests
from datetime import datetime, timedelta

API_KEY = "YOUR_API_KEY"
campaign_id = 123

# Example 1: Get all replied leads
params = {
    "api_key": API_KEY,
    "emailStatus": "is_replied",
    "limit": 100,
    "offset": 0
}

response = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
)

leads = response.json()
print(f"Replied leads: {leads['total']}")

# Example 2: Get leads added in last 7 days
seven_days_ago = (datetime.now() - timedelta(days=7)).isoformat()

params = {
    "api_key": API_KEY,
    "created_at_gt": seven_days_ago,
    "limit": 100
}

new_leads = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
).json()

print(f"New leads (7 days): {new_leads['total']}")

# Example 3: Get in-progress leads with high engagement
params = {
    "api_key": API_KEY,
    "status": "INPROGRESS",
    "emailStatus": "is_clicked",
    "limit": 100
}

engaged_leads = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
).json()

# Example 4: Paginate through all leads
def get_all_leads(campaign_id):
    all_leads = []
    offset = 0
    limit = 100
    
    while True:
        response = requests.get(
            f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
            params={"api_key": API_KEY, "offset": offset, "limit": limit}
        )
        
        data = response.json()
        leads = data.get('leads', [])
        
        if not leads:
            break
            
        all_leads.extend(leads)
        offset += limit
        
        if offset >= data.get('total', 0):
            break
    
    return all_leads

const API_KEY = 'YOUR_API_KEY';
const campaignId = 123;

// Get replied leads
async function getRepliedLeads(campaignId) {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/${campaignId}/leads?api_key=${API_KEY}&emailStatus=is_replied&limit=100`
  );
  
  const data = await response.json();
  console.log(`Replied leads: ${data.total}`);
  return data.leads;
}

// Get leads by category
async function getLeadsByCategory(campaignId, categoryId) {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/${campaignId}/leads?api_key=${API_KEY}&lead_category_id=${categoryId}&limit=100`
  );
  
  return response.json();
}

await getRepliedLeads(123);

{
  "total": 150,
  "leads": [
    {
      "id": 789,
      "email": "john@company.com",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "ACME Corp",
      "status": "INPROGRESS",
      "category_id": 1,
      "category_name": "Interested",
      "created_at": "2025-01-15T10:00:00Z",
      "last_sent_time": "2025-01-20T09:00:00Z",
      "email_stats": {
        "is_opened": true,
        "is_clicked": true,
        "is_replied": true,
        "is_bounced": false
      },
      "custom_fields": {
        "job_title": "CEO",
        "industry": "SaaS"
      }
    }
  ],
  "offset": 0,
  "limit": 100
}

GET

api

campaigns

{campaign_id}

leads

# Get replied leads
curl "https://server.smartlead.ai/api/v1/campaigns/123/leads?api_key=YOUR_KEY&emailStatus=is_replied&limit=100"

import requests
from datetime import datetime, timedelta

API_KEY = "YOUR_API_KEY"
campaign_id = 123

# Example 1: Get all replied leads
params = {
    "api_key": API_KEY,
    "emailStatus": "is_replied",
    "limit": 100,
    "offset": 0
}

response = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
)

leads = response.json()
print(f"Replied leads: {leads['total']}")

# Example 2: Get leads added in last 7 days
seven_days_ago = (datetime.now() - timedelta(days=7)).isoformat()

params = {
    "api_key": API_KEY,
    "created_at_gt": seven_days_ago,
    "limit": 100
}

new_leads = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
).json()

print(f"New leads (7 days): {new_leads['total']}")

# Example 3: Get in-progress leads with high engagement
params = {
    "api_key": API_KEY,
    "status": "INPROGRESS",
    "emailStatus": "is_clicked",
    "limit": 100
}

engaged_leads = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
).json()

# Example 4: Paginate through all leads
def get_all_leads(campaign_id):
    all_leads = []
    offset = 0
    limit = 100
    
    while True:
        response = requests.get(
            f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
            params={"api_key": API_KEY, "offset": offset, "limit": limit}
        )
        
        data = response.json()
        leads = data.get('leads', [])
        
        if not leads:
            break
            
        all_leads.extend(leads)
        offset += limit
        
        if offset >= data.get('total', 0):
            break
    
    return all_leads

const API_KEY = 'YOUR_API_KEY';
const campaignId = 123;

// Get replied leads
async function getRepliedLeads(campaignId) {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/${campaignId}/leads?api_key=${API_KEY}&emailStatus=is_replied&limit=100`
  );
  
  const data = await response.json();
  console.log(`Replied leads: ${data.total}`);
  return data.leads;
}

// Get leads by category
async function getLeadsByCategory(campaignId, categoryId) {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/${campaignId}/leads?api_key=${API_KEY}&lead_category_id=${categoryId}&limit=100`
  );
  
  return response.json();
}

await getRepliedLeads(123);

{
  "total": 150,
  "leads": [
    {
      "id": 789,
      "email": "john@company.com",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "ACME Corp",
      "status": "INPROGRESS",
      "category_id": 1,
      "category_name": "Interested",
      "created_at": "2025-01-15T10:00:00Z",
      "last_sent_time": "2025-01-20T09:00:00Z",
      "email_stats": {
        "is_opened": true,
        "is_clicked": true,
        "is_replied": true,
        "is_bounced": false
      },
      "custom_fields": {
        "job_title": "CEO",
        "industry": "SaaS"
      }
    }
  ],
  "offset": 0,
  "limit": 100
}

Fetch all leads in a campaign with advanced filtering by status, category, engagement, and date ranges. Essential for lead management, reporting, and analysis.

Overview

Retrieves all leads associated with a campaign with comprehensive filtering options similar to Master Inbox endpoints. Key Features:

Pagination support (offset/limit, max 100 per request)
Filter by lead status (STARTED, INPROGRESS, COMPLETED, PAUSED, STOPPED)
Filter by email engagement (opened, clicked, replied, bounced, etc.)
Filter by lead category
Date range filtering (created_at, last_sent_time, event_time)

Path Parameters

number

required

Campaign ID

Query Parameters

string

required

Your SmartLead API key

number

default:"0"

Pagination offset (minimum 0)

number

default:"100"

Records per page (minimum 1, maximum 100)

string

Filter leads created after this date (ISO 8601 format)

string

Filter leads with last email sent after this date (ISO 8601 format)

string

Filter by last event time (ISO 8601 format)

string

Lead status filterValid values:

STARTED - Lead added, sequence not started
INPROGRESS - Currently in sequence
COMPLETED - Sequence completed
PAUSED - Lead paused
STOPPED - Lead stopped

number

Filter by specific category ID

string

Filter by email engagement statusValid values:

is_opened - Email was opened
is_clicked - Link was clicked
is_bounced - Email bounced
is_replied - Lead replied
is_unsubscribed - Lead unsubscribed
is_spam - Marked as spam
is_accepted - Email accepted by server
not_replied - Opened but didn’t reply
is_sender_bounced - Sender bounce

# Get replied leads
curl "https://server.smartlead.ai/api/v1/campaigns/123/leads?api_key=YOUR_KEY&emailStatus=is_replied&limit=100"

import requests
from datetime import datetime, timedelta

API_KEY = "YOUR_API_KEY"
campaign_id = 123

# Example 1: Get all replied leads
params = {
    "api_key": API_KEY,
    "emailStatus": "is_replied",
    "limit": 100,
    "offset": 0
}

response = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
)

leads = response.json()
print(f"Replied leads: {leads['total']}")

# Example 2: Get leads added in last 7 days
seven_days_ago = (datetime.now() - timedelta(days=7)).isoformat()

params = {
    "api_key": API_KEY,
    "created_at_gt": seven_days_ago,
    "limit": 100
}

new_leads = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
).json()

print(f"New leads (7 days): {new_leads['total']}")

# Example 3: Get in-progress leads with high engagement
params = {
    "api_key": API_KEY,
    "status": "INPROGRESS",
    "emailStatus": "is_clicked",
    "limit": 100
}

engaged_leads = requests.get(
    f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
    params=params
).json()

# Example 4: Paginate through all leads
def get_all_leads(campaign_id):
    all_leads = []
    offset = 0
    limit = 100
    
    while True:
        response = requests.get(
            f"https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads",
            params={"api_key": API_KEY, "offset": offset, "limit": limit}
        )
        
        data = response.json()
        leads = data.get('leads', [])
        
        if not leads:
            break
            
        all_leads.extend(leads)
        offset += limit
        
        if offset >= data.get('total', 0):
            break
    
    return all_leads

const API_KEY = 'YOUR_API_KEY';
const campaignId = 123;

// Get replied leads
async function getRepliedLeads(campaignId) {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/${campaignId}/leads?api_key=${API_KEY}&emailStatus=is_replied&limit=100`
  );
  
  const data = await response.json();
  console.log(`Replied leads: ${data.total}`);
  return data.leads;
}

// Get leads by category
async function getLeadsByCategory(campaignId, categoryId) {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/${campaignId}/leads?api_key=${API_KEY}&lead_category_id=${categoryId}&limit=100`
  );
  
  return response.json();
}

await getRepliedLeads(123);

Response Example

{
  "total": 150,
  "leads": [
    {
      "id": 789,
      "email": "john@company.com",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "ACME Corp",
      "status": "INPROGRESS",
      "category_id": 1,
      "category_name": "Interested",
      "created_at": "2025-01-15T10:00:00Z",
      "last_sent_time": "2025-01-20T09:00:00Z",
      "email_stats": {
        "is_opened": true,
        "is_clicked": true,
        "is_replied": true,
        "is_bounced": false
      },
      "custom_fields": {
        "job_title": "CEO",
        "industry": "SaaS"
      }
    }
  ],
  "offset": 0,
  "limit": 100
}

Common Workflows

Export Interested Leads

# Get all interested leads
interested = get_leads(
    campaign_id=123,
    filters={"lead_category_id": 1}
)

# Export to CSV
import csv
with open('interested_leads.csv', 'w') as f:
    writer = csv.DictWriter(f, fieldnames=['email', 'name', 'company'])
    for lead in interested['leads']:
        writer.writerow({
            'email': lead['email'],
            'name': f"{lead['first_name']} {lead['last_name']}",
            'company': lead.get('company_name', '')
        })

Add Leads to Campaign Get Lead by ID

⌘I

Campaign Management

Campaign Leads

Campaign Webhooks

Campaign Statistics

Lead Management

Lead Notes

Lead Tasks

Lead Tags

Lead Lists

Email Account Management

Email Account Tags

Master Inbox

Smart Delivery

Smart Senders

Webhooks

Global Analytics

Utilities

Client Management

Smart Prospect

Overview

Path Parameters

Query Parameters

Response Example

Common Workflows

Export Interested Leads

​Overview

​Path Parameters

​Query Parameters

​Response Example

​Common Workflows

​Export Interested Leads

​Related Endpoints

Overview

Path Parameters

Query Parameters

Response Example

Common Workflows

Export Interested Leads

Related Endpoints