PATCH /v1/brands/{brand_id}/campaigns/{campaign_id}

Update, launch, pause or end a campaign

scope write:outreach cost 1 RU idempotent optional

Change a campaign's settings, or its state through status:

active launches a draft or resumes a paused campaign. Real emails go out from its mailbox in the send window, within the mailbox's daily limit and warmup, skipping unsubscribed and blocked addresses. It needs the brand owner on an active subscription, not a trial (403 brand_plan_required), and a connected mailbox (400 integration_not_connected with details.connect_url).
paused stops sending until it is active again.
completed ends it for good; its remaining emails are not sent.
archived hides a campaign that is not active.

An active campaign must be paused before its list, emails or mailbox change. The call is the caller's intent: it runs with no confirmation step. Requires the editor role and the brand owner on Pro. A client seat cannot reach campaigns.

Path parameters

campaign_id string required

Campaign id.
brand_id string required

Brand UUID.

Query parameters

dry_run boolean optional

Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

default: false

Header parameters

Idempotency-Key string optional

Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required

Type: CampaignUpdate

contact_list_id string (nullable) nullable

The contact list it emails.
daily_limit integer (nullable) nullable

Emails a day (1 to 500).
description string (nullable) nullable

Description.
mailbox_id string (nullable) nullable

The Gmail mailbox, from GET /v1/me/mailboxes.
name string (nullable) nullable

Name.
re_enrollment_behavior enum (nullable) nullable

skip (default), continue or restart.
send_interval_minutes integer (nullable) nullable

Minutes between two sends: 0, or 10 and up.
send_window_end string (nullable) nullable

HH:MM.
send_window_start string (nullable) nullable

HH:MM.
send_window_timezone string (nullable) nullable

An IANA time zone.
sequence_id string (nullable) nullable

A sequence, which sends on its own.
skip_unsubscribe_footer boolean (nullable) nullable

Send without an unsubscribe footer (default true).
skip_weekends boolean (nullable) nullable

Skip weekends.
status enum (nullable) nullable

active launches a draft or resumes a paused campaign: real emails go out. paused stops sending until it is active again. completed ends it for good. archived hides an ended or draft campaign.
template_id string (nullable) nullable

A single email, sent as drafts to review.

Example payload

{
  "status": "active"
}

Responses

Update, launch, pause or end a campaign application/json

Type: Campaign

brand_id string required

Owning brand id.
id string required

Campaign id.
name string required

Name.
re_enrollment_behavior enum required

A contact already emailed by another campaign: skip, continue or restart.
send_interval_minutes integer required

Minutes between two sends; 0 sends as fast as allowed.

min: 0
send_window_timezone string required

The window's IANA time zone.
skip_unsubscribe_footer boolean required

Whether its emails go out without an unsubscribe footer.
skip_weekends boolean required

Whether it sends on weekends.
stats CampaignStats required

What its emails did.
Show fields

Type: CampaignStats
- bounce_rate number required
  
  Bounced over sent, in percent.
- emails_bounced integer required
  
  Bounced.
  
  min: 0
- emails_opened integer required
  
  Opened.
  
  min: 0
- emails_replied integer required
  
  Replied to.
  
  min: 0
- emails_sent integer required
  
  Sent.
  
  min: 0
- open_rate number required
  
  Opened over sent, in percent.
- reply_rate number required
  
  Replied over sent, in percent.
- total_emails integer required
  
  Emails the campaign created.
  
  min: 0
status enum required

draft, active (sending), paused, completed (ended for good) or archived.
completed_at string (nullable) nullable

When it was ended.

format: `date-time`
contact_list_id string (nullable) nullable

The contact list it emails.
created_at string (nullable) nullable

When it was created.

format: `date-time`
daily_limit integer (nullable) nullable

The most it sends a day; the mailbox's cap also holds.
description string (nullable) nullable

Description.
mailbox_id string (nullable) nullable

The Gmail mailbox it sends from.
next_scheduled_email CampaignNextEmail (nullable) nullable

The next email due, while it is active or paused.
object string

default: `campaign`
paused_at string (nullable) nullable

When it was last paused.

format: `date-time`
send_window_end string (nullable) nullable

End of the daily window (HH:MM).
send_window_start string (nullable) nullable

Start of the daily window (HH:MM).
sequence_id string (nullable) nullable

A sequence it runs, sending on its own.
started_at string (nullable) nullable

When it was launched.

format: `date-time`
template_id string (nullable) nullable

A single email it sends, as drafts to review.
updated_at string (nullable) nullable

Last change.

format: `date-time`

Example response

{
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "contact_list_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "created_at": "2026-09-21T10:00:00+00:00",
  "daily_limit": 30,
  "id": "8192a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "mailbox_id": "5e6f7081-92a3-4b4c-8d5e-6f708192a3b4",
  "name": "Best running shoes lists",
  "object": "campaign",
  "re_enrollment_behavior": "skip",
  "send_interval_minutes": 10,
  "send_window_end": "17:00",
  "send_window_start": "09:00",
  "send_window_timezone": "America/New_York",
  "sequence_id": "4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d",
  "skip_unsubscribe_footer": true,
  "skip_weekends": true,
  "started_at": "2026-09-22T09:00:00+00:00",
  "stats": {
    "bounce_rate": 3.3,
    "emails_bounced": 1,
    "emails_opened": 18,
    "emails_replied": 4,
    "emails_sent": 30,
    "open_rate": 60,
    "reply_rate": 13.3,
    "total_emails": 42
  },
  "status": "active",
  "updated_at": "2026-09-22T09:00:00+00:00"
}

Request validation failed application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentials application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resource application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource not found application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflict application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request body did not match the expected schema application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceeded application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurred application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retry application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request PATCH \
  --url 'https://api.rankprompt.com/v1/brands/your_brand_id_here/campaigns/your_campaign_id_here?dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "active"
}'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/campaigns/your_campaign_id_here?dry_run=false';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"status":"active"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands/your_brand_id_here/campaigns/your_campaign_id_here"

querystring = {"dry_run":"false"}

payload = { "status": "active" }
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers, params=querystring)

print(response.json())