Campaign Reruns

This API provides campaign rerun management capabilities, enabling external systems to view rerun history, inspect run-specific messages, and initiate new reruns against updated customer groups — all without manual intervention through the platform UI.

Introduction

The Campaign Reruns API enables organisations to automate and integrate campaign refresh workflows:

Rerun History: Retrieve a complete audit trail of all campaign runs with status and customer group metadata

Run Messages: Inspect the generated messages for any specific run, including segment and review data

Rerun Initiation: Trigger a new campaign run against a different customer group in a single atomic API call

Segment Intelligence: Automatic reuse of existing approved messages where segments match, with new generation only where needed

Async Processing: Background job queue handles large-scale message generation without blocking your integration

These endpoints are designed for CRM systems, marketing automation platforms, and external integrations that need to programmatically refresh campaign messages as customer data changes over time.

Field Descriptions

Rerun History Object

`comparison_summary` Object

Run Message Object

Rerun Object

`comparison` Object

Key Concepts

Runs

Every campaign starts at Run #1 (the original published campaign). Each time a rerun is initiated, the run number increments. The campaign always reflects the current run as its active state.

Segments

Campaigns generate messages per customer segment (a unique combination of variable values). When a rerun is initiated against a new customer group, segments from the previous run are compared against the new group:

Matched segments — the segment exists in both runs; the existing approved message is reused

New segments — only present in the new group; new messages are generated

Orphaned segments — only present in the previous run; their messages are archived

Campaign Status After Rerun

Scenario	Resulting Campaign Status
New segments require generation	`Ready for review`
All segments matched (no new generation needed)	`Ready to publish`

Endpoints

Endpoints Overview

Endpoint	Method	Purpose	Access Control
`/v1/campaign/rerun/history`	POST	Get all run history for a campaign	API Authentication (JWT + API Headers)
`/v1/campaign/rerun/messages`	POST	Get messages for a specific run	API Authentication (JWT + API Headers)
`/v1/campaign/rerun/initiate`	POST	Initiate a new campaign rerun	API Authentication (JWT + API Headers)

Authentication

All endpoints require API authentication via HTTP headers.

Required Headers

Header	Required	Description
`authorization`	Yes	Bearer token (JWT) containing `user_id`, `account_id`, `role_code`
`x-auth-context`	Yes	JSON object: `{ "api_access": true, "api_code": "<API_CODE>" }`
`x-ip`	Yes	Client IP address for audit logging
`Content-Type`	Yes	Must be `application/json`

Authentication Flow

API Code Validation: Validate api_code in x-auth-context matches server configuration

JWT Verification: Verify JWT token signature against API secret

Access Check: Confirm api_access is set to true

Account Extraction: Extract account_id from JWT for data isolation

Example Headers

authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-auth-context: {"api_access": true, "api_code": "your-api-code"}
x-ip: 192.168.1.100
Content-Type: application/json

1. Get Campaign Rerun History

Endpoint

POST /v1/campaign/rerun/history

Description

Returns the complete run history for a campaign, ordered from most recent to oldest. Each entry represents a distinct run, including the customer group used, the number of segments, and a summary of how messages were handled.

If the campaign has never been formally rerun (i.e. only Run #1 exists), a synthesised Run #1 entry is returned derived from the original campaign data, ensuring history is always available.

Purpose

Enables external systems to audit the full lifecycle of a campaign's message generation across multiple customer groups and time periods.

Business Use Cases

Audit Trails: Maintain a record of which customer group was used for each message run.

Run Selection: Allow users to choose which run's messages to retrieve or publish.

Status Monitoring: Track the outcome of each run (e.g. Published, Ready for review).

Reporting: Generate reports on campaign rerun activity over time.

Security Features

JWT token validation with account-specific secret

API code verification against server configuration

Account-level data isolation — only runs for the authenticated account's campaign are returned

2. Get Run Messages

Endpoint

POST /v1/campaign/rerun/messages

Description

Returns the generated messages for a campaign, optionally filtered to a specific run number. Each message includes its segment data, review status, approval stage, and archival state.

When a run_number is provided, archived messages for that run are included automatically (since messages from historical runs are archived when a newer run begins). When no run_number is provided, only active (non-archived) messages for the current run are returned by default.

Purpose

Enables external systems to retrieve the full set of generated messages for a given run, supporting downstream publishing, review workflows, and data export.

Business Use Cases

Message Review: Retrieve messages for a specific run to display in an external review interface.

Publishing Integration: Pull approved messages for delivery to a marketing or CRM platform.

Historical Audit: Inspect messages from previous runs for compliance or reporting.

Segment Analysis: Review which message was generated for each customer segment.

Security Features

JWT token validation with account-specific secret

API code verification against server configuration

Account-level data isolation — campaign ownership is validated before returning messages

3. Initiate Campaign Rerun

Endpoint

POST /v1/campaign/rerun/initiate

Description

Initiates a new campaign run against a different customer group in a single atomic operation. This endpoint combines segment preview, run record creation, campaign state update, previous-run message archival, and async processing job queuing — all in one call.

Prerequisites:

The campaign must have a status of Published

All messages in the current run must be in Published status before a rerun can be initiated

The endpoint automatically archives all messages from the previous run. Orphaned segment messages (those no longer relevant to the new customer group) are also archived during async processing.

Purpose

Enables external integrations to fully automate the campaign refresh cycle — updating the customer group and triggering message generation without any manual steps in the platform.

Business Use Cases

Automated Refresh: Trigger a campaign rerun when CRM data is updated (e.g. monthly customer list refresh).

Scheduled Campaigns: Integrate with scheduling systems to rerun campaigns on a regular cadence.

Dynamic Audiences: Update campaigns in response to real-time segmentation changes.

Workflow Automation: Chain rerun initiation with downstream publishing steps once the job completes.

Processing Flow

After a successful response, background processing proceeds through the following phases:

Copying — Matched segment messages are copied from the previous run to the new run

Generating — New segment messages are generated using the campaign's AI configuration

Archiving — Orphaned segment messages are archived

Finalising — Campaign state is updated to reflect the completed run

Security Features

JWT token validation with account-specific secret

API code verification against server configuration

Account-level data isolation — campaign ownership validated before any mutation

All messages in the current run must be Published before a rerun is permitted

Campaign must be in Published status — prevents rerunning mid-review campaigns

Common Error Codes

Status Code	Description	Common Causes
400	Bad Request	Campaign not in `Published` status; unpublished messages exist; current run targeted for archive
401	Unauthorized	Missing required request body fields
403	Forbidden	Missing or invalid authentication headers, invalid API code, invalid JWT
404	Not Found	Campaign not found; customer group not found
500	Internal Server Error	Database errors, processing failures

Specific Error Messages

Message	Cause	Resolution
`"auth error"`	Missing `req.auth` or entity manager	Ensure a valid JWT token is present in the `authorization` header
`"Unauthorized"`	API validation failed	Verify `x-auth-context` contains a valid `api_code`
`"Missing required fields"`	Required body fields absent	Include all required fields in the request body
`"Campaign not found"`	Invalid or inaccessible `campaign_id`	Verify the campaign exists and belongs to your account
`"Customer group not found"`	Invalid `new_customer_group_id`	Verify the customer group ID is correct
`"Only Published campaigns can be rerun"`	Campaign is not in `Published` status	Ensure the campaign has been published before initiating a rerun
`"All campaign messages must be published before initiating a rerun"`	One or more messages in the current run are not yet published	Publish all current run messages before initiating a rerun

Security & Compliance

Data Protection

Account-Level Isolation: All data queries filtered by account_id extracted from the JWT

Encrypted Transport: All API communications over HTTPS

Access Control

JWT Authentication: All endpoints require a valid JWT token

API Code Validation: api_code must match server configuration

Campaign Ownership: All operations validate that the campaign belongs to the authenticated account

Database Context: All operations execute within an authenticated database context

Audit Logging

User Context: All rerun records store the user_id of the initiating user

Job Tracking: Async background jobs are tracked with unique job_uid identifiers

Timestamp Recording: started_at and completed_at timestamps recorded per run

Comparison Snapshots: Segment comparison summaries stored permanently on each run record

Introduction#

Field Descriptions#

Key Concepts#

Runs#

Segments#

Campaign Status After Rerun#

Endpoints#

Endpoints Overview#

Authentication#

Required Headers#

Authentication Flow#

Example Headers#

1. Get Campaign Rerun History#

Endpoint#

Description#

Purpose#

Business Use Cases#

Security Features#

2. Get Run Messages#

Endpoint#

Description#

Purpose#

Business Use Cases#

Security Features#

3. Initiate Campaign Rerun#

Endpoint#

Description#

Purpose#

Business Use Cases#

Processing Flow#

Security Features#

Common Error Codes#

Specific Error Messages#

Security & Compliance#

Data Protection#

Access Control#

Audit Logging#

Introduction

Field Descriptions

Key Concepts

Runs

Segments

Campaign Status After Rerun

Endpoints

Endpoints Overview

Authentication

Required Headers

Authentication Flow

Example Headers

1. Get Campaign Rerun History

Endpoint

Description

Purpose

Business Use Cases

Security Features

2. Get Run Messages

Endpoint

Description

Purpose

Business Use Cases

Security Features

3. Initiate Campaign Rerun

Endpoint

Description

Purpose

Business Use Cases

Processing Flow

Security Features

Common Error Codes

Specific Error Messages

Security & Compliance

Data Protection

Access Control

Audit Logging