`https://lumail.io/api/v1/campaigns`

Retrieve a paginated list of all campaigns in your organization. Filter by status and search by name or subject.

## Response

- **Success (200 OK)** - Returns a paginated array of campaign objects.
- **Error (401 Unauthorized)** - Invalid or missing API token.

## Query Parameters

| Parameter | Type   | Default | Description                                                       |
| --------- | ------ | ------- | ----------------------------------------------------------------- |
| `status`  | string | `all`   | Filter by status: `all`, `DRAFT`, `ARCHIVED`, `SCHEDULED`, `SENT` |
| `page`    | number | `1`     | Page number for pagination                                        |
| `limit`   | number | `20`    | Number of campaigns per page (max 100)                            |
| `query`   | string | -       | Search campaigns by name or subject                               |
| `sortBy`  | string | -       | Sort order: `name`, `name_desc` (default: by date)                |

## Response Fields

| Field                            | Type           | Description                                      |
| -------------------------------- | -------------- | ------------------------------------------------ |
| `success`                        | boolean        | Indicates if the operation was successful        |
| `campaigns`                      | array          | Array of campaign objects                        |
| `campaigns[].id`                 | string         | Unique identifier for the campaign               |
| `campaigns[].campaignId`         | string         | Same as id (for consistency)                     |
| `campaigns[].name`               | string         | Name of the campaign                             |
| `campaigns[].subject`            | string         | Email subject line                               |
| `campaigns[].preview`            | string or null | Preview text for the email                       |
| `campaigns[].status`             | string         | Campaign status: DRAFT, SCHEDULED, SENDING, SENT |
| `campaigns[].contentType`        | string         | Content type: MAILY, PLATE, or MARKDOWN          |
| `campaigns[].sendAt`             | string or null | ISO timestamp when the campaign was sent         |
| `campaigns[].scheduledAt`        | string or null | ISO timestamp when the campaign is scheduled     |
| `campaigns[].recipientCount`     | number         | Number of recipients                             |
| `campaigns[].emailsSentCount`    | number         | Number of emails sent                            |
| `campaigns[].emailsOpenedCount`  | number         | Number of emails opened                          |
| `campaigns[].emailsClickedCount` | number         | Number of emails clicked                         |
| `campaigns[].createdAt`          | string         | ISO timestamp when the campaign was created      |
| `campaigns[].updatedAt`          | string         | ISO timestamp when the campaign was last updated |
| `total`                          | number         | Total number of campaigns matching the filter    |
| `page`                           | number         | Current page number                              |
| `limit`                          | number         | Number of items per page                         |
| `pageCount`                      | number         | Total number of pages                            |

## Usage Example

Use this API endpoint to:

- Display all campaigns in your application dashboard
- Build campaign management interfaces
- Monitor campaign statuses and performance
- Search for specific campaigns by name or subject
- Implement pagination for large campaign lists

## Related Documentation

- [Create Campaign](/docs/api-reference/api-campaigns-post) - Create a new campaign
- [Get Campaign](/docs/api-reference/api-campaign-get) - Get details for a specific campaign
- [Update Campaign](/docs/api-reference/api-campaign-patch) - Update a campaign
- [Delete Campaign](/docs/api-reference/api-campaign-delete) - Delete a campaign


## API Reference
**Method:** GET
**Endpoint:** /api/v1/campaigns

### SDK
```ts
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

const { campaigns, total, pageCount } = await lumail.campaigns.list({
  status: "DRAFT",
  page: 1,
  limit: 20,
});
console.log(campaigns);
```

### cURL
```bash
curl -X GET "https://lumail.io/api/v1/campaigns?status=DRAFT&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

### JavaScript
```javascript
const response = await fetch('https://lumail.io/api/v1/campaigns?status=DRAFT&page=1&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
```

### Python
```python
import requests

url = "https://lumail.io/api/v1/campaigns"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
params = {
    "status": "DRAFT",
    "page": 1,
    "limit": 20
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)
```

### Success Response
```json
{
  "success": true,
  "campaigns": [
    {
      "id": "cmp_abc123xyz",
      "campaignId": "cmp_abc123xyz",
      "name": "Welcome Newsletter",
      "subject": "Welcome to our community!",
      "preview": "We're excited to have you...",
      "status": "DRAFT",
      "contentType": "MAILY",
      "sendAt": null,
      "scheduledAt": null,
      "recipientCount": 0,
      "emailsSentCount": 0,
      "emailsOpenedCount": 0,
      "emailsClickedCount": 0,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T14:20:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "pageCount": 1
}
```

### Error Response
```json
{
  "message": "Invalid API token"
}
```