Campaigns

Create campaign

Create a Scribeless campaign through the API.

Create a Scribeless campaign, then use the returned campaign ID when creating recipients.

POST https://platform.scribeless.co/api/campaigns

For most integrations, creating the campaign in the platform UI is simpler. Use this endpoint when you already have the product and template IDs your integration should use. You can discover published templates and their compatible products with GET /api/templates.

Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Request body

Field	Type	Description
`name`	string	Campaign name shown in Scribeless.
`delivery_method`	string	`directMail` or `bulkShipping`.
`frequency`	string	`oneTime` or `recurring`.
`product_id`	string	Product ID for the mail format.
`template_id`	string	Published template ID to render.
`include_envelope`	boolean	Optional. Whether to include an envelope where supported.
`envelope_sealed`	boolean	Optional. Whether the envelope should be sealed.
`stamp_on_envelope`	boolean	Optional. Whether the stamp goes on the envelope.
`shipping_address`	object	Required for bulk shipping campaigns.
`return_address`	object	Optional return address for direct mail. Required when `activate` is `true`.
`tracking_email`	string	Optional notification email.
`activate`	boolean	Optional. Set to `true` to activate a recurring campaign in the same request. Defaults to `false`.

Example request

curl --request POST 'https://platform.scribeless.co/api/campaigns' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "name": "API postcard campaign",
    "delivery_method": "directMail",
    "frequency": "oneTime",
    "product_id": "PRODUCT_ID",
    "template_id": "TEMPLATE_ID",
    "include_envelope": true,
    "stamp_on_envelope": true,
    "return_address": {
      "type": "return",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "company": "Example Co",
      "address1": "1 Example Street",
      "city": "London",
      "state": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    }
  }'

Response

Successful requests return the created campaign object. Use its id as campaignId when calling POST /api/recipients.

{
  "id": "CAMPAIGN_ID",
  "name": "API postcard campaign",
  "status": "pending",
  "delivery_method": "directMail",
  "frequency": "oneTime",
  "billing_method": "oneTime",
  "product_id": "PRODUCT_ID",
  "template_id": "TEMPLATE_ID"
}

You can list available campaigns with GET /api/campaigns or fetch this campaign later with GET /api/campaigns/{campaignId}.

Create and activate a recurring campaign

Set activate to the boolean value true to create a recurring campaign and activate it in one request. The team must have recurring campaigns enabled. The campaign must use direct mail and include a return address.

curl --request POST 'https://platform.scribeless.co/api/campaigns' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "name": "Recurring customer follow-up",
    "delivery_method": "directMail",
    "frequency": "recurring",
    "product_id": "PRODUCT_ID",
    "template_id": "TEMPLATE_ID",
    "return_address": {
      "type": "return",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "company": "Example Co",
      "address1": "1 Example Street",
      "city": "London",
      "state": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    },
    "activate": true
  }'

A successful request returns the campaign with status: "ready". Scribeless derives the billing method from the team's billing setup.

If activation fails after the campaign is created, the error includes its ID in data.campaign_id. Retry with POST /api/campaigns/{campaignId}/activate. Do not repeat the create request because it creates another campaign.

Notes

Product and template selection must be compatible. For example, a postcard campaign must use a postcard product and a published postcard template.
Campaign variables in the template must match the recipient fields or variables you send later.
If you do not already know the required product and template IDs, create the campaign in the platform UI and use the recipient API against that campaign.
Do not send billing fields when creating public API campaigns. Billing is handled by your Scribeless account setup.
activate must be a JSON boolean. String values such as "true" and "false" return 400.
Creating a recurring campaign returns 403 when recurring campaigns are not enabled for the team.
If you omit activate or set it to false, the new campaign remains pending. Activate it later with POST /api/campaigns/{campaignId}/activate.
One-time checkout workflows should create a normal one-time campaign with frequency: "oneTime" and then call POST /api/recipients/checkout after adding recipients. Do not send billing_method: "oneTimeInvoice"; it is not accepted by this endpoint.
For campaign status definitions, see the Campaign and recipient statuses Help Center article.

Templates

List, fetch, and create Scribeless templates for campaign creation.

Fetch campaign

Get a Scribeless campaign by ID.