> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the ColdSend API in minutes.

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

<Info>
  Complete this guide in approximately 10-15 minutes.
</Info>

## 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

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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}`);
    ```
  </Tab>
</Tabs>

<Info>
  The campaign is created with status `DRAFT`. You'll configure leads, inboxes, and email content in the following steps.
</Info>

## Step 3: Add a Sender Account

### Option A: ColdSend Native

ColdSend Native inboxes are managed addresses on a ColdSend-managed domain.

```python theme={null}
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"
    }
)
```

<Note>
  ColdSend Native inboxes require a `domain_id` from a domain already managed in your workspace. The full email will be `john@yourdomain.com`.
</Note>

### Option B: SMTP / BYOC

Connect your own email account via SMTP/IMAP:

```python theme={null}
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}")
```

<Warning>
  Use an app-specific password, not your main email password. For Gmail, generate one at Google Account → Security → App Passwords.
</Warning>

## Step 4: Configure Email Content & Assign Inboxes

Update the campaign with email content and inbox assignment:

```python theme={null}
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
            }
        ]
    }
)
```

<Info>
  You can also add follow-up sequences in the same update. See [Follow-up Sequences](/campaigns/sequences) for details.
</Info>

## Step 5: Launch the Campaign

```python theme={null}
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

<CardGroup cols={3}>
  <Card title="Campaigns Overview" href="/campaigns/overview" icon="mail">
    Learn the 5-step campaign workflow and all available actions.
  </Card>

  <Card title="Personalization" href="/campaigns/personalization" icon="sparkles">
    Use variables, spintax, and conditionals for personalized content.
  </Card>

  <Card title="Sender Accounts" href="/sender-accounts/overview" icon="inbox">
    Detailed guide for all sender account operations.
  </Card>
</CardGroup>