Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Get promotion insights

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

Aggregated insights for the Promotions tab: the top 5 promotions by click-through rate (CTR; only promotions with at least 100 impressions are eligible), the top 5 by raw click count, the top 5 (promotion, letter) pairs by clicks, and a paginated “all promotions” table ranked by clicks (not chronological, unlike the list endpoint). revenue/revenuePerMille are always 0 unless the company’s self-serve promotions marketplace is enabled.

v3 endpoints expect a company API key.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
api
required
boolean

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

page
integer

1-indexed page number for the all table. Defaults to 1.

records
integer

Records per page for the all table (max 100). Defaults to 10.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

200 OK

Media type application/json
object
items
object
topByCtr
Array<object>
object
collateralUid
string
title
string
promoter
string
channels
Array<string>
zone
string
impressions
integer
clicks
integer
ctr
number
revenue
number
revenuePerMille
number
firstPublishedAt
string
status
integer
topByClicks
Array<object>
object
collateralUid
string
title
string
promoter
string
channels
Array<string>
zone
string
impressions
integer
clicks
integer
ctr
number
revenue
number
revenuePerMille
number
firstPublishedAt
string
status
integer
topByLetterPromo
Array<object>
object
collateralUid
string
promoTitle
string
letterUid
string
letterTitle
string
letterBrand
string
letterChannel
string
clicks
integer
all
object
items
Array<object>
object
collateralUid
string
title
string
promoter
string
channels
Array<string>
zone
string
impressions
integer
clicks
integer
ctr
number
revenue
number
revenuePerMille
number
firstPublishedAt
string
status
integer
total
integer
message
string
total
integer
Example 
{
  "items": {
    "topByCtr": [
      {
        "collateralUid": "b2c3d4e5f6",
        "title": "Summer Sale 2026",
        "promoter": "Example Brand",
        "channels": [
          "News Daily"
        ],
        "zone": "A",
        "impressions": 1240,
        "clicks": 38,
        "ctr": 3.06,
        "revenue": 0,
        "revenuePerMille": 0,
        "firstPublishedAt": "2026-06-04 17:30:00",
        "status": 5
      }
    ],
    "topByClicks": [
      {
        "collateralUid": "b2c3d4e5f6",
        "title": "Summer Sale 2026",
        "promoter": "Example Brand",
        "channels": [
          "News Daily"
        ],
        "zone": "A",
        "impressions": 1240,
        "clicks": 38,
        "ctr": 3.06,
        "revenue": 0,
        "revenuePerMille": 0,
        "firstPublishedAt": "2026-06-04 17:30:00",
        "status": 5
      }
    ],
    "topByLetterPromo": [
      {
        "collateralUid": "b2c3d4e5f6",
        "promoTitle": "Summer Sale 2026",
        "letterUid": "a1b2c3d4e5",
        "letterTitle": "Daily Edition — July 1",
        "letterBrand": "example-brand",
        "letterChannel": "news-daily",
        "clicks": 38
      }
    ],
    "all": {
      "items": [
        {
          "collateralUid": "b2c3d4e5f6",
          "title": "Summer Sale 2026",
          "promoter": "Example Brand",
          "channels": [
            "News Daily"
          ],
          "zone": "A",
          "impressions": 1240,
          "clicks": 38,
          "ctr": 3.06,
          "revenue": 0,
          "revenuePerMille": 0,
          "firstPublishedAt": "2026-06-04 17:30:00",
          "status": 5
        }
      ],
      "total": 1
    }
  },
  "message": "Insights fetched successfully",
  "total": 1
}

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