Smartlead API Documentation: Full Reference Guide for Cold Email Automation
The Smartlead API is a REST API that lets developers programmatically manage cold email campaigns, leads, email accounts, and analytics. It uses API key authentication and is available at https://server.smartlead.ai/api/v1.
The Smartlead API is a REST API that gives developers programmatic access to every core function of the Smartlead cold email platform. You can use it to automate campaign creation, manage leads at scale, configure sending email accounts, build email sequences, retrieve analytics, and wire up real-time webhooks — all without touching the Smartlead UI.
What you can do with the Smartlead API:
Campaign management — Create and manage email campaigns with multiple sequences, A/B testing, and advanced scheduling options
Email account rotation — Add multiple email accounts (SMTP, Gmail, Outlook) and let Smartlead automatically rotate senders to maximize deliverability
Intelligent warmup — Use Smartlead's AI-powered warmup system to gradually increase sending volume while maintaining high deliverability rates
Unified inbox — Manage all replies from all campaigns in one place, with AI-powered categorization and response suggestions
Advanced analytics — Track opens, clicks, replies, bounces, and more across all campaigns
Webhook integrations — Connect to your CRM and other tools for real-time event notifications
Lead management — Organize, categorize, import, pause, resume, and unsubscribe prospects at scale
Log in to your Smartlead account
Go to Settings
Click "Activate API"
If your plan includes API access, an API key will be generated
Copy your API key — treat it like a combined username and password and keep it secure
All Smartlead API requests use this base URL:
https://server.smartlead.ai/api/v1
Authentication is done via API key passed as a query parameter on every request:
?api_key=YOUR_API_KEY
Example authenticated request:
curl -X GET "https://server.smartlead.ai/api/v1/campaigns/?api_key=YOUR_API_KEY"
There is no OAuth or Bearer token system — every request must include the api_key query parameter.
Smartlead offers two API versions:
V1 API (recommended) — Base path: https://server.smartlead.ai/api/v1/... — Latest version with all features and improved response formats. Use this for all new integrations.
Legacy API — Base path: https://server.smartlead.ai/api/... — Maintained for backward compatibility with existing integrations only.
Rate limits vary by subscription plan. Please contact customer support.
If you exceed limit, you will receive a 429 Too Many Requests HTTP response. Implement exponential backoff in your integration to handle this gracefully.
Understanding these terms is essential before working with the Smartlead API:
Campaign — An outreach sequence directed to a list of leads, with configurable conditions, schedule, and email content.
Lead — A recipient of your emails — the person you are attempting to contact.
Email Account — A sending mailbox (SMTP, Gmail, or Outlook) attached to campaigns for rotation.
Sequence — The series of emails (with delays) that are sent to each lead within a campaign.
Warmup — A process that gradually increases sending volume from a new email account to build sender reputation.
Webhook — A real-time HTTP callback triggered by campaign events (reply received, email bounced, etc.).
STARTED — Scheduled to begin; awaiting first email send.
INPROGRESS — Has received at least one email.
COMPLETED — Has received all emails in the sequence.
BLOCKED — Email bounced or lead was added to the global block list.
ACTIVE — Campaign is running and sending emails.
PAUSED — Campaign is temporarily halted.
STOPPED — Campaign has been stopped.
ARCHIVED — Campaign is archived.
DRAFTED — Campaign is in draft state, not yet launched.
Campaigns
GET /campaigns/ — List all campaigns
GET /campaigns/{campaign_id} — Get campaign by ID
POST /campaigns/create — Create campaign
PATCH /campaigns/{campaign_id}/status — Update campaign status
POST /campaigns/{campaign_id}/schedule — Update campaign schedule
POST /campaigns/{campaign_id}/settings — Update campaign settings
GET /campaigns/{campaign_id}/sequences— Fetch campaign sequence
POST /campaigns/{campaign_id}/sequences — Save campaign sequence
DELETE /campaigns/{campaign_id} — Delete campaign
GET /campaigns/{campaign_id}/email-accounts — List email accounts per campaign
POST /campaigns/{campaign_id}/email-accounts — Add email account to campaign
DELETE /campaigns/{campaign_id}/email-accounts— Remove email account from campaign
GET /leads/{lead_id}/campaigns — Fetch campaigns by lead ID
Email Accounts
GET /email-accounts/ — List all email accounts
POST /email-accounts/save — Create email account
POST /email-accounts/{email_account_id} — Update email account
GET /email-accounts/{email_account_id}/ — Get email account by ID
POST /email-accounts/{email_account_id}/warmup — Configure warmup
GET /email-accounts/{email_account_id}/warmup-stats — Get warmup stats
Leads
GET /campaigns/{campaign_id}/leads — List leads by campaign
GET /leads/ — Fetch lead by email (use ?email= query param)
GET /leads/fetch-categories — Fetch lead categories
POST /campaigns/{campaign_id}/leads — Add leads to campaign
POST /campaigns/{campaign_id}/leads/{lead_id} — Update lead
POST /campaigns/{campaign_id}/leads/{lead_id}/pause — Pause lead
POST /campaigns/{campaign_id}/leads/{lead_id}/resume — Resume lead
DELETE /campaigns/{campaign_id}/leads/{lead_id} — Delete lead
POST /campaigns/{campaign_id}/leads/{lead_id}/unsubscribe — Unsubscribe lead from campaign
POST /leads/{lead_id}/unsubscribe — Unsubscribe lead globally
POST /leads/add-domain-block-list — Add to block list
GET /campaigns/{campaign_id}/leads/{lead_id}/message-history — Fetch message history
POST /campaigns/{campaign_id}/reply-email-thread — Reply to lead
GET /campaigns/{campaign_id}/leads-export — Export leads to CSV
Analytics
GET /campaigns/{campaign_id}/statistics — Campaign statistics
GET /campaigns/{campaign_id}/analytics-by-date — Analytics by date range
GET /campaigns/{campaign_id}/analytics — Top-level analytics
GET /analytics/overview — Global analytics overview across all campaigns
Retrieves all email campaigns for the authenticated user, including status, schedule settings, tracking configuration, AI matching preferences, and sending limits. Campaigns are returned ordered by ID descending (newest first).
GET https://server.smartlead.ai/api/v1/campaigns/?api_key=YOUR_API_KEY
Query Parameters
api_key · string · Required — Your Smartlead API key.
client_id · number · Optional — Filter campaigns by specific client ID. For agency and white-label accounts.
include_tags · boolean · Optional (default: false) — When true, includes campaign tags with tag ID, name, and color.
Example Requests
curl -X GET "https://server.smartlead.ai/api/v1/campaigns/?api_key=YOUR_API_KEY&include_tags=true"
import requests
response = requests.get(
"https://server.smartlead.ai/api/v1/campaigns/",
params={"api_key": "YOUR_API_KEY", "include_tags": True}
)
campaigns = response.json()
const response = await fetch(
`https://server.smartlead.ai/api/v1/campaigns/?api_key=${YOUR_API_KEY}&include_tags=true`
);
const data = await response.json();
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://server.smartlead.ai/api/v1/campaigns/?api_key=$api_key&include_tags=true");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
Example Response
[
{
"id": 12345,
"user_id": 67890,
"name": "Q1 Outreach Campaign",
"status": "ACTIVE",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-02-01T08:00:00.000Z",
"track_settings": [],
"scheduler_cron_value": {
"tz": "America/New_York",
"days": [1, 2, 3, 4, 5],
"startHour": "09:00",
"endHour": "19:00"
},
"min_time_btwn_emails": 24,
"max_leads_per_day": 100,
"stop_lead_settings": "REPLY_TO_AN_EMAIL",
"schedule_start_time": null,
"enable_ai_esp_matching": true,
"send_as_plain_text": false,
"follow_up_percentage": 20,
"unsubscribe_text": "",
"parent_campaign_id": null,
"client_id": null,
"tags": []
}
]
Response Fields
id · number — Unique campaign identifier.
user_id · number — ID of the user who owns this campaign.
name · string — Campaign name.
status · string — ACTIVE, PAUSED, STOPPED, ARCHIVED, or DRAFTED.
created_at · string (ISO 8601) — Timestamp when campaign was created.
updated_at · string (ISO 8601) — Timestamp of last modification.
track_settings · array — Tracking flags: DONT_EMAIL_OPEN, DONT_LINK_CLICK. Empty array = track everything.
scheduler_cron_value · object — Sending schedule (see Scheduler Object Fields below).
min_time_btwn_emails · number — Minimum minutes between consecutive emails. Higher values (120+) appear more natural and improve deliverability.
max_leads_per_day · number — Max leads to contact per day across all email accounts.
stop_lead_settings · string — When to stop emailing a lead: REPLY_TO_AN_EMAIL, OPENED_EMAIL, CLICKED_LINK, or NEVER.
schedule_start_time · string / null — Scheduled start time (ISO 8601), or null to start immediately.
enable_ai_esp_matching · boolean — When true, Smartlead AI matches leads with optimal email accounts based on provider and deliverability history.
send_as_plain_text · boolean — When true, emails are sent as plain text instead of HTML.
follow_up_percentage · number — Percentage of leads to send follow-up emails to (range: 0–100).
unsubscribe_text · string — Custom unsubscribe text appended to emails.
parent_campaign_id · number / null — ID of parent campaign if this is a subsequence.
client_id · number / null — Client ID if campaign belongs to a specific client.
tags · array — Tag objects (only present when include_tags=true).
Scheduler Object Fields
tz · string — Timezone in IANA format (e.g., "America/New_York").
days · array — Days of week: 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday.
startHour · string — Start sending time in 24-hour format (e.g., "09:00").
endHour · string — Stop sending time in 24-hour format (e.g., "19:00").
Tag Object Fields (only present when include_tags=true)
tag_id · number — Unique tag identifier.
tag_name · string — Name of the tag.
tag_color · string — Hex color code (e.g., "#FF5733").
HTTP Status Codes
200 — Success — returns direct array of campaign objects.
401 — Unauthorized — invalid or missing API key.
404 — Not found.
422 — Validation error — malformed parameters.
429 — Rate limit exceeded.
Fetches complete data for a single campaign using its campaign ID.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
Example Request
curl -X GET "https://server.smartlead.ai/api/v1/campaigns/12345?api_key=YOUR_API_KEY"
Returns full campaign JSON including status, name, tracking settings, scheduler configuration, lead limits, and AI ESP matching settings.
Creates a new campaign. New campaigns start in DRAFTED status, defaulting to "Untitled Campaign" if no name is provided.
POST https://server.smartlead.ai/api/v1/campaigns/create?api_key=YOUR_API_KEY
Request Body
{
"name": "My New Campaign",
"client_id": null
}
Request Body Parameters
name · string · Optional — Campaign name. Defaults to "Untitled Campaign" if omitted.
client_id · number · Optional — Assign campaign to a specific client (agency accounts).
Updates the status of an existing campaign.
PATCH https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/status?api_key=YOUR_API_KEY
Request Body
{
"status": "START"
}
Valid Status Values
START — Start or resume the campaign.
PAUSED — Temporarily halt sending.
STOPPED — Stop the campaign permanently.
Modifies the sending schedule for a campaign — timezone, active days, sending hours, interval between emails, and maximum daily leads.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/schedule?api_key=YOUR_API_KEY
Request Body
{
"timezone": "America/New_York",
"days_of_the_week": [1, 2, 3, 4, 5],
"start_hour": "09:00",
"end_hour": "19:00",
"min_time_btw_emails": 24,
"max_leads_per_day": 100
}
Request Body Parameters
timezone · string · Required — IANA timezone (e.g., "America/New_York").
days_of_the_week · array · Required — Days to send. 0=Sunday, 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday.
start_hour · string · Required — Start time in 24-hour format (e.g., "09:00").
end_hour · string · Required — End time in 24-hour format (e.g., "19:00").
min_time_btw_emails · number · Required — Minutes between consecutive emails.
max_leads_per_day · number · Required — Maximum leads to contact daily.
Adjusts tracking preferences, stop conditions, unsubscribe text, and client assignment.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/settings?api_key=YOUR_API_KEY
Request Body
{
"track_settings": [],
"stop_lead_settings": "REPLY_TO_AN_EMAIL",
"unsubscribe_text": "Click here to unsubscribe",
"send_as_plain_text": false,
"follow_up_percentage": 20,
"enable_ai_esp_matching": true,
"client_id": null
}
Request Body Parameters
track_settings · array · Optional — Tracking flags to disable. Values: DONT_EMAIL_OPEN, DONT_LINK_CLICK. Empty array = track everything.
stop_lead_settings · string · Optional — When to stop emailing a lead: REPLY_TO_AN_EMAIL, OPENED_EMAIL, CLICKED_LINK, or NEVER.
unsubscribe_text · string · Optional — Custom unsubscribe text appended to emails.
send_as_plain_text · boolean · Optional — When true, emails are sent as plain text instead of HTML.
follow_up_percentage · number · Optional — Percentage of leads to send follow-ups to (0–100).
enable_ai_esp_matching · boolean · Optional — Enable AI-based email account matching per lead.
client_id · number / null · Optional — Assign campaign to a specific client.
Retrieves all sequence data for a campaign, including email variants, subject lines, and email bodies.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/sequences?api_key=YOUR_API_KEY
Returns sequences with subject lines, email bodies, and variant labels (for A/B testing).
Updates or creates email sequences for a campaign, including delay settings and variant content.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/sequences?api_key=YOUR_API_KEY
Request Body
[
{
"seq_number": 1,
"seq_delay_details": {
"delay_in_days": 0
},
"variant_distribution_type": "MANUALLY_EQUAL",
"variants": [
{
"subject": "Quick question, {{first_name}}",
"email_body": "<p>Hi {{first_name}},</p><p>Your email body here.</p>",
"variant_label": "A"
}
]
}
]
Sequence Object Fields
seq_number · number · Required — Position of this step in the sequence (1-indexed).
seq_delay_details · object · Required — Delay before this step sends. Use delay_in_days for the number of days to wait.
variant_distribution_type · string · Required — How variants are distributed. Use MANUALLY_EQUAL for equal distribution.
variants · array · Required — Array of email variants for A/B testing.
Variant Object Fields
subject · string · Required — Email subject line. Supports merge tags like {{first_name}}.
email_body · string · Required — HTML email body. Supports merge tags.
variant_label · string · Required — Label for this variant (e.g., "A", "B").
Permanently removes a campaign from your account.
DELETE https://server.smartlead.ai/api/v1/campaigns/{campaign_id}?api_key=YOUR_API_KEY
Fetches all email accounts currently assigned to a campaign for sending.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/email-accounts?api_key=YOUR_API_KEY
Returns account details including SMTP/IMAP configuration, daily send limits, and authentication status.
Associates an email account with a campaign to use for sending.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/email-accounts?api_key=YOUR_API_KEY
Request Body
{
"email_account_ids": [456, 457, 458]
}
email_account_ids · number · Required — The ID of the email account to add to this campaign.
Disassociates an email account from a campaign.
DELETE https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/email-accounts?api_key=YOUR_API_KEY
Request Body
{
"email_account_ids": [ 456, 457, 458] }
}
email_account_ids · number · Required — The ID of the email account to remove from this campaign.
Returns all campaigns that contain a specific lead.
GET https://server.smartlead.ai/api/v1/leads/{lead_id}/campaigns?api_key=YOUR_API_KEY
Path Parameters
lead_id · number · Required — The unique ID of the lead.
Lists all email accounts associated with your user account, with pagination support.
GET https://server.smartlead.ai/api/v1/email-accounts/?api_key=YOUR_API_KEY&offset=0&limit=10
Query Parameters
api_key · string · Required — Your API key.
offset · number · Optional (default: 0) — Pagination offset.
limit · number · Optional (default: 100, max: 100) — Results per page.
Returns account credentials, server settings, warmup details, and daily send counts.
Adds a new email account with SMTP/IMAP configuration.
POST https://server.smartlead.ai/api/v1/email-accounts/save?api_key=YOUR_API_KEY
Request Body
{
"from_name": "John Smith",
"from_email": "[email protected]",
"username": "[email protected]",
"password": "your_app_password",
"smtp_host": "smtp.gmail.com",
"smtp_port": 587,
"smtp_port_type": "TLS",
"imap_host": "imap.gmail.com",
"imap_port": 993,
"max_email_per_day": 50,
"custom_tracking_url": null,
"bcc": null,
"signature": null
}
Request Body Parameters
from_name · string · Required — Display name shown to recipients.
from_email · string · Required — The sending email address.
user_name · string · Required — SMTP/IMAP login username (usually the email address).
password · string · Required — SMTP/IMAP password or app password.
smtp_host · string · Required — SMTP server hostname.
smtp_port · number · Required — SMTP port (typically 587 for TLS, 465 for SSL).
smtp_port_type · string · Required — Connection type: TLS or SSL.
imap_host · string · Required — IMAP server hostname.
imap_port · number · Required — IMAP port (typically 993).
max_email_per_day · number · Optional — Daily send limit for this account.
custom_tracking_url · string / null · Optional — Custom tracking domain for open and click tracking.
bcc · string / null · Optional — BCC address to receive a copy of every sent email.
signature · string / null · Optional — HTML email signature.
Modifies an existing email account's properties including daily limits, tracking URLs, and signatures.
POST https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}?api_key=YOUR_API_KEY
Path Parameters
email_account_id · number · Required — The unique ID of the email account to update.
Accepts the same fields as the Create endpoint. Include only the fields you want to update.
Retrieves complete details for a single email account.
GET https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}/?api_key=YOUR_API_KEY
Path Parameters
email_account_id · number · Required — The unique ID of the email account.
Sets up or updates warmup settings for an email account, including daily volume and ramp-up strategy.
POST https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}/warmup?api_key=YOUR_API_KEY
Path Parameters
email_account_id · number · Required — The unique ID of the email account.
Request Body
{
"warmup_enabled": true,
"total_warmup_per_day": 20,
"daily_rampup": 2,
"reply_rate_percentage": 30
}
Request Body Parameters
warmup_enabled · boolean · Required — Enable or disable warmup for this account.
total_warmup_per_day · number · Required — Total warmup emails to send per day.
daily_rampup · number · Required — Number of additional warmup emails to add each day (gradual ramp-up).
reply_rate_percentage · number · Required — Percentage of warmup emails to reply to (improves sender reputation).
Returns the last 7 days of warmup statistics for an email account.
GET https://server.smartlead.ai/api/v1/email-accounts/{email_account_id}/warmup-stats?api_key=YOUR_API_KEY
Path Parameters
email_account_id · number · Required — The unique ID of the email account.
Returns: sent count, spam placement count, and inbox placement count per day for the last 7 days.
Fetches all leads in a campaign with full lead data and pagination.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads?api_key=YOUR_API_KEY&offset=0&limit=100
Query Parameters
api_key · string · Required — Your API key.
offset · number · Optional (default: 0) — Pagination offset.
limit · number · Optional (default: 100, max: 100) — Results per page.
Returns lead data including status, contact info, custom fields, and engagement metrics (open count, click count, reply count).
Returns full lead data using the lead's email address as the identifier.
GET https://server.smartlead.ai/api/v1/leads/?api_key=YOUR_API_KEY&[email protected]
Query Parameters
api_key · string · Required — Your API key.
email · string · Required — The email address of the lead to fetch.
Retrieves all available lead categories for organization and segmentation.
GET https://server.smartlead.ai/api/v1/leads/fetch-categories?api_key=YOUR_API_KEY
Bulk uploads leads to a campaign. Maximum 400 leads per request.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads?api_key=YOUR_API_KEY
Request Body
{
"lead_list": [
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Smith",
"company_name": "Acme Corp",
"phone_number": "+1234567890",
"website": "https://acme.com",
"location": "New York, USA",
"linkedin_profile": "https://linkedin.com/in/johnsmith",
"company_url": "https://acme.com",
"custom_fields": {
"job_title": "VP of Sales",
"industry": "SaaS"
}
}
],
"settings": {
"ignore_global_block_list": false,
"ignore_unsubscribe_list": false,
"ignore_community_bounce_list": false,
"ignore_duplicate_leads_in_other_campaign": false
}
}
Lead Object Fields
email · string · Required — Lead's email address.
first_name · string · Optional — Lead's first name.
last_name · string · Optional — Lead's last name.
company_name · string · Optional — Lead's company name.
phone_number · string · Optional — Lead's phone number.
website · string · Optional — Lead's personal or company website.
location · string · Optional — Lead's location.
linkedin_profile · string · Optional — Lead's LinkedIn profile URL.
company_url · string · Optional — Lead's company website URL.
custom_fields · object · Optional — Key-value pairs for any custom fields defined in your account.
Settings Parameters
ignore_global_block_list · boolean — When true, skips global block list check when importing this batch.
ignore_unsubscribe_list · boolean — When true, skips unsubscribe list check.
ignore_community_bounce_list · boolean — When true, skips community bounce list check.
ignore_duplicate_leads_in_other_campaign · boolean — When true, allows importing leads that already exist in other campaigns.
Modifies lead information including custom fields.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
lead_id · number · Required — The unique ID of the lead.
Accepts the same fields as the lead object in the Add Leads endpoint. Include only the fields you want to update.
Pauses a lead's activity within a specific campaign — no further emails will be sent until the lead is resumed.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/pause?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
lead_id · number · Required — The unique ID of the lead.
Resumes a paused lead in a campaign with an optional delay before the next send.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/resume?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
lead_id · number · Required — The unique ID of the lead.
Removes a lead from a specific campaign. The lead's data is deleted from that campaign only.
DELETE https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
lead_id · number · Required — The unique ID of the lead.
Unsubscribes a lead from a specific campaign only. The lead can still receive emails from other campaigns.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/unsubscribe?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
lead_id · number · Required — The unique ID of the lead.
Globally unsubscribes a lead from all campaigns and prevents them from being re-added to any future campaign.
POST https://server.smartlead.ai/api/v1/leads/{lead_id}/unsubscribe?api_key=YOUR_API_KEY
Path Parameters
lead_id · number · Required — The unique ID of the lead to globally unsubscribe.
Adds an email address or entire domain to the global block list to prevent any future outreach.
POST https://server.smartlead.ai/api/v1/leads/add-domain-block-list?api_key=YOUR_API_KEY
Request Body — Block a specific email address:
{
"email": "[email protected]"
}
Request Body — Block an entire domain:
{
"domain": "example.com"
}
email · string · Conditionally Required — Email address to block. Use this OR domain, not both.
domain · string · Conditionally Required — Domain to block (e.g., "example.com"). Blocks all email addresses at this domain. Use this OR email, not both.
Returns the complete email conversation thread for a specific lead within a campaign.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads/{lead_id}/message-history?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
lead_id · number · Required — The unique ID of the lead.
Returns: message types (SENT / REPLY), timestamps, subject lines, and full email bodies.
Sends a reply directly into a lead's message thread from the master inbox.
POST https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/reply-email-thread?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
Request Body
{
"lead_id": 789,
"email_body": "<p>Hi John, thanks for your reply...</p>",
"reply_message_id": "msg_abc123",
"reply_email_time": "2024-01-20T10:00:00.000Z"
}
lead_id · number · Required — The ID of the lead to reply to.
email_body · string · Required — HTML content of your reply.
reply_message_id · string · Required — The message ID of the email you are replying to (maintains thread continuity).
reply_email_time · string · Required — ISO 8601 timestamp for the reply.
Downloads a CSV file of all leads in a campaign with complete metrics.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/leads-export?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
CSV columns included:
id, campaign_lead_map_id, status, created_at, first_name, last_name, email, phone_number, company_name, website, location, custom_fields, linkedin_profile, company_url, is_unsubscribed, last_email_sequence_sent, is_interested, open_count, click_count, reply_count
Returns detailed engagement metrics for a campaign with optional filtering by sequence number or email status.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/statistics?api_key=YOUR_API_KEY&offset=0&limit=100
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
Optional Query Parameters
email_sequence_number · number · Optional — Filter results by a specific sequence step number.
email_status · string · Optional — Filter by engagement status. Values: opened, clicked, replied, unsubscribed, bounced.
offset · number · Optional (default: 0) — Pagination offset.
limit · number · Optional (default: 100) — Results per page.
Retrieves campaign analytics for a specific date range. Maximum span: 30 days.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/analytics-by-date?api_key=YOUR_API_KEY&start_date=2024-01-01&end_date=2024-01-30
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
Query Parameters
start_date · string · Required — Start of date range in YYYY-MM-DD format.
end_date · string · Required — End of date range in YYYY-MM-DD format. Maximum 30 days from start date.
Returns: sent count, open count, click count, reply count, bounce count, and unsubscribe count per day within the range.
Provides aggregate performance metrics for a campaign in a single response.
GET https://server.smartlead.ai/api/v1/campaigns/{campaign_id}/analytics?api_key=YOUR_API_KEY
Path Parameters
campaign_id · number · Required — The unique ID of the campaign.
Returns: sent / open / click / reply totals, lead status distribution, and client information.
Returns performance metrics across all campaigns — not just a single campaign. Use this for dashboard-level reporting and portfolio health tracking.
GET https://server.smartlead.ai/api/v1/analytics/overview?api_key=YOUR_API_KEY
Includes: aggregate sent / open / click / reply counts, response analysis with sentiment breakdown, lead category-wise response tracking, day-wise and month-wise performance metrics, email health by domain and individual account (with bounce rate), and provider comparison across Gmail, Outlook, and SMTP.
Smartlead supports webhook integration for real-time event notifications. Configure webhooks to push campaign and lead activity events to your CRM, Slack, or any HTTP endpoint the moment they occur.
Webhook Endpoints:
POST /webhooks — Create a new webhook
GET /webhooks — List all webhooks
PUT /api/v1/webhook/update/:webhook_id — Update a webhook
DELETE /webhooks/{webhook_id} — Delete a webhook
Common webhook events:
Email reply received
Email bounced
Lead unsubscribed
Campaign completed
Lead status changed
The Smartlead API uses standard HTTP response codes:
200 — Success. Request completed as expected.
400 — Bad Request. Check your request body or query parameters for errors.
401 — Unauthorized. Your API key is missing or invalid.
404 — Not Found. Verify the resource ID exists in your account.
422 — Validation Error. Check parameter types and ensure all required fields are present.
429 — Rate Limit Exceeded. You've exceeded 10 requests per 2 seconds. Implement exponential backoff and retry.
500 — Server Error. Retry after a short delay. Contact support if the error persists.
503 — Service Unavailable. Retry after a short delay.
Best practice: On 429, wait at least 2 seconds before retrying. Use exponential backoff for repeated failures.
The Smartlead API base URL is https://server.smartlead.ai/api/v1. All endpoints use this as the root, with your API key appended as a query parameter: ?api_key=YOUR_API_KEY.
Authentication is done via API key. Go to your Smartlead account settings, activate API access, and copy your key. Append it to every request as ?api_key=YOUR_KEY. There is no OAuth — every request must include the key.
Rate limits vary by subscription plan. Please contact customer support.
Use POST /api/v1/campaigns/{campaign_id}/leads with your API key. You can upload up to 400 leads per request. The payload supports custom fields, duplicate detection, and block list handling.
Yes. The Smartlead API supports full campaign lifecycle management: create, update schedule, update settings, add/remove email accounts, fetch sequences, save sequences, and delete campaigns — all via REST endpoints.
Use POST /api/v1/email-accounts/{email_account_id}/warmup to configure warmup settings including daily send volume and ramp-up amount. Use GET /warmup-stats to monitor the last 7 days of warmup performance.
The API returns sent, open, click, reply, bounce, and unsubscribe counts. You can query by campaign ID, by date range (max 30-day span), or get top-level aggregate metrics. Lead status distribution is also included.
Use POST /api/v1/leads/{lead_id}/unsubscribe to globally unsubscribe a lead from all campaigns and prevent re-adding. For a single campaign, use the campaign-specific unsubscribe endpoint.
Yes. Smartlead supports webhook integration for real-time event notifications. Use the /webhooks endpoints to create, list, update, and delete webhooks that fire on campaign and lead events.
The current recommended version uses /api/v1/... endpoint paths. The legacy version (/api/...) is maintained for backward compatibility. All new integrations should use v1.
Campaigns can have the following statuses: ACTIVE, PAUSED, STOPPED, ARCHIVED, and DRAFTED. New campaigns start as DRAFTED.
Yes. Use the client_id query parameter on GET /campaigns/ to filter results to a specific client. This is designed for agency and white-label accounts managing multiple clients.
enable_ai_esp_matching do? When set to true, Smartlead's AI automatically matches each lead with the optimal sending email account based on the lead's email provider and historical deliverability data. This improves inbox placement rates.
send_as_plain_text do? When true, Smartlead sends emails as plain text instead of HTML. This can improve deliverability with technical audiences and makes emails look more personal.
Yes. Use GET /campaigns/{campaign_id}/leads-export to download a full CSV of all leads in a campaign including engagement metrics (opens, clicks, replies), custom fields, and subscription status.
For support, contact [email protected]