Skip to main content

​
Campaigns Overview

A campaign represents a single outreach effort in ColdSend. Each campaign contains leads, email variants, follow-up sequences, and sender accounts.

​
Campaign Lifecycle

Campaigns progress through distinct states:
StatusDescription
DRAFTCampaign is being configured
ACTIVECampaign is running and sending emails
PAUSEDCampaign is temporarily stopped
COMPLETEDAll leads have been processed
FAILEDCampaign launch failed

​
5-Step Creation Workflow

Creating a campaign follows a structured workflow:

​
Step 0: Create Campaign

Initialize the campaign with basic settings: 
response = requests.post(
    f"{base_url}/api/public/v1/campaigns",
    headers={"X-API-Key": api_key},
    json={
        "name": "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
    }
)

campaign_id = response.json()["campaign_id"]
The campaign is created with status DRAFT and current_step = 0.

​
Step 1: Basic Configuration

Configure scheduling and settings. These can be updated later:
  • Campaign name
  • Timezone for scheduling
  • Sending days (which days of the week)
  • Sending window (hours during which emails are sent)
  • Daily limit per inbox
  • Tracking and unsubscribe settings

​
Step 2: Lead Configuration

Define how lead data maps from your CSV to ColdSend fields: 
requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={
        "lead_mapping": {
            "email": "email",
            "first_name": "first_name",
            "last_name": "last_name",
            "company": "company",
            "custom_size": "company_size"
        }
    }
)
Lead upload happens through the ColdSend dashboard or internal API.

​
Step 3: Inbox Selection

Assign sender accounts to the campaign: 
requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={
        "inbox_ids": [inbox_id_1, inbox_id_2]
    }
)
ColdSend validates each inbox before assignment.

​
Step 4: Email Content

Create email variants and optional follow-up sequences: 
requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={
        "variants": [
            {
                "variant_name": "A",
                "subject_template": "Quick question about {{company}}",
                "email_content": "Hi {{first_name}},\n\n...",
                "distribution_percent": 60
            },
            {
                "variant_name": "B",
                "subject_template": "Introduction",
                "email_content": "Hello {{first_name}},\n\n...",
                "distribution_percent": 40
            }
        ]
    }
)

​
Step 5: Launch

Set current_step to 5 to launch the campaign: 
requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={"current_step": 5}
)
The campaign status changes to ACTIVE if leads exist, or PAUSED if no leads have been uploaded.

​
Step Progression Rules

  • You cannot skip steps (can only progress to current_step + 1)
  • You can update the current step multiple times
  • Campaigns must be in DRAFT status to update

​
Campaign Limits

  • Maximum 4 email variants per campaign
  • Maximum 3 follow-up sequences
  • Maximum 45 days total sequence duration
  • Maximum 30 days wait between any sequence step

​
Scheduling

​
Timezone

All scheduling respects the campaign’s timezone setting. Use IANA timezone format: 
America/New_York
Europe/London
Asia/Tokyo

​
Sending Days

Specify which days to send using numbers 1-7:
NumberDay
1Monday
2Tuesday
3Wednesday
4Thursday
5Friday
6Saturday
7Sunday

​
Sending Window

Define the hours during which emails are sent: 
{
  "sending_window_start": 9,
  "sending_window_end": 17
}
This sends emails between 9:00 AM and 5:00 PM in the campaign’s timezone.

​
Daily Limits

Control how many emails each sender account sends per day: 
{
  "daily_limit_per_inbox": 30
}
Set to null to use the inbox’s default limit.

​
Next Steps