Skip to main content

​
Quickstart

This guide walks you through creating your first campaign using the ColdSend API.

​
Prerequisites

  • A ColdSend account with an active subscription
  • An API key with appropriate scopes

​
Step 1: Create an API Key

  1. Log in to your ColdSend dashboard
  2. Navigate to Settings > API Keys
  3. Click “Create API Key”
  4. Enter a descriptive name (e.g., “Integration Key”)
  5. Select scopes: campaigns:write and sender_accounts:write
  6. Copy and securely store the key
The full API key is only displayed once. Store it in a secure location such as a secrets manager.

​
Step 2: Create a Campaign

Use the POST /api/public/v1/campaigns endpoint to create a new campaign: 
import requests

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

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}")
Response: 
{
  "success": true,
  "message": "Campaign created successfully",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Product Launch Outreach",
  "status": "DRAFT",
  "current_step": 0,
  "created_at": "2024-01-15T10:30:00Z"
}

​
Step 3: Add a Sender Account

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

inbox = response.json()
inbox_id = inbox["inbox_id"]
print(f"Sender account added: {inbox_id}")
Use an app-specific password, not your main email password. App passwords provide limited access and can be revoked independently.

​
Step 4: Configure Email Content

Add email variants and assign the sender account: 
response = requests.put(
    f"{base_url}/api/public/v1/campaigns/{campaign_id}",
    headers={"X-API-Key": api_key},
    json={
        "inbox_ids": [inbox_id],
        "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.\n\nBest,\nJohn",
                "distribution_percent": 100
            }
        ]
    }
)

print(f"Campaign updated: {response.json()}")

​
Step 5: Launch the Campaign

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

result = response.json()
print(f"Campaign status: {result['status']}")
The campaign requires leads before it can activate. Upload leads through the ColdSend dashboard or via the lead upload endpoints in the internal API.

​
Next Steps