Campaigns

Overview

There is no create or send endpoint here, deliberately. Every bulk send holds for explicit approval by the workspace owner before a single recipient is enqueued — see Bulk send. An endpoint that created and sent a campaign in one call would go around that, so it does not exist. An agent can see what is scheduled and stop it; it cannot start one.

Listing requires campaigns:read. Cancelling requires campaigns:cancel — a scope named for what it can do and nothing else.

The campaign object

Status, timing and identity. The campaign body — subject and content — is never returned.

{
  "id": "8f14e45f-ceea-467a-9c6f-2b1c3e4d5a6b",
  "name": "August product notes",
  "status": "scheduled",
  "topic_id": "3a2b1c0d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "scheduled_send_at": "2026-09-02T09: 00: 00.000Z",
  "sent_at": null,
  "created_at": "2026-08-28T14: 02: 11.000Z"
}

List campaigns

GET /api/v1/campaigns — newest first, cursor-paginated. See Pagination.

"color:#ff7b72">import { PristineSend } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

for "color:#ff7b72">await ("color:#ff7b72">const campaign of "color:#ff7b72">await ps.campaigns.list({ limit: 25 })) {
  console.log(campaign.name, campaign.status, campaign.scheduled_send_at)
}

Clicked links

GET /api/v1/campaigns/{id}/links — every link in the campaign that was clicked, ranked most-clicked first. Requires campaigns:read.

"color:#ff7b72">const { data, total_links, opt_out_clicks, reconstructed_clicks } =
  "color:#ff7b72">await ps.campaigns.links("8f14e45f-ceea-467a-9c6f-2b1c3e4d5a6b", { limit: 20 })

for ("color:#ff7b72">const link of data) {
  // `unique_clicks` is people, `clicks` is presses.
  console.log(link.url, link.clicks, link.unique_clicks)
}

This is a leaderboard, not a paginated collection, so there is no cursor. limit takes the top N and total_links tells you how many distinct links were clicked — so a truncated list is visible as one.

Unsubscribe links are never in data. They are counted in opt_out_clicks and never named, because those URLs carry a live one-click opt-out token — returning one would let a read-only key opt a recipient out. Two consequences worth planning for: an empty data beside a non-zero opt_out_clicks means the only thing anyone pressed was the way out, which is not the same as nobody clicking; and opt_out_clicks counts presses on an opt-out link rather than completed unsubscribes, so quote unsubscribed from Metrics for that.

clicks counts presses and unique_clicks counts people, so any rate you compute against the number of readers must use unique_clicks — otherwise one enthusiastic recipient can push it over 100%.

reconstructed_clicks above zero means some of these totals were rebuilt from an older record that kept only the most recent click per recipient, so report them as a minimum. null there means we could not determine it, which is not the same as 0.

A transactional message belongs to no campaign, so its clicks are read from GET /api/v1/emails/{id}/clicks instead.

Cancel a scheduled campaign

POST /api/v1/campaigns/{id}/cancel — only a campaign in scheduled can be cancelled.

"color:#ff7b72">await ps.campaigns.cancel("8f14e45f-ceea-467a-9c6f-2b1c3e4d5a6b")

The check is race-safe. If the send worker claimed the campaign moments before your request, nothing is cancelled and you get a 404 — rather than a success for something that did not happen.

One narrow window remains and is worth knowing about: if the worker had already claimed a batch when the cancel landed, that one batch may still go out. Every subsequent batch is stopped.

Errors

A campaign that cannot be cancelled — already sending, already sent, or not yours — returns 404 not_found. These are deliberately the same response: telling them apart would confirm the existence of another workspace's campaign id. See Errors.