Get a promotion

GET

/api/v3/promotions/{promotionCollateralUid}

const url = 'https://api.tryletterhead.com/api/v3/promotions/example?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/example?api=true' \
  --header 'Authorization: Bearer <token>'

Fetch a single promotion by its promotionCollateralUid. Response includes nested metrics for letters that have used this promotion.

v3 endpoints expect a company API key.

Authorizations

bearerAuth

Parameters

Path Parameters

promotionCollateralUid

required

string

UUID of the promotion to delete

Query Parameters

api

required

boolean

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

page

integer

Pagination for the nested letters list (default 1)

Responses

200

200 OK

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

letters

object

items

Array<object>

object

title

string

publicationDate

string

channel

string

impressions

integer

clicks

integer

total

integer

totalPages

integer

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": {
    "promotionCollateralUid": "b2c3d4e5f6",
    "campaignTitle": "Summer Sale 2026",
    "channels": [
      "news-daily"
    ],
    "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": 600,
    "imageHeight": 400,
    "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,
    "letters": {
      "items": [
        {
          "title": "Daily Edition — July 1",
          "publicationDate": "2026-07-01",
          "channel": "news-daily",
          "impressions": 1240,
          "clicks": 38
        }
      ],
      "total": 1,
      "totalPages": 1
    },
    "createdAt": "2026-06-04 17:30:00",
    "updatedAt": "2026-06-04 17:30:00"
  },
  "message": "Promotion fetched successfully",
  "total": 1
}

404

404 Not Found

application/json

object

items

Array<object>

object

message

string

total

integer

Example

{
  "items": [],
  "message": "Promotion not found",
  "total": 0
}

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