List promotions

GET

/api/v3/promotions

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/promotions?api=true' \
  --header 'Authorization: Bearer <token>'

• Production

List promotions for the authenticated company, with filtering, sorting, and pagination.

v3 endpoints expect a company API key.

Response field naming note

The list response uses image and position for two fields that the Get a promotion endpoint exposes as imageUrl and zone. Same data, different keys — this is a legacy inconsistency in the API. Treat them as aliases. The same applies to promotionCampaignUid (list) vs the campaign-uid embedded in the show response.

Authorizations

• bearerAuth

Parameters

Query Parameters

api

required

boolean

When set to true, the endpoint accepts authorization with your API Key.

page

integer

1-indexed page number. Defaults to 1.

records

integer

Records per page (max 100). Defaults to 10.

keyword

string

Search by campaign title or promoter name

status

integer

0=draft, 5=active, 9=inactive, 6=any

sortBy

string

createdAt | title | status | promoterDisplayName. Defaults to createdAt.

direction

string

asc or desc. Defaults to desc.

channels[]

Array<string>

Filter by channel slug(s)

promoters[]

Array<string>

Filter by promoter name(s)

from

string

Y-m-d, inclusive lower bound on dates

to

string

Y-m-d, inclusive upper bound on dates (must be ≥ from)

metrics

boolean

When true, items include clicks and impressions. Defaults to false.

mjml

boolean

When true, items include rendered MJML. Defaults to false.

html

boolean

Accepted for compatibility with other promotion endpoints, but currently has no effect on this response — no item ever carries a separate html field; the mjml field is the only rendered-content field this endpoint returns. Defaults to false.

resolveContent

boolean

Accepted for compatibility with other promotion endpoints, but currently has no effect on this response — this endpoint’s items never expose resolved passthrough links. Defaults to false.

esp

integer

ESP id used to render MJML/HTML (only relevant when mjml=true). Defaults to 0 (Letterhead’s own ESP).

Responses

200

200 OK

Media type application/json

object

items

Array<object>

object

promotionCollateralUid

string

campaignTitle

string

promoter

string

createdAt

string

nextDate

string

isActive

boolean

isInactive

boolean

isEvergreen

boolean

position

string

promotionCampaignUid

string

image

string

imageWidth

integer

imageHeight

integer

impressions

integer

clicks

integer

mjml

string

nullable

total

integer

totalInPage

integer

page

integer

limit

integer

totalPages

integer

Example

{
  "items": [
    {
      "promotionCollateralUid": "b2c3d4e5f6",
      "campaignTitle": "Summer Sale 2026",
      "promoter": "Example Brand",
      "createdAt": "2026-06-04 17:30:00",
      "nextDate": "2026-07-01",
      "isActive": true,
      "isInactive": false,
      "isEvergreen": false,
      "position": "A",
      "promotionCampaignUid": "a1b2c3d4e5",
      "image": "https://cdn.example.com/summer-sale.png",
      "imageWidth": 600,
      "imageHeight": 400,
      "impressions": 0,
      "clicks": 0,
      "mjml": null
    }
  ],
  "total": 47,
  "totalInPage": 10,
  "page": 1,
  "limit": 10,
  "totalPages": 5
}