API Reference

Campaigns

List and read your campaigns, make and edit drafts, and cancel one that is scheduled but has not started sending.

Overview

The API makes and edits drafts, and never sends one. A draft is sent by a person in PristineSend, or asked for through Bulk send, which holds for explicit approval by the workspace owner before a single recipient is enqueued. An endpoint that created and sent a campaign in one call would go around that, so none exists. Making and editing drafts is on Campaign drafts.

Listing and reading require campaigns:read. Cancelling requires campaigns:cancel, a scope named for what it can do and nothing else; it can stop a send, never start one.

The campaign object

Status, timing and identity. name is the campaign's subject line, which is what the app calls it, and null when the subject is blank. version is raised each time a draft's email, sender or topic changes, open_notes counts the notes a person left on it for their AI that nobody has resolved, and app_url is where it opens in PristineSend: the editor, its report once it is sent, or the approval screen while a bulk send waits there. The email itself is not in the list: read one campaign with GET /api/v1/campaigns/{id}.

{
  "id": "8f14e45f-ceea-467a-9c6f-2b1c3e4d5a6b",
  "name": "August product notes",
  "status": "scheduled",
  "version": 4,
  "open_notes": 0,
  "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",
  "app_url": "https://pristinesend.com/campaigns/8f14e45f-ceea-467a-9c6f-2b1c3e4d5a6b"
}

List campaigns

GET /api/v1/campaigns — newest first, cursor-paginated (see Pagination). status keeps one status: draft, scheduled, sending, sent, paused, cancelled or pending_approval.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

for await (const campaign of await ps.campaigns.list({ status: "draft" })) {
  console.log(campaign.name, campaign.version, campaign.open_notes, campaign.app_url)
}

Cancel a scheduled campaign

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

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.