Skip to main content
This guide walks you through creating your first campaign using the ColdSend API.
Complete this guide in approximately 10-15 minutes.

​
Prerequisites

  • ColdSend Account — Active account with API access
  • API Key — With scopes for campaigns and sender accounts
  • Development Environment — Python, JavaScript, cURL, etc.
  • Email Account — Sender email (ColdSend Native, Gmail, Outlook, or custom SMTP)

​
Step 1: Create an API Key

Navigate to Settings > API Keys in the ColdSend dashboard. Create a key with these scopes:
  • campaigns:create — Create campaigns
  • campaigns:update — Update campaign configuration
  • campaigns:read — View campaign data
  • sender_accounts:create — Add sender accounts
Store the key securely — it’s only shown once.

​
Step 2: Create a Campaign

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_id = response.json()["campaign_id"]
print(f"Campaign created: {campaign_id}")
The campaign is created with status DRAFT. You’ll configure leads, inboxes, and email content in the following steps.

​
Step 3: Add a Sender Account

​
Option A: ColdSend Native

ColdSend Native inboxes are managed addresses on a ColdSend-managed domain. 
response = requests.post(
    f"{base_url}/api/public/v1/sender-accounts/coldsend-native",
    headers={"X-API-Key": api_key},
    json={
        "domain_id": "550e8400-e29b-41d4-a716-446655440000",
        "email_prefix": "john",
        "display_name": "John Smith from Company"
    }
)
ColdSend Native inboxes require a domain_id from a domain already managed in your workspace. The full email will be john@yourdomain.com.

​
Option B: SMTP / BYOC

Connect your own email account via SMTP/IMAP: 
response = requests.post(
    f"{base_url}/api/public/v1/sender-accounts/smtp",
    headers={"X-API-Key": api_key},
    json={
        "email_address": "outreach@company.com",
        "display_name": "John Smith from Company",
        "inbox_type": "GOOGLE_WORKSPACE",
        "daily_limit": 50,
        "smtp_host": "smtp.gmail.com",
        "smtp_port": 587,
        "smtp_username": "outreach@company.com",
        "smtp_password": "your-app-password",
        "smtp_use_tls": True,
        "imap_host": "imap.gmail.com",
        "imap_port": 993,
        "imap_username": "outreach@company.com",
        "imap_password": "your-app-password",
        "imap_use_ssl": True
    }
)

inbox_id = response.json()["inbox_id"]
print(f"Sender account added: {inbox_id}")
Use an app-specific password, not your main email password. For Gmail, generate one at Google Account → Security → App Passwords.

​
Step 4: Configure Email Content & Assign Inboxes

Update the campaign with email content and inbox assignment: 
response = requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={
        "inbox_ids": ["inbox-id-uuid"],
        "variants": [
            {
                "variant_name": "A",
                "subject_template": "Quick question about {{company}}",
                "email_content": "Hi {{first_name}},\n\nI noticed {{company}} is expanding. I'd love to share how we've helped similar companies scale their outreach.\n\nBest,\nJohn",
                "distribution_percent": 100
            }
        ]
    }
)
You can also add follow-up sequences in the same update. See Follow-up Sequences for details.

​
Step 5: Launch the Campaign

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"Status: {result['status']}")
print(f"Launch ready: {result['is_launch_ready']}")
The API validates that the campaign has leads, inboxes, and email content configured. If requirements are missing, is_launch_ready will be false and missing_requirements tells you what’s needed.

​
Next Steps

Campaigns Overview

Learn the 5-step campaign workflow and all available actions.

Personalization

Use variables, spintax, and conditionals for personalized content.

Sender Accounts

Detailed guide for all sender account operations.