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.
`tracking_email`	string	Optional notification email.

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 fetch the campaign later with GET /api/campaigns/{campaignId}.

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.
Approved partner invoice-billed 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.