List promotion listings

GET

/api/v3/promotions/listings

const url = 'https://api.tryletterhead.com/api/v3/promotions/listings?api=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

List the placements (self-serve marketplace listings) your company offers for sale to advertisers. This is the publisher-authenticated management view; the unauthenticated public storefront advertisers browse is a separate, non-v3 surface.

v3 endpoints expect a company API key.

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.

sortBy

string

createdAt | price | availableFrom | status | title. Defaults to createdAt.

direction

string

asc or desc. Defaults to desc.

Responses

200

200 OK

application/json

object

items

Array<object>

object

uniqueId

string

channels

Array<object>

object

channel

string

channelTitle

string

zone

string

title

string

description

string

price

number

runLengthDays

integer

totalSlots

integer

availableSlots

integer

soldSlots

integer

availableFrom

string

nullable

availableTo

string

nullable

status

string

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": [
    {
      "uniqueId": "c3d4e5f6a7",
      "channels": [
        {
          "channel": "news-daily",
          "channelTitle": "News Daily"
        }
      ],
      "zone": "A",
      "title": "Front newsletter banner",
      "description": "Prime placement at the top of every send.",
      "price": 250,
      "runLengthDays": 7,
      "totalSlots": 4,
      "availableSlots": 3,
      "soldSlots": 1,
      "availableFrom": "2026-07-01",
      "availableTo": null,
      "status": "available",
      "createdAt": "2026-06-04 17:30:00",
      "updatedAt": "2026-06-04 17:30:00"
    }
  ],
  "message": "Promotion listings retrieved successfully",
  "total": 1
}

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