Campaigns

Activate campaign

Activate an API-created recurring Scribeless campaign.

Activate a recurring campaign that is pending or paused.

POST https://platform.scribeless.co/api/campaigns/{campaignId}/activate

Activation validates the campaign, derives its billing method, bills its existing pending recipients, and then changes its status to ready. A ready recurring campaign accepts and bills new recipients through the normal recurring workflow.

Prerequisites

The campaign must:

belong to the team for the API key;
use frequency: "recurring";
use delivery_method: "directMail";
have a return address;
use a compatible published template and product;
have a status of pending or paused.

The team must have recurring campaigns enabled and a supported billing setup. Campaign creation returns 403 before activation when recurring campaigns are not enabled.

Headers

X-API-Key: YOUR_API_KEY

Path parameters

Parameter	Type	Description
`campaignId`	string	Scribeless campaign ID.

Example request

curl --request POST 'https://platform.scribeless.co/api/campaigns/CAMPAIGN_ID/activate' \
  --header 'X-API-Key: YOUR_API_KEY'

Response

A successful request returns the updated campaign with status: "ready".

{
  "id": "CAMPAIGN_ID",
  "status": "ready",
  "frequency": "recurring",
  "delivery_method": "directMail",
  "billing_method": "subscription"
}

Scribeless derives billing_method from the team's billing setup. Clients cannot select the activation billing method. Campaigns in an invoice-billed lifecycle cannot be activated and return 409.

Billing and retries

Activation bills existing pending recipients before it marks the campaign as ready. If billing fails, the campaign does not become ready and its recipients remain pending.

A 502 response is safe to retry. A 409 can mean that activation is not allowed or that a previous payment is still processing. Read the error message before you retry a 409 response.

Do not create recipients while an activation request is in progress. Wait for activation to return the campaign with status: "ready" before you create more recipients.

Status codes

Status	Meaning
`200`	Campaign activated.
`400`	The campaign is not recurring direct mail, has no return address, or has an incompatible template or product.
`401`	The API key is missing, malformed, invalid, or unauthorized.
`402`	The team has no active recurring subscription, or payment is still required.
`404`	The campaign does not exist or does not belong to the team.
`409`	The campaign is already active, has a terminal status, is invoice-billed, or has a payment still processing.
`502`	Upstream billing failed. Recipients remain pending, and the request can be retried.

To activate during creation, set activate: true when you call POST /api/campaigns.

List campaigns

Get Scribeless campaigns available to the authenticated team.

Create recipients

Create one or more recipients for a Scribeless campaign.