POST/api/v1/projects/{project_id}/campaigns/{campaign_id}/cancel

`cancel_campaign`

Cancels a scheduled, sending or paused campaign for good: its letters not sent yet are cancelled; letters already sent stay sent.

Call it: to stop a campaign that must not go on (a wrong audience, a campaign no longer wanted); pause_campaign holds one that may resume. Irreversible: it takes confirm: true; without it the call checks the same and changes nothing.
Needs: an admin key with project_id, or a project key with scope send (its own project; the argument is ignored); a draft, launching, completed or failed campaign is a conflict.
Returns: outcome (would_cancel, cancelled, already_cancelled), effect in words and the campaign as get_campaign returns it after the call: the same as POST /api/v1/projects/{project_id}/campaigns/{campaign_id}/cancel answers when confirmed.

Arguments

object
campaign_idstring · uuidrequired

The campaign’s id: a scheduled, sending or paused campaign.
confirmboolean

true cancels the campaign for good. Without it the call checks what the cancel checks, says what would happen and changes nothing.

default false
project_idstring · uuid | null

The campaign’s project. An admin key must pass it; a project key’s own project is used and this is ignored.

No other arguments are accepted.

Result

The result comes back as structuredContent, with the same JSON as a text block.

object · all fields required
campaignCampaign

The campaign after the call, as get_campaign returns it: the cancel’s answer (POST /api/v1/projects/{project_id}/campaigns/{campaign_id}/cancel) when confirmed; unchanged by a dry run.
23 fields
- Campaign object · all fields required
- completed_atstring · date-time | null
- created_atstring · date-time
- from_emailstring | null
  
  null: the project’s settings.from_email.
- from_namestring | null
  
  null: the project’s settings.from_name.
- idstring · uuid
- last_errorstring | null
  
  Why the launch failed; null unless failed.
- launched_atstring · date-time | null
- list_idsarray of string
  
  The lists it goes to, in the order given.
- namestring
- partial_versionsmap of string → integer · uint32
  
  The versions of the partials fixed at launch, by name; {} before.
- project_idstring · uuid
- reply_tostring | null
  
  null: the project’s settings.reply_to.
- scheduled_atstring · date-time | null
  
  When a scheduled campaign launches; null unless scheduled.
- shard_countinteger · uint32 | null
  
  Fixed at launch; null before.
  
  ≥ 0
- statusstring
  
  draft, scheduled, launching, sending, paused, completed, cancelled or failed.
- subject_overridestring | null
  
  null: the template’s subject.
- template_idstring · uuid
- template_versioninteger · uint32 | null
  
  The template’s version fixed at launch; null before.
  
  ≥ 0
- throttle_per_hourinteger · uint32 | null
  
  null: the project’s default_throttle_per_hour, or no limit.
  
  ≥ 0
- total_recipientsinteger · uint64 | null
  
  Recipients of the launch’s snapshot; null before.
  
  ≥ 0
- tracking_overrideTrackingOverride | null
  
  null: the project’s settings.tracking.
  2 fields
  
  TrackingOverride object · all fields required
  
  clicksboolean
  
  opensboolean
- transport_overridestring | null
  
  null: the project’s transport, then the node’s default.
- updated_atstring · date-time
  
  The latest change: creation, fields, status.
effectstring

The outcome in words, for the agent and its user.
outcomeCancelOutcome

What a cancel did.

would_cancel A dry run: nothing changed; a call with confirm: true cancels it.

cancelled Cancelled: no more of its letters go out.

already_cancelled It was cancelled already: nothing changed.

Definitions

Campaign

A campaign of a project (create_campaign, get_campaign, update_campaign; GET /api/v1/projects/{project_id}/campaigns/{campaign_id}).

object · all fields required
completed_atstring · date-time | null
created_atstring · date-time
from_emailstring | null

null: the project’s settings.from_email.
from_namestring | null

null: the project’s settings.from_name.
idstring · uuid
last_errorstring | null

Why the launch failed; null unless failed.
launched_atstring · date-time | null
list_idsarray of string

The lists it goes to, in the order given.
namestring
partial_versionsmap of string → integer · uint32

The versions of the partials fixed at launch, by name; {} before.
project_idstring · uuid
reply_tostring | null

null: the project’s settings.reply_to.
scheduled_atstring · date-time | null

When a scheduled campaign launches; null unless scheduled.
shard_countinteger · uint32 | null

Fixed at launch; null before.

≥ 0
statusstring

draft, scheduled, launching, sending, paused, completed, cancelled or failed.
subject_overridestring | null

null: the template’s subject.
template_idstring · uuid
template_versioninteger · uint32 | null

The template’s version fixed at launch; null before.

≥ 0
throttle_per_hourinteger · uint32 | null

null: the project’s default_throttle_per_hour, or no limit.

≥ 0
total_recipientsinteger · uint64 | null

Recipients of the launch’s snapshot; null before.

≥ 0
tracking_overrideTrackingOverride | null

null: the project’s settings.tracking.

see TrackingOverride
transport_overridestring | null

null: the project’s transport, then the node’s default.
updated_atstring · date-time

The latest change: creation, fields, status.

CancelOutcome

What a cancel did.

string · enum

would_cancel A dry run: nothing changed; a call with confirm: true cancels it.

cancelled Cancelled: no more of its letters go out.

already_cancelled It was cancelled already: nothing changed.

TrackingOverride

What a campaign tracks in place of the project’s.

object · all fields required
clicksboolean
opensboolean

Errors

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors

HTTP API

The same operation over HTTP: POST /api/v1/projects/{project_id}/campaigns/{campaign_id}/cancel