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

# Campaigns Overview

> Understand how campaigns work in ColdSend and the campaign workflow.

A campaign represents a single outreach effort in ColdSend. Each campaign contains leads, email variants, follow-up sequences, and sender accounts, working together to automate your cold email outreach.

## Campaign Lifecycle

Campaigns progress through distinct states:

<CardGroup cols={2}>
  <Card title="DRAFT" icon="square-pen">
    Campaign is being configured. You can add leads, assign inboxes, create email variants, and set up sequences.
  </Card>

  <Card title="ACTIVE" icon="play">
    Campaign is running and sending emails according to schedule and limits.
  </Card>

  <Card title="PAUSED" icon="pause">
    Campaign is temporarily stopped. No emails are being sent, but all configuration is preserved.
  </Card>

  <Card title="COMPLETED" icon="circle-check">
    All leads have been processed. No more emails will be sent.
  </Card>

  <Card title="FAILED" icon="triangle-alert">
    Campaign launch failed due to configuration issues or missing components.
  </Card>
</CardGroup>

## Campaign Workflow

Campaign creation and activation follows a component-based approach:

1. **Create Campaign** — Set core configuration (name, schedule, limits)
2. **Upload Leads** — Add recipients via CSV
3. **Assign Inboxes** — Select sender accounts for the campaign
4. **Design Emails** — Create email variants and follow-up sequences
5. **Launch** — Set `launch: true` to activate. The API validates all requirements automatically.

<Info>
  The public API does not expose internal step numbers. Simply provide the fields you want to update, and the system handles validation automatically. Set `launch: true` when you're ready to activate.
</Info>

### Step 1: Create Campaign

Initialize a campaign with core settings:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

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

    campaign_id = response.json()[campaign_id]
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.coldsend.pro/api/public/v1/campaigns \
      -H X-API-Key: cs_live_your_api_key_here \
      -H Content-Type: application/json \
      -d '{
        name: 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
      }'
    ```
  </Tab>
</Tabs>

### Step 2: Upload Leads

Leads are uploaded via CSV upload. See [Leads Management](/leads/overview) for detailed instructions.

### Step 3: Assign Inboxes & Configure Content

Update the campaign with inbox assignments, email variants, and sequences all in one `PUT` request:

```python theme={null}
response = requests.put(
    fhttps://api.coldsend.pro/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...,
                distribution_percent: 100
            }
        ]
    }
)
```

### Step 4: Launch

Set `launch: true` to activate:

```python theme={null}
response = requests.put(
    fhttps://api.coldsend.pro/api/public/v1/campaigns/{campaign_id},
    headers={X-API-Key: api_key},
    json={launch: True}
)
```

The response includes `is_launch_ready` and `missing_requirements` to help you check what's missing.

<Warning>
  When `launch: true`, the API validates that the campaign leads, inboxes, and email content are all configured. If requirements are missing, the campaign stays in DRAFT and the response tells you what's needed.
</Warning>

## Campaign Actions

### Pause Campaign

```python theme={null}
response = requests.post(
    fhttps://api.coldsend.pro/api/public/v1/campaigns/{campaign_id}/pause,
    headers={X-API-Key: api_key}
)
```

### Activate/Resume Campaign

```python theme={null}
response = requests.post(
    fhttps://api.coldsend.pro/api/public/v1/campaigns/{campaign_id}/activate,
    headers={X-API-Key: api_key}
)
```

### Delete Campaign

```python theme={null}
response = requests.delete(
    fhttps://api.coldsend.pro/api/public/v1/campaigns/{campaign_id},
    headers={X-API-Key: api_key}
)
```

<Warning>
  Only DRAFT or PAUSED campaigns can be deleted. This is permanent — all leads, sequences, and analytics are removed.
</Warning>

## Campaign Limits

| Category                | Limit                |
| ----------------------- | -------------------- |
| Email variants          | Max 4 per campaign   |
| Follow-up sequences     | Max 3 per campaign   |
| Total sequence duration | Max 45 days          |
| Max wait between steps  | Max 30 days per step |
| Leads per upload        | Max 10,000           |
| Max CSV file size       | 50MB                 |
| Campaign name           | 8-255 characters     |

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Campaign" icon="square-pen" href="/campaigns/create-campaign">
    Detailed guide for campaign creation with all available parameters.
  </Card>

  <Card title="Email Variants" icon="files" href="/campaigns/variants">
    Configure A/B testing variants and distribution.
  </Card>

  <Card title="Follow-up Sequences" icon="layers" href="/campaigns/sequences">
    Set up automated follow-up sequences.
  </Card>

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