Skip to main content

​
Create Campaign

Use the API to create and configure campaigns programmatically.

​
Create a New Campaign

POST /api/public/v1/campaigns 
import requests

response = requests.post(
    "https://api.coldsend.io/api/public/v1/campaigns",
    headers={"X-API-Key": "cs_live_your_api_key"},
    json={
        "name": "Q1 Product Launch",
        "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
    }
)

​
Request Fields

FieldTypeRequiredDescription
namestringYesCampaign name (8-255 characters)
timezonestringNoIANA timezone (default: America/New_York)
sending_daysarrayNoDays to send, 1-7 (default: [1,2,3,4,5])
sending_window_startintegerNoStart hour, 0-23 (default: 9)
sending_window_endintegerNoEnd hour, 1-24 (default: 17)
daily_limit_per_inboxintegerNoMax emails per inbox per day (1-100)
start_datestringNoISO 8601 datetime to start campaign
enable_trackingbooleanNoEnable open tracking (default: false)
enable_unsubscribebooleanNoAdd unsubscribe link (default: true)

​
Response

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

​
Update Campaign

PUT /api/public/v1/campaigns/{campaign_id} Update any campaign field during the configuration process: 
response = requests.put(
    f"https://api.coldsend.io/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": "cs_live_your_api_key"},
    json={
        "name": "Updated Campaign Name",
        "daily_limit_per_inbox": 50,
        "inbox_ids": [inbox_id],
        "variants": [...],
        "sequences": [...]
    }
)

​
Updatable Fields

You can update the following fields: Basic Settings
  • name - Campaign name
  • timezone - IANA timezone
  • sending_days - Days of the week to send
  • sending_window_start - Start hour
  • sending_window_end - End hour
  • daily_limit_per_inbox - Per-inbox daily limit
  • enable_tracking - Open tracking toggle
  • enable_unsubscribe - Unsubscribe link toggle
Lead Configuration
  • lead_mapping - CSV column to field mapping
Sender Accounts
  • inbox_ids - Array of inbox UUIDs
Email Content
  • variants - Array of email variants
  • sequences - Array of follow-up sequences
Workflow
  • current_step - Progress to next step (1-5)

​
Response

{
  "success": true,
  "message": "Campaign updated successfully",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_step": 3,
  "status": "DRAFT",
  "updated_at": "2024-01-15T11:00:00Z",
  "inbox_validations": [
    {
      "inbox_id": "650e8400-e29b-41d4-a716-446655440000",
      "is_valid": true
    }
  ]
}
The inbox_validations array is included when you update inbox_ids, showing whether each inbox passed validation.

​
Delete Campaign

DELETE /api/public/v1/campaigns/{campaign_id} Permanently delete a campaign: 
response = requests.delete(
    f"https://api.coldsend.io/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": "cs_live_your_api_key"}
)
Deletion is permanent. All campaign data including leads, variants, and analytics will be removed.

​
Validation Errors

​
Invalid Timezone

{
  "detail": [
    {
      "loc": ["body", "timezone"],
      "msg": "Invalid timezone: America/Invalid",
      "type": "value_error"
    }
  ]
}

​
Invalid Sending Window

{
  "detail": "sending_window_end must be greater than sending_window_start"
}

​
Campaign Name Too Short

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "ensure this value has at least 8 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}