# List campaigns (/api-reference/campaigns/listCampaigns)

`GET /campaigns`

Base URL: `https://next-api.useplunk.com`

Get a paginated list of email campaigns.

This endpoint uses **offset pagination** (`page` / `pageSize`), not the cursor pagination used by `GET /contacts`.

## Query parameters

- `page`: integer — 1-based page number.
- `pageSize`: integer — Items per page.
- `status`: enum ("DRAFT" | "SCHEDULED" | "SENDING" | "SENT" | "CANCELLED") — Filter by campaign status. An unrecognised value returns `400`.
- `search`: string — Case-insensitive match on name, subject, or sender address.
- `sort`: enum ("name" | "createdAt" | "updatedAt") — Column to sort by. Unrecognised values fall back to `createdAt`.
- `dir`: enum ("asc" | "desc") — Sort direction. Unrecognised values fall back to the default.

## Responses

### `200` — List of campaigns

- `data`: array<object>
  items:
    - `id`: string
    - `name`: string
    - `description`: string
    - `subject`: string
    - `body`: string
    - `from`: string (email)
    - `fromName`: string
    - `replyTo`: string (email)
    - `type`: enum ("TRANSACTIONAL" | "MARKETING" | "HEADLESS") — Content type of the campaign email. Not to be confused with `audienceType`.
    - `status`: enum ("DRAFT" | "SCHEDULED" | "SENDING" | "SENT" | "CANCELLED")
    - `audienceType`: enum ("ALL" | "SEGMENT" | "FILTERED")
    - `audienceCondition`: object — Set when `audienceType` is `FILTERED`.
    - `segmentId`: string — Set when `audienceType` is `SEGMENT`.
    - `scheduledFor`: string (date-time) — When the campaign is scheduled to send. Null for immediate or unsent campaigns.
    - `totalRecipients`: integer
    - `sentCount`: integer
    - `deliveredCount`: integer
    - `openedCount`: integer
    - `clickedCount`: integer
    - `bouncedCount`: integer
    - `projectId`: string
    - `sentAt`: string (date-time)
    - `createdAt`: string (date-time)
    - `updatedAt`: string (date-time)
- `page`: integer
- `pageSize`: integer
- `total`: integer — Total campaigns matching the filters, across all pages.
- `totalPages`: integer

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "subject": "string",
      "body": "string",
      "from": "user@example.com",
      "fromName": "string",
      "replyTo": "user@example.com",
      "type": "TRANSACTIONAL",
      "status": "DRAFT",
      "audienceType": "ALL",
      "audienceCondition": {
        "logic": "AND",
        "groups": [
          {
            "filters": [
              {
                "field": "string",
                "operator": "equals"
              }
            ]
          }
        ]
      },
      "segmentId": "string",
      "scheduledFor": "2026-08-09T17:56:20.150Z",
      "totalRecipients": 0,
      "sentCount": 0,
      "deliveredCount": 0,
      "openedCount": 0,
      "clickedCount": 0,
      "bouncedCount": 0,
      "projectId": "string",
      "sentAt": "2026-08-09T17:56:20.150Z",
      "createdAt": "2026-08-09T17:56:20.150Z",
      "updatedAt": "2026-08-09T17:56:20.150Z"
    }
  ],
  "page": 0,
  "pageSize": 0,
  "total": 0,
  "totalPages": 0
}
```

### `400` — Invalid `status` value.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.150Z"
}
```

### `401` — Missing or invalid API key.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.150Z"
}
```

## Example request

```bash
curl -X GET 'https://next-api.useplunk.com/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```