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

# Create Campaign

> Creates a new email campaign with default settings in DRAFTED status.

<Note>
  Creates a new email campaign with default settings in DRAFTED status Campaign name defaults to 'Untitled Campaign' if not provided
</Note>

## Overview

Creates a new email campaign with default settings in DRAFTED status

**Key Features**:

* Returns campaign ID and metadata.

## Query Parameters

<ParamField query="api_key" type="string" required>
  Your SmartLead API key for authentication
</ParamField>

## Request Body

<ParamField body="name" type="string">
  Campaign name. If not provided, defaults to "Untitled Campaign". Can be changed later via update settings.
</ParamField>

<ParamField body="client_id" type="number">
  Associate campaign with a specific client (for agency/white-label accounts). If not provided and user has client\_id, automatically uses that value.
</ParamField>

<Note>
  **Minimal Required Fields**: This endpoint only accepts `name` and `client_id`. Other campaign settings (track\_settings, schedule, sequences, etc.) must be configured using separate update endpoints after creation.
</Note>

## Response

<ResponseField name="ok" type="boolean">
  Always `true` for successful creation
</ResponseField>

<ResponseField name="id" type="number">
  Unique identifier for the newly created campaign
</ResponseField>

<ResponseField name="name" type="string">
  Campaign name (either provided or "Untitled Campaign")
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when campaign was created
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://server.smartlead.ai/api/v1/campaigns/create?api_key=YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q1 2024 Cold Outreach"
    }'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  url = "https://server.smartlead.ai/api/v1/campaigns/create"

  payload = {
      "name": "Q1 2024 Cold Outreach"
  }

  response = requests.post(
      url,
      params={"api_key": API_KEY},
      json=payload
  )

  result = response.json()
  print(f"Campaign created with ID: {result['id']}")
  print(f"Campaign name: {result['name']}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = 'YOUR_API_KEY';

  async function createCampaign() {
    const response = await fetch(
      `https://server.smartlead.ai/api/v1/campaigns/create?api_key=${API_KEY}`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name: 'Q1 2024 Cold Outreach'
        }),
      }
    );
    
    const data = await response.json();
    console.log(`Campaign created with ID: ${data.id}`);
    return data;
  }

  createCampaign();
  ```
</RequestExample>

## Response Codes

<ResponseField name="200" type="Success">
  Campaign created successfully
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Invalid request parameters or malformed request body
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key. Check your authentication.
</ResponseField>

<ResponseField name="422" type="Validation Error">
  Request validation failed. Check parameter types and required fields.
</ResponseField>

<ResponseField name="429" type="Rate Limit Exceeded">
  Too many requests. Please slow down and retry after the rate limit resets.
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error occurred. Please try again or contact support if the issue persists.
</ResponseField>

<ResponseField name="503" type="Service Unavailable">
  API is temporarily unavailable or under maintenance. Please try again later.
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "ok": true,
    "id": 125,
    "name": "Q1 2024 Cold Outreach",
    "created_at": "2024-01-25T10:30:00Z"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Invalid API Key"
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "error": "Invalid campaign name format"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "error": "Error while creating email campaign - Database connection failed"
  }
  ```
</ResponseExample>

## Implementation Details

**What Happens**:

1. Campaign is created with minimal data (just name and optional client\_id)
2. Campaign starts in **DRAFTED** status
3. Campaign name defaults to "Untitled Campaign" if not provided
4. Client ID is automatically set if user is a client
5. Returns campaign ID immediately for further configuration

**Default Settings**:

* Status: `DRAFTED`
* Track Settings: Not set (configure later)
* Schedule: Not set (configure later)
* Sequences: Empty (add later)
* Email Accounts: None (add later)
* Leads: None (add later)

**Response Format**: Direct object with `ok`, `id`, `name`, `created_at`

<Warning>
  **Newly created campaigns cannot send emails yet**. You must configure sequences, add email accounts, and add leads before starting the campaign.
</Warning>

## Next Steps

After creating a campaign, follow this workflow:

<Steps>
  <Step title="Add Email Sequences">
    Create your email sequence (initial email + follow-ups)

    ```bash theme={null}
    POST /v1/campaigns/{campaign_id}/sequences
    ```

    [Update Sequences](/api-reference/campaigns/update-sequences)
  </Step>

  <Step title="Add Email Accounts">
    Associate sender email accounts with the campaign

    ```bash theme={null}
    POST /v1/campaigns/{campaign_id}/email-accounts
    ```

    [Add Email Accounts](/api-reference/campaigns/add-email-accounts)
  </Step>

  <Step title="Add Leads">
    Upload your prospect list (up to 400 leads per request)

    ```bash theme={null}
    POST /v1/campaigns/{campaign_id}/leads
    ```

    [Add Leads](/api-reference/leads/add-to-campaign)
  </Step>

  <Step title="Configure Schedule">
    Set sending hours, timezone, and frequency

    ```bash theme={null}
    PATCH /v1/campaigns/{campaign_id}/schedule
    ```

    [Update Schedule](/api-reference/campaigns/update-schedule)
  </Step>

  <Step title="Configure Settings">
    Set tracking, limits, and stop conditions

    ```bash theme={null}
    PATCH /v1/campaigns/{campaign_id}/settings
    ```

    [Update Settings](/api-reference/campaigns/update-settings)
  </Step>

  <Step title="Start Campaign">
    Activate the campaign to begin sending

    ```bash theme={null}
    PATCH /v1/campaigns/{campaign_id}/status
    ```

    [Update Status](/api-reference/campaigns/update-status)
  </Step>
</Steps>

## Campaign Naming Best Practices

<AccordionGroup>
  <Accordion title="Use Descriptive Names">
    Choose names that clearly indicate the campaign purpose and timeframe

    * ✅ Good: "SaaS Founders Q1 2024"
    * ❌ Bad: "Campaign 1"
  </Accordion>

  <Accordion title="Include Time Period">
    Add the quarter or month to track performance over time

    * "Q1 2024 Enterprise Outreach"
    * "Jan 2024 Product Launch"
  </Accordion>

  <Accordion title="Indicate Target Audience">
    Make it clear who you're targeting

    * "Healthcare CFOs - Q1"
    * "Tech Startup CTOs"
  </Accordion>
</AccordionGroup>

## Complete Example Workflow

```python Python - Complete Campaign Setup theme={null}
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://server.smartlead.ai/api/v1"

# 1. Create campaign
campaign = requests.post(
    f"{BASE_URL}/campaigns/create",
    params={"api_key": API_KEY},
    json={"name": "Q1 2024 Outreach"}
).json()

campaign_id = campaign['id']
print(f"Created campaign {campaign_id}")

# 2. Add sequences
requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/sequences",
    params={"api_key": API_KEY},
    json={
        "sequences": [
            {
                "seq_number": 1,
                "subject": "Quick question",
                "email_body": "Hi {{first_name}}...",
                "seq_delay_details": {"delay_in_days": 0}
            }
        ]
    }
)
print("Added sequences")

# 3. Add email accounts
requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/email-accounts",
    params={"api_key": API_KEY},
    json={"email_account_ids": [456, 457]}
)
print("Added email accounts")

# 4. Add leads
requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/leads",
    params={"api_key": API_KEY},
    json={
        "lead_list": [
            {"email": "john@example.com", "first_name": "John"}
        ]
    }
)
print("Added leads")

# 5. Start campaign
requests.patch(
    f"{BASE_URL}/campaigns/{campaign_id}/status",
    params={"api_key": API_KEY},
    json={"status": "ACTIVE"}
)
print(f"Campaign {campaign_id} is now ACTIVE!")
```

## Related Endpoints

* [Get Campaign by ID](/api-reference/campaigns/get-by-id)
* [Update Campaign Settings](/api-reference/campaigns/update-settings)
* [Update Campaign Schedule](/api-reference/campaigns/update-schedule)
* [Add Email Sequences](/api-reference/campaigns/update-sequences)
* [Add Email Accounts](/api-reference/campaigns/add-email-accounts)
* [Add Leads to Campaign](/api-reference/leads/add-to-campaign)
* [Start Campaign](/api-reference/campaigns/update-status)