Create Campaign

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"
  }'

import requests

API_KEY = "YOUR_API_KEY"
url = "https://server.smartlead.ai/api/v1/campaigns/create"

payload = {
    "name": "Q1 2024 Cold Outreach"
}

response = requests.post(
    url,
    params={"api_key": API_KEY},
    json=payload
)

result = response.json()
print(f"Campaign created with ID: {result['id']}")
print(f"Campaign name: {result['name']}")

const API_KEY = 'YOUR_API_KEY';

async function createCampaign() {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/create?api_key=${API_KEY}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: 'Q1 2024 Cold Outreach'
      }),
    }
  );
  
  const data = await response.json();
  console.log(`Campaign created with ID: ${data.id}`);
  return data;
}

createCampaign();

{
  "ok": true,
  "id": 125,
  "name": "Q1 2024 Cold Outreach",
  "created_at": "2024-01-25T10:30:00Z"
}

{
  "message": "Invalid API Key"
}

{
  "error": "Invalid campaign name format"
}

{
  "error": "Error while creating email campaign - Database connection failed"
}

POST

api

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"
  }'

import requests

API_KEY = "YOUR_API_KEY"
url = "https://server.smartlead.ai/api/v1/campaigns/create"

payload = {
    "name": "Q1 2024 Cold Outreach"
}

response = requests.post(
    url,
    params={"api_key": API_KEY},
    json=payload
)

result = response.json()
print(f"Campaign created with ID: {result['id']}")
print(f"Campaign name: {result['name']}")

const API_KEY = 'YOUR_API_KEY';

async function createCampaign() {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/create?api_key=${API_KEY}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: 'Q1 2024 Cold Outreach'
      }),
    }
  );
  
  const data = await response.json();
  console.log(`Campaign created with ID: ${data.id}`);
  return data;
}

createCampaign();

{
  "ok": true,
  "id": 125,
  "name": "Q1 2024 Cold Outreach",
  "created_at": "2024-01-25T10:30:00Z"
}

{
  "message": "Invalid API Key"
}

{
  "error": "Invalid campaign name format"
}

{
  "error": "Error while creating email campaign - Database connection failed"
}

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

string

required

Your SmartLead API key for authentication

Request Body

string

Campaign name. If not provided, defaults to “Untitled Campaign”. Can be changed later via update settings.

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

boolean

Always true for successful creation

number

Unique identifier for the newly created campaign

string

Campaign name (either provided or “Untitled Campaign”)

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"
  }'

import requests

API_KEY = "YOUR_API_KEY"
url = "https://server.smartlead.ai/api/v1/campaigns/create"

payload = {
    "name": "Q1 2024 Cold Outreach"
}

response = requests.post(
    url,
    params={"api_key": API_KEY},
    json=payload
)

result = response.json()
print(f"Campaign created with ID: {result['id']}")
print(f"Campaign name: {result['name']}")

const API_KEY = 'YOUR_API_KEY';

async function createCampaign() {
  const response = await fetch(
    `https://server.smartlead.ai/api/v1/campaigns/create?api_key=${API_KEY}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: 'Q1 2024 Cold Outreach'
      }),
    }
  );
  
  const data = await response.json();
  console.log(`Campaign created with ID: ${data.id}`);
  return data;
}

createCampaign();

Response Codes

Success

Campaign created successfully

Bad Request

Invalid request parameters or malformed request body

Unauthorized

Invalid or missing API key. Check your authentication.

Validation Error

Request validation failed. Check parameter types and required fields.

Rate Limit Exceeded

Too many requests. Please slow down and retry after the rate limit resets.

Internal Server Error

Server error occurred. Please try again or contact support if the issue persists.

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"
}

{
  "message": "Invalid API Key"
}

{
  "error": "Invalid campaign name format"
}

{
  "error": "Error while creating email campaign - Database connection failed"
}

Implementation Details

What Happens:

Campaign is created with minimal data (just name and optional client_id)
Campaign starts in DRAFTED status
Campaign name defaults to “Untitled Campaign” if not provided
Client ID is automatically set if user is a client
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:

Add Email Sequences

Create your email sequence (initial email + follow-ups)

POST /v1/campaigns/{campaign_id}/sequences

Update Sequences

Add Email Accounts

Associate sender email accounts with the campaign

POST /v1/campaigns/{campaign_id}/email-accounts

Add Email Accounts

Add Leads

Upload your prospect list (up to 400 leads per request)

POST /v1/campaigns/{campaign_id}/leads

Add Leads

Configure Schedule

Set sending hours, timezone, and frequency

PATCH /v1/campaigns/{campaign_id}/schedule

Update Schedule

Configure Settings

Set tracking, limits, and stop conditions

PATCH /v1/campaigns/{campaign_id}/settings

Update Settings

Start Campaign

Activate the campaign to begin sending

PATCH /v1/campaigns/{campaign_id}/status

Update Status

Campaign Naming Best Practices

Use Descriptive Names

Choose names that clearly indicate the campaign purpose and timeframe

✅ Good: “SaaS Founders Q1 2024”
❌ Bad: “Campaign 1”

Include Time Period

Add the quarter or month to track performance over time

“Q1 2024 Enterprise Outreach”
“Jan 2024 Product Launch”

Indicate Target Audience

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!")

Get Campaign by ID Update Campaign Status

⌘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

Query Parameters

Request Body

Response

Response Codes

Implementation Details

Next Steps

Campaign Naming Best Practices

Complete Example Workflow

​Overview

​Query Parameters

​Request Body

​Response

​Response Codes

​Implementation Details

​Next Steps

​Campaign Naming Best Practices

​Complete Example Workflow

​Related Endpoints

Overview

Query Parameters

Request Body

Response

Response Codes

Implementation Details

Next Steps

Campaign Naming Best Practices

Complete Example Workflow

Related Endpoints