Quickstart

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

Python
JavaScript

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}")

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_id } = await response.json();
console.log(`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.

Getting Started

Authentication

Campaigns

Sender Accounts

Domains

Leads

Replies

Analytics

Reference

Compliance

Prerequisites

Step 1: Create an API Key

Step 2: Create a Campaign

Step 3: Add a Sender Account

Option A: ColdSend Native

Option B: SMTP / BYOC

Step 4: Configure Email Content & Assign Inboxes

Step 5: Launch the Campaign

Next Steps

Campaigns Overview

Personalization

Sender Accounts

​Prerequisites

​Step 1: Create an API Key

​Step 2: Create a Campaign

​Step 3: Add a Sender Account

​Option A: ColdSend Native

​Option B: SMTP / BYOC

​Step 4: Configure Email Content & Assign Inboxes

​Step 5: Launch the Campaign

​Next Steps

Campaigns Overview

Personalization

Sender Accounts

Prerequisites

Step 1: Create an API Key

Step 2: Create a Campaign

Step 3: Add a Sender Account

Option A: ColdSend Native

Option B: SMTP / BYOC

Step 4: Configure Email Content & Assign Inboxes

Step 5: Launch the Campaign

Next Steps