Skip to main content
POST
/
api
/
v1
/
campaigns
/
create
curl -X POST "https://server.smartlead.ai/api/v1/campaigns/create?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Cold Outreach"
  }'

{
  "ok": true,
  "id": 125,
  "name": "Q1 2024 Cold Outreach",
  "created_at": "2024-01-25T10:30:00Z"
}
Creates a new email campaign with default settings in DRAFTED status Campaign name defaults to ‘Untitled Campaign’ if not provided

​
Overview

Creates a new email campaign with default settings in DRAFTED status Key Features:
  • Returns campaign ID and metadata.

​
Query Parameters

​
api_key
string
required
Your SmartLead API key for authentication

​
Request Body

​
name
string
Campaign name. If not provided, defaults to “Untitled Campaign”. Can be changed later via update settings.
​
client_id
number
Associate campaign with a specific client (for agency/white-label accounts). If not provided and user has client_id, automatically uses that value.
Minimal Required Fields: This endpoint only accepts name and client_id. Other campaign settings (track_settings, schedule, sequences, etc.) must be configured using separate update endpoints after creation.

​
Response

​
ok
boolean
Always true for successful creation
​
id
number
Unique identifier for the newly created campaign
​
name
string
Campaign name (either provided or “Untitled Campaign”)
​
created_at
string
ISO 8601 timestamp when campaign was created
curl -X POST "https://server.smartlead.ai/api/v1/campaigns/create?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Cold Outreach"
  }'

​
Response Codes

​
200
Success
Campaign created successfully
​
400
Bad Request
Invalid request parameters or malformed request body
​
401
Unauthorized
Invalid or missing API key. Check your authentication.
​
422
Validation Error
Request validation failed. Check parameter types and required fields.
​
429
Rate Limit Exceeded
Too many requests. Please slow down and retry after the rate limit resets.
​
500
Internal Server Error
Server error occurred. Please try again or contact support if the issue persists.
​
503
Service Unavailable
API is temporarily unavailable or under maintenance. Please try again later.
{
  "ok": true,
  "id": 125,
  "name": "Q1 2024 Cold Outreach",
  "created_at": "2024-01-25T10:30:00Z"
}

​
Implementation Details

What Happens:
  1. Campaign is created with minimal data (just name and optional client_id)
  2. Campaign starts in DRAFTED status
  3. Campaign name defaults to “Untitled Campaign” if not provided
  4. Client ID is automatically set if user is a client
  5. Returns campaign ID immediately for further configuration
Default Settings:
  • Status: DRAFTED
  • Track Settings: Not set (configure later)
  • Schedule: Not set (configure later)
  • Sequences: Empty (add later)
  • Email Accounts: None (add later)
  • Leads: None (add later)
Response Format: Direct object with ok, id, name, created_at
Newly created campaigns cannot send emails yet. You must configure sequences, add email accounts, and add leads before starting the campaign.

​
Next Steps

After creating a campaign, follow this workflow:
1

Add Email Sequences

Create your email sequence (initial email + follow-ups)
POST /v1/campaigns/{campaign_id}/sequences
Update Sequences
2

Add Email Accounts

Associate sender email accounts with the campaign
POST /v1/campaigns/{campaign_id}/email-accounts
Add Email Accounts
3

Add Leads

Upload your prospect list (up to 400 leads per request)
POST /v1/campaigns/{campaign_id}/leads
Add Leads
4

Configure Schedule

Set sending hours, timezone, and frequency
PATCH /v1/campaigns/{campaign_id}/schedule
Update Schedule
5

Configure Settings

Set tracking, limits, and stop conditions
PATCH /v1/campaigns/{campaign_id}/settings
Update Settings
6

Start Campaign

Activate the campaign to begin sending
PATCH /v1/campaigns/{campaign_id}/status
Update Status

​
Campaign Naming Best Practices

Choose names that clearly indicate the campaign purpose and timeframe
  • ✅ Good: “SaaS Founders Q1 2024”
  • ❌ Bad: “Campaign 1”
Add the quarter or month to track performance over time
  • “Q1 2024 Enterprise Outreach”
  • “Jan 2024 Product Launch”
Make it clear who you’re targeting
  • “Healthcare CFOs - Q1”
  • “Tech Startup CTOs”

​
Complete Example Workflow

Python - Complete Campaign Setup
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://server.smartlead.ai/api/v1"

# 1. Create campaign
campaign = requests.post(
    f"{BASE_URL}/campaigns/create",
    params={"api_key": API_KEY},
    json={"name": "Q1 2024 Outreach"}
).json()

campaign_id = campaign['id']
print(f"Created campaign {campaign_id}")

# 2. Add sequences
requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/sequences",
    params={"api_key": API_KEY},
    json={
        "sequences": [
            {
                "seq_number": 1,
                "subject": "Quick question",
                "email_body": "Hi {{first_name}}...",
                "seq_delay_details": {"delay_in_days": 0}
            }
        ]
    }
)
print("Added sequences")

# 3. Add email accounts
requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/email-accounts",
    params={"api_key": API_KEY},
    json={"email_account_ids": [456, 457]}
)
print("Added email accounts")

# 4. Add leads
requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/leads",
    params={"api_key": API_KEY},
    json={
        "lead_list": [
            {"email": "john@example.com", "first_name": "John"}
        ]
    }
)
print("Added leads")

# 5. Start campaign
requests.patch(
    f"{BASE_URL}/campaigns/{campaign_id}/status",
    params={"api_key": API_KEY},
    json={"status": "ACTIVE"}
)
print(f"Campaign {campaign_id} is now ACTIVE!")