Get channel health grouped by newsletter group

GET

/api/v3/contacts/metrics/groups

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

Returns a subscriber-health rollup for every one of your newsletters, grouped the same way your newsletter groups are organized. For each newsletter you get the current subscriber count, the net change over the last 30 days, a breakdown of your audience into five engagement segments (loyalists, newAndEngaged, casual, fading, ghosts) each with a percentage and a trend (up, down, or stable), and an overall health bucket (growing, stable, or needsAttention).

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

application/json

object

items

object

groups

Array<object>

object

group

object

slug

string

name

string

totalSubscribers

integer

channels

Array<object>

object

channel

object

slug

string

name

string

latestLetterTitle

Title of the channel’s most recently created letter. Omitted for a channel with no letters yet.

string

subscribers

integer

netGrowth

Net change in subscribers over the last 30 days.

integer

segments

One entry per engagement segment (loyalists, newAndEngaged, casual, fading, ghosts), each with a percentage and a trend (up, down, or stable).

object

key

additional properties

object

percentage

integer

trend

string

health

growing, stable, or needsAttention.

string

senderHealth

The channel’s sender health score, when available.

object

score

integer

nullable

severity

string

trend

string

lastUpdated

When the underlying growth snapshot was last refreshed. Null if no snapshot exists yet.

string

nullable

message

string

total

integer

Example

{
  "items": {
    "groups": [
      {
        "group": {
          "slug": "newsletters",
          "name": "Newsletters"
        },
        "totalSubscribers": 21200,
        "channels": [
          {
            "channel": {
              "slug": "the-daily",
              "name": "The Daily",
              "latestLetterTitle": "The Thursday Briefing"
            },
            "subscribers": 12400,
            "netGrowth": 340,
            "segments": {
              "loyalists": {
                "percentage": 42,
                "trend": "up"
              },
              "newAndEngaged": {
                "percentage": 18,
                "trend": "stable"
              },
              "casual": {
                "percentage": 21,
                "trend": "down"
              },
              "fading": {
                "percentage": 12,
                "trend": "stable"
              },
              "ghosts": {
                "percentage": 7,
                "trend": "stable"
              }
            },
            "health": "growing",
            "senderHealth": {
              "score": 87,
              "severity": "healthy",
              "trend": "stable"
            }
          }
        ]
      }
    ]
  },
  "message": "Groups metrics retrieved.",
  "total": 1
}

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