Get audience metrics overview
const url = 'https://api.tryletterhead.com/api/v3/metrics/audience';const form = new FormData();form.append('api', 'true');form.append('from', '2026-02-26');form.append('to', '2026-03-26');form.append('channels[]', 'an-example-channel');form.append('groupBy', 'channel');form.append('page', '1');form.append('limit', '5');form.append('sortBy', 'subscribers');form.append('direction', 'desc');form.append('includeCleaned', 'true');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tryletterhead.com/api/v3/metrics/audience \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: multipart/form-data' \ --form api=true \ --form from=2026-02-26 \ --form to=2026-03-26 \ --form 'channels[]=an-example-channel' \ --form groupBy=channel \ --form page=1 \ --form limit=5 \ --form sortBy=subscribers \ --form direction=desc \ --form includeCleaned=trueCompany-scoped audience growth totals for a date range: new subscribers, total audience
members, and unsubscribes, plus a dense daily sparkline and the prior period’s totals for
comparison. Pass groupBy=channel to also get a per-channel breakdown.
v3 endpoints expect a company API key.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
When set to true, this endpoint will accept authorization with your API Key.
Example
truePeriod start date (inclusive). The range between from and to cannot exceed 370 days.
Example
2026-02-26Period end date (inclusive), must be >= from.
Example
2026-03-26string[] | Optionally filter to a list of channels (by their slugs).
Example
an-example-channelPass channel to include a per-channel breakdown.
Example
channelPage number for the channel breakdown. Defaults to 1.
Example
1Items per page for the channel breakdown. Max of 50. Defaults to 5.
Example
5Sort the channel breakdown by “subscribers” or “channel.” Defaults to “subscribers.”
Example
subscribersSort direction for the channel breakdown, “asc” or “desc.” Defaults to “desc.”
Example
descWhether cleaned (previously unengaged, then removed) contacts count toward totalAudienceMembers. Defaults to true.
Example
trueResponses
Section titled “ Responses ”Get audience metrics overview
object
object
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
object
Internal numeric channel id — 0 when the metric is company-wide rather than channel-specific.
One row per day between from and to, inclusive — dense, so days with no activity still appear with zero values.
object
Present only when groupBy=channel was passed.
object
object
object
Example
{ "items": { "newSubscribers": { "currentValue": 42, "previousValue": 35, "changePercentage": 20, "growthRate": 0.02, "referenceDate": "2026-03-26", "channelId": 0 }, "totalAudienceMembers": 5000, "totalSubscribers": { "currentValue": 4800, "previousValue": 4750, "changePercentage": 1.05, "growthRate": 0.01, "referenceDate": "2026-03-26", "channelId": 0 }, "unsubscribes": { "currentValue": 8, "previousValue": 6, "changePercentage": 33.3, "growthRate": 0.33, "referenceDate": "2026-03-26", "channelId": 0 }, "totalCleaned": 120, "totalPending": 15, "totalUnsubscribes": 200, "totalNotSubscribed": 30, "lastUpdated": "2026-03-26T00:00:00Z", "daily": [ { "date": "2026-02-26", "totalSubscribers": 4750, "newSubscribers": 1, "unsubscribes": 0, "activeReaders": 300, "activeClickers": 40 }, { "date": "2026-02-27", "totalSubscribers": 4751, "newSubscribers": 1, "unsubscribes": 0, "activeReaders": 295, "activeClickers": 38 } ] }, "message": "Audience metrics overview retrieved successfully.", "total": 1}400 Validation Error — from/to missing, malformed, or from is after to.
object
object
Example
{ "data": [ "The from date must be on or before the to date." ], "items": [], "message": "Looks like the input data doesn't meet our requirements.", "total": 0}422 Unprocessable Entity — the from/to range exceeds 370 days.
object
object
Example
{ "data": [ "Date range must not exceed 370 days." ], "items": [], "message": "Looks like the input data doesn't meet our requirements.", "total": 0}Still can’t find what you need? Contact support.