Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Schedule a promotion (public API-key endpoint)

POST
/api/v3/promotions/actions/schedule
 
curl --request POST \
  --url https://api.tryletterhead.com/api/v3/promotions/actions/schedule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "campaignTitle": "Summer Sale 2026", "channels": [ "an-example-channel" ], "headline": "50% off summer collection", "contentText": "Limited-time offer on all summer items.", "imageUrl": "https://cdn.example.com/summer-sale.png", "imageAlternativeText": "Summer sale banner", "promotionLink": "https://example.com/summer-sale", "promoter": "Example Brand", "dates": [ "2026-07-01" ], "isActive": true, "isEvergreen": false, "zone": "A", "type": 2 }'

Create a new promotional campaign, identical in body and response shape to Create a promotion. This endpoint is built specifically for external tools scheduling promotions via the public API: it authenticates with a company API key only (never a Passport/JWT session), and — unlike other v3 promotion endpoints — does not require the api=true query parameter, since API-key auth is the only auth this endpoint accepts.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
campaignTitle
required

Internal name of the campaign

string
channels

Slugs of channels to scope to. null/omitted means all channels. Required when allChannels: false is sent explicitly.

Array<string>
headline

Display headline of the ad

string
contentText

Body copy

string
imageUrl

Publicly accessible image URL

string
imageAlternativeText

Alt text for accessibility

string
promotionLink

Click-through destination. Must be http(s).

string
promoter

Display name of the advertiser

string
dates

Y-m-d dates when the promotion runs. Ignored at send time if isEvergreen: true.

Array<string>
isActive
required

true = scheduled/live, false = draft

boolean
isEvergreen

true = always runs, dates are ignored at send time

boolean
zone

Template position. One of A, B, C, D, E, F, G, H, I, J. Required unless autoInject: true is sent — there is no default, and omitting it without autoInject returns a 422 validation error.

string
type
required

Template type: 1=Text only, 2=Text & Image, 4=Banner, 7=HTML

integer
autoInject

When true, the promotion is auto-placed into every send at autoInjectPosition instead of a manually-chosen zone. When true, zone may be omitted but autoInjectPosition becomes required. Defaults to false (manual placement via zone).

boolean
autoInjectPosition

0-100 placement position, required when autoInject: true. Ignored for manual (non-auto-inject) promotions.

integer
Example 
{
  "campaignTitle": "Summer Sale 2026",
  "channels": [
    "an-example-channel"
  ],
  "headline": "50% off summer collection",
  "contentText": "Limited-time offer on all summer items.",
  "imageUrl": "https://cdn.example.com/summer-sale.png",
  "imageAlternativeText": "Summer sale banner",
  "promotionLink": "https://example.com/summer-sale",
  "promoter": "Example Brand",
  "dates": [
    "2026-07-01"
  ],
  "isActive": true,
  "isEvergreen": false,
  "zone": "A",
  "type": 2
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

201 Created

Media type application/json
object
items
object
promotionCollateralUid
string
campaignTitle
string
channels
Array<string>
allChannels
boolean
headline
string
contentText
string
imageUrl
string
imageAlternativeText
string
imageWidth
integer
imageHeight
integer
promotionLink
string
promoter
string
promotionServiceProviderId
integer
dates
Array<string>
isActive
boolean
isInactive
boolean
isEvergreen
boolean
embedClicks
integer
zone
string
type
integer
createdAt
string
updatedAt
string
message
string
total
integer
Example 
{
  "items": {
    "promotionCollateralUid": "b2c3d4e5f6",
    "campaignTitle": "Summer Sale 2026",
    "channels": [
      "an-example-channel"
    ],
    "allChannels": false,
    "headline": "50% off summer collection",
    "contentText": "Limited-time offer on all summer items.",
    "imageUrl": "https://cdn.example.com/summer-sale.png",
    "imageAlternativeText": "Summer sale banner",
    "imageWidth": 0,
    "imageHeight": 0,
    "promotionLink": "https://example.com/summer-sale",
    "promoter": "Example Brand",
    "promotionServiceProviderId": 0,
    "dates": [
      "2026-07-01"
    ],
    "isActive": true,
    "isInactive": false,
    "isEvergreen": false,
    "embedClicks": 0,
    "zone": "A",
    "type": 2,
    "createdAt": "2026-06-04 17:30:00",
    "updatedAt": "2026-06-04 17:30:00"
  },
  "message": "Promotion created successfully",
  "total": 1
}

Still can’t find what you need? Contact support.