---
title: "List campaigns"
method: GET
path: "/api/v1/campaigns"
tags: ["Campaigns"]
---

# List campaigns

`GET /api/v1/campaigns`

## Request

- Base URL: `https://mailcheer.com`
- URL: `https://mailcheer.com/api/v1/campaigns`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Permission required: `campaigns:read`.

## Query parameters

- `limit` integer
- `cursor` string
- `status` 'draft' | 'scheduled' | 'sending' | 'sent' | 'archived'

## Response `200`

The requested page.

- object: The envelope of every list. To walk through it: as long as `has_more` is `true`, call the same address again with `?cursor=<next_cursor>`. The order is stable; a page returns at most `limit` items (50 by default, 100 at most).
  - `object` 'list'
  - `data` object[]
    - `id` string
    - `object` 'campaign'
    - `name` string
    - `subject` string, nullable
    - `kind` string
    - `status` 'draft' | 'scheduled' | 'sending' | 'sent' | 'archived'
    - `from` string, nullable
    - `scheduled_at` string, date-time, nullable
    - `sent_at` string, date-time, nullable
    - `created_at` string, date-time
    - `schedule_error` string, nullable: Why a scheduled send did not go out.
    - `stats` object: A bot is an open or a click within two minutes of delivery (security gateways visit every link as the message arrives; privacy relays preload images), or one from a robot that declares itself in its user agent or comes from an address range its operator publishes (Google, Bing). Privacy relays (Apple Mail, Gmail, Yahoo) are not bots in themselves.
      - `recipients` integer
      - `sent` integer
      - `delivered` integer
      - `opened` integer
      - `clicked` integer
      - `bounced` integer
      - `complained` integer
      - `open_rate` number, nullable: Percentage of delivered messages opened at least once, one decimal — bots included, as most tools count it.
      - `click_rate` number, nullable: Percentage of delivered messages clicked at least once, one decimal — bots included.
      - `human_opened` integer: Messages opened (or clicked) at least once by a person, bots set aside.
      - `human_clicked` integer: Messages clicked at least once by a person, bots set aside.
      - `human_open_rate` number, nullable: `open_rate` without bots: the closest figure to real readings.
      - `human_click_rate` number, nullable: `click_rate` without bots.
      - `opens_tracked` boolean: `false` when every delivered message went out without an open-tracking pixel (the workspace's “Track opens” setting was off): `open_rate` and `human_open_rate` are then `null`. Open figures only count messages that carried the pixel.
  - `has_more` boolean: One more page after this one.
  - `next_cursor` string, nullable: To pass back as `?cursor=` for the next page. `null` on the last page.

## Other responses

- `401`: Key missing, unknown or revoked.
- `403`: The key does not have the requested permission, or the workspace cannot send: `sending_blocked` (suspended, blocked or banned — nothing goes out, through any channel), `commitment_required` (the anti-spam commitment is not accepted), `reputation_blocked` (too many bounces or complaints).

---

[API](https://skmtc.dev/mailcheer/apis/mailcheer-api.md) · [All operations](https://skmtc.dev/mailcheer/apis/mailcheer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailcheer/apis/mailcheer-api/revisions/ba64b7ef2170?raw)