List top-performing letters

GET

/api/v3/letters/metrics/top-performers

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/letters/metrics/top-performers?api=true&metric=openRate' \
  --header 'Authorization: Bearer <token>'

• Production

Returns your company’s letters ranked by open rate or click-to-open rate, best first. As a v3 endpoint, it requires a company-derived API key.

By default the ranking covers a rolling 90-day window. To rank a specific period instead, pass both from and to (YYYY-MM-DD); passing only one of them is rejected, and to cannot be earlier than from.

Use channels[] to restrict the ranking to specific channels. Each item includes uniqueId, title, channel, organization, publicationDate, editionUrl, and the counts behind the ranking (delivered, opens, opensUnique, clicks, clicksUnique).

Authorizations

• bearerAuth

Parameters

Query Parameters

api

required

boolean

When set to true, this endpoint will accept authorization with your API Key.

metric

string

Allowed values: openRate clickToOpenRate

The rate to rank by. Defaults to openRate.

channels[]

Array<string>

Channel slugs to restrict the ranking to. Repeat the parameter for more than one channel.

from

string format: date

Start of the period to rank (YYYY-MM-DD). Must be sent together with to.

to

string format: date

End of the period to rank (YYYY-MM-DD). Must be sent together with from.

Responses

200

Top-performing letters

Media type application/json

object

items

Array<object>

object

uniqueId

string

title

string

channel

string

organization

string

publicationDate

string

editionUrl

string

delivered

integer

opens

integer

opensUnique

integer

clicks

integer

clicksUnique

integer

message

string

total

integer

Example ^generated

{
  "items": [
    {
      "uniqueId": "example",
      "title": "example",
      "channel": "example",
      "organization": "example",
      "publicationDate": "example",
      "editionUrl": "example",
      "delivered": 1,
      "opens": 1,
      "opensUnique": 1,
      "clicks": 1,
      "clicksUnique": 1
    }
  ],
  "message": "example",
  "total": 1
}