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

# Campaigns

> Create and manage bulk message campaigns with tracking

## What Are Campaigns?

Campaigns enable bulk message delivery to multiple recipients with centralized tracking and management.

## Creating a Campaign

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/campaigns \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Spring Promotion",
      "template_id": "tmpl_abc123",
      "sender_id": "sender_xyz789",
      "schedule_at": "2026-03-01T09:00:00Z"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/campaigns', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Spring Promotion',
      template_id: 'tmpl_abc123',
      sender_id: 'sender_xyz789',
      schedule_at: '2026-03-01T09:00:00Z'
    })
  });
  const campaign = await response.json();
  ```

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

  response = requests.post(
      'https://api-message.nativehub.live/api/v1/campaigns',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Spring Promotion',
          'template_id': 'tmpl_abc123',
          'sender_id': 'sender_xyz789',
          'schedule_at': '2026-03-01T09:00:00Z'
      }
  )
  campaign = response.json()
  ```
</CodeGroup>

## Importing Recipients

### CSV Format

CSV must include a `phone` column. Additional columns map to template variables:

```csv theme={null}
phone,name,code
+1234567890,John,SAVE20
+9876543210,Jane,SAVE20
```

### Upload Recipients

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/recipients \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "file=@recipients.csv"
  ```

  ```javascript Node.js theme={null}
  const formData = new FormData();
  formData.append('file', fs.createReadStream('recipients.csv'));

  const response = await fetch(
    'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/recipients',
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
      body: formData
    }
  );
  const result = await response.json();
  ```

  ```python Python theme={null}
  files = {'file': open('recipients.csv', 'rb')}
  response = requests.post(
      'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/recipients',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      files=files
  )
  result = response.json()
  ```
</CodeGroup>

<Info>
  Duplicates and DNC numbers are automatically filtered during import.
</Info>

## Campaign Lifecycle

| Status      | Description          |
| ----------- | -------------------- |
| `draft`     | Created, not started |
| `running`   | Actively sending     |
| `paused`    | Temporarily stopped  |
| `completed` | All messages sent    |
| `cancelled` | Manually stopped     |

## Managing Campaigns

### Start Campaign

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/start \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/start', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/start',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  ```
</CodeGroup>

### Pause Campaign

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/pause \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/pause', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/pause',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  ```
</CodeGroup>

### Cancel Campaign

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/cancel \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/cancel', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/cancel',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  ```
</CodeGroup>

<Warning>
  Cancelled campaigns cannot be restarted. Messages already queued may still send.
</Warning>

## Monitoring Progress

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123',
    {
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    }
  );
  const campaign = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  campaign = response.json()
  ```
</CodeGroup>

Response includes delivery counts:

```json theme={null}
{
  "id": "cmp_abc123",
  "name": "Spring Promotion",
  "status": "running",
  "stats": {
    "total": 10000,
    "sent": 7500,
    "delivered": 7200,
    "failed": 150,
    "pending": 2500
  }
}
```

## Viewing Recipients

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/recipients?page=1&per_page=20" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/recipients?page=1&per_page=20',
    {
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    }
  );
  const recipients = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api-message.nativehub.live/api/v1/campaigns/cmp_abc123/recipients',
      params={'page': 1, 'per_page': 20},
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  recipients = response.json()
  ```
</CodeGroup>

Response format:

```json theme={null}
{
  "data": [
    {
      "phone": "+1234567890",
      "variables": {"name": "John", "code": "SAVE20"},
      "status": "delivered",
      "sent_at": "2026-03-01T09:05:00Z"
    }
  ],
  "total": 10000,
  "page": 1,
  "per_page": 20
}
```