List promotions by date (cached)

GET

/api/v3/promotions/actions/by-dates

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

List company promotions from an internal cache, filtered by dates: when dates[] is provided, returns promotions matching any of those dates plus every evergreen promotion; when dates[] is empty, returns only evergreen promotions. Same item shape as List promotions, but returns everything in one page rather than paginating (page/limit in the response envelope are always 1/the full result count).

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.

dates[]

Array<string>

Y-m-d dates to match. Omit/empty to return only evergreen promotions.

channels[]

Array<string>

Filter by channel slug(s)

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.

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

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": 1,
  "totalInPage": 1,
  "page": 1,
  "limit": 1,
  "totalPages": 1
}

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