# Create Campaign

**POST** `/v1/campaigns`

Creates a new marketing campaign for email or SMS channels.

After creating a campaign, call **POST `/v1/campaigns/{{campaign_id}}/send`** to materialize recipients and start delivery. Creating a campaign does not send anything on its own.

---

### audience_type

Controls how recipients are resolved.

| Value | Description |
|---|---|
| `all_users` | Every user on the tenant |
| `user_attributes` | Filtered by behaviour/attributes via a saved audience |
| `audience_ids` | One or more saved audience segments |
| `list` | One or more contact lists (`list_ids`) |
| `custom` | Explicit email addresses, phone numbers, or a mix of lists + manual entries |

If `audience_type` is omitted, it is inferred automatically:
- Only `list_ids` provided → `list`
- `emails` or `phones` provided (with or without `list_ids`) → `custom`

---

### audience_config

Required when `audience_type` is `list`, `custom`, or `audience_ids`.

```json
// list — target members of one or more contact lists
{ "list_ids": [940121] }

// custom — explicit addresses
{ "emails": ["user@example.com", "other@example.com"] }

// custom — mix lists and manual emails in one campaign
{ "list_ids": [940121], "emails": ["vip@example.com"] }

// audience_ids — saved segments
{ "audience_ids": [123, 456] }

// user_attributes — attribute filter
{ "audience_type": "user", "filters": [...] }
```

---

### status

| Value | When to use |
|---|---|
| `draft` | Default. Campaign is saved but not ready to send. |
| `scheduled` | Set automatically by the backend when `schedule_type: "scheduled"` and a future `scheduled_at` is provided. Do not set this manually. |

> **Note:** `active` is accepted by the API but has no special behaviour — the campaign still requires a separate `/send` call to deliver.

---

### schedule_type

| Value | Description |
|---|---|
| `immediate` | Delivery starts as soon as `/send` is called. |
| `scheduled` | Delivery waits until `scheduled_at`. The backend sets `status: "scheduled"` automatically. |

---

### Response fields

**campaign.id** — Unique identifier of the newly created campaign. Pass this to `/send`.