Create Campaign

Create and configure cold email campaigns programmatically. Campaign activation follows a component-based approach where you provide the fields you want, then set launch: true when ready.

Create a New Campaign

POST /api/public/v1/campaigns

Python
JavaScript
cURL

import requests

api_key = "cs_live_your_api_key_here"
base_url = "https://api.coldsend.pro"

response = requests.post(
    f"{base_url}/api/public/v1/campaigns",
    headers={"X-API-Key": api_key},
    json={
        "name": "Q1 Product Launch Outreach",
        "timezone": "America/New_York",
        "sending_days": [1, 2, 3, 4, 5],
        "sending_window_start": 9,
        "sending_window_end": 17,
        "daily_limit_per_inbox": 30,
        "enable_tracking": True,
        "enable_unsubscribe": True
    }
)

campaign = response.json()
campaign_id = campaign["campaign_id"]
print(f"Campaign created: {campaign_id}")

const apiKey = "cs_live_your_api_key_here";
const baseUrl = "https://api.coldsend.pro";

const response = await fetch(`${baseUrl}/api/public/v1/campaigns`, {
  method: "POST",
  headers: {
    "X-API-Key": apiKey,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Q1 Product Launch Outreach",
    timezone: "America/New_York",
    sending_days: [1, 2, 3, 4, 5],
    sending_window_start: 9,
    sending_window_end: 17,
    daily_limit_per_inbox: 30,
    enable_tracking: true,
    enable_unsubscribe: true
  })
});

const campaign = await response.json();
const campaignId = campaign.campaign_id;
console.log(`Campaign created: ${campaignId}`);

curl -X POST "https://api.coldsend.pro/api/public/v1/campaigns" \
  -H "X-API-Key: cs_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Product Launch Outreach",
    "timezone": "America/New_York",
    "sending_days": [1, 2, 3, 4, 5],
    "sending_window_start": 9,
    "sending_window_end": 17,
    "daily_limit_per_inbox": 30,
    "enable_tracking": true,
    "enable_unsubscribe": true
  }'

{
  "success": true,
  "message": "Campaign created successfully",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Product Launch Outreach",
  "status": "DRAFT",
  "created_at": "2024-01-15T10:30:00Z"
}

Request Parameters

Required Fields

Parameter	Type	Description
`name`	string	Campaign name (8-255 characters)

Optional Fields

Parameter	Type	Default	Description
`timezone`	string	`America/New_York`	IANA timezone for scheduling
`sending_days`	int[]	`[1,2,3,4,5]`	Days to send (1=Mon, 7=Sun)
`sending_window_start`	int	`9`	Start hour (0-23)
`sending_window_start_minute`	int	`0`	Start minute (0-59)
`sending_window_end`	int	`17`	End hour (1-24)
`sending_window_end_minute`	int	`0`	End minute (0-59)
`daily_limit_per_inbox`	int	null	Max emails per inbox/day (1-100)
`start_date`	datetime	null	ISO 8601 start date
`enable_tracking`	bool	`false`	Enable email open tracking
`enable_unsubscribe`	bool	`true`	Include unsubscribe link
`ramp_up_enabled`	bool	`false`	Gradually increase sending volume each day
`ramp_up_increment`	int	system default	Emails/inbox/day added per ramp-up day (1-100)
`ramp_up_max_limit`	int	system default	Daily cap per inbox once fully ramped (1-1000)

The sending window supports minute-precision. For example, sending_window_start: 9 with sending_window_start_minute: 30 starts at 9:30 AM. When sending_window_end is 24, the minute must be 0.

Update Campaign

PUT /api/public/v1/campaigns/{campaign_id} Update any campaign field or activate it. Only include the fields you want to change.

Python

response = requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={
        "name": "Updated Campaign Name",
        "inbox_ids": ["inbox-uuid"],
        "variants": [
            {
                "variant_name": "A",
                "subject_template": "Quick question about {{company}}",
                "email_content": "Hi {{first_name}},\n\n...",
                "distribution_percent": 100
            }
        ],
        "sequences": [...],
        "launch": True
    }
)

Updatable Fields

Basic Settings: name, timezone, sending_days, sending_window_start, sending_window_start_minute, sending_window_end, sending_window_end_minute, daily_limit_per_inbox, enable_tracking, enable_unsubscribe, start_date, ramp_up_enabled, ramp_up_increment, ramp_up_max_limit

Setting ramp_up_enabled: true resets the ramp-up counter for all assigned inboxes, so the gradual increase starts fresh.

Inboxes: inbox_ids — Array of inbox UUIDs to assign Email Content: variants — Array of email variant objects for A/B testing Follow-ups: sequences — Array of follow-up sequence objects Launch Control: launch — Set to true to activate the campaign

Launch Validation

When launch: true, the API checks:

At least one lead exists
At least one inbox is assigned
At least one email variant is configured

Python

response = requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={"launch": True}
)

result = response.json()
print(f"Launch ready: {result['is_launch_ready']}")
print(f"Missing: {result['missing_requirements']}")

Response

{
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "is_launch_ready": false,
  "missing_requirements": ["leads", "variants"],
  ...
}

If requirements are missing, the campaign remains in DRAFT. The missing_requirements field tells you exactly what’s needed.

Validation Errors

Error	Cause
`ensure this value has at least 8 characters`	Campaign name too short
`Invalid timezone: America/Invalid`	Invalid IANA timezone
`sending_window_end must be after sending_window_start`	Window configuration invalid
`Variant distributions must sum to 100%`	Variant percentages don’t total 100

Best Practices

Use descriptive names — Include goal, target audience, or time period
Match timezone to audience — Prevents emails from sending at odd hours
Start conservative with limits — 20-50 emails/inbox/day for new accounts
Enable tracking — Essential for measuring campaign performance
Test before launching — Try with a few test leads first

Next Steps

Email Variants

Configure A/B testing and distribution.

Follow-up Sequences

Set up automated follow-up emails.

Personalization

Use variables, spintax, and conditionals.

Getting Started

Authentication

Campaigns

Sender Accounts

Domains

Leads

Replies

Analytics

Reference

Compliance

Create a New Campaign

Request Parameters

Required Fields

Optional Fields

Update Campaign

Updatable Fields

Launch Validation

Validation Errors

Best Practices

Next Steps

Email Variants

Follow-up Sequences

Personalization

​Create a New Campaign

​Request Parameters

​Required Fields

​Optional Fields

​Update Campaign

​Updatable Fields

​Launch Validation

​Validation Errors

​Best Practices

​Next Steps

Email Variants

Follow-up Sequences

Personalization

Create a New Campaign

Request Parameters

Required Fields

Optional Fields

Update Campaign

Updatable Fields

Launch Validation

Validation Errors

Best Practices

Next Steps