# List SMS campaigns

`GET /campaigns`

Returns SMS campaigns for one shop (`shop_id`) or all your shops,
sorted by creation date descending, with their messages and sending
status.

Requires the `campaigns:read` scope.

**Returns** a `data` array of up to `limit` campaigns and a
`pagination` object. Fetch the next page by passing
`pagination.next_cursor` back as `cursor`, until `has_more` is
`false`. `data` is empty when nothing matches the filters.

Each campaign embeds its `messages` with their individual content, date
and sending status, so one call is enough to reconstruct a campaign
timeline.

## Example request

```bash
curl "https://api.dokaa.app/v1/campaigns" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string) – Restrict to a single shop (omit to query all your shops)
- `status` (string) (one of: draft, sending, ended, cancelled, error) – Filter by campaign status
- `from` (string) (format: date) – Only campaigns created on or after this date
- `to` (string) (format: date) – Only campaigns created on or before this date
- `cursor` (string) – Opaque cursor from the previous response's `pagination.next_cursor`
- `limit` (integer) (default: 25; min: 1; max: 100) – Number of items per page

## Responses

### 200 – Paginated list of campaigns

```json
{
  "data": [
    {
      "id": "66d4e5f6a7b8c9d0e1f2a3b4",
      "shop_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Offre rentrée",
      "status": "ended",
      "type": "one-shot",
      "contact_amount": 320,
      "messages": [
        {
          "content": "Profitez de -20% cette semaine chez Pizza Marcel !",
          "date": "2026-07-10T11:00:00Z",
          "status": "sent"
        }
      ],
      "created_at": "2026-07-08T09:30:00Z",
      "updated_at": "2026-07-10T11:05:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}
```

### 401 – Missing, invalid, or revoked API key

### 403 – The API key does not grant access to this resource

### 422 – Invalid request parameters

Errors are `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail` fields.