List letter metrics
const url = 'https://api.tryletterhead.com/api/v3/letters/metrics?api=true';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"page":1,"direction":"asc","createdAtAfter":"2026-01-01","createdAtBefore":"2026-03-31","channels":["example"],"filters":{"tags":["example"]}}'};
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/letters/metrics?api=true' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "page": 1, "direction": "asc", "createdAtAfter": "2026-01-01", "createdAtBefore": "2026-03-31", "channels": [ "example" ], "filters": { "tags": [ "example" ] } }'Returns performance metrics for your company’s published letters, one row per letter, with pagination. As a v3 endpoint, it requires a company-derived API key.
Use it to pull opens, clicks, bounces, and unsubscribes for many letters at once instead of fetching them one at a time. Results are sorted by creation date; use direction to choose newest-first (desc, the default) or oldest-first (asc).
Filtering. Pass channels (an array of channel slugs) to restrict results to specific channels, and createdAtAfter / createdAtBefore (YYYY-MM-DD) to restrict them to a creation-date window. To restrict results to letters carrying newsletter tags, pass the tags’ uniqueId values in filters.tags — note that this one sits inside a filters object, unlike the other filters. With no filters, letters from every channel your company owns are returned.
Response. items holds the array of letters and total is the count of letters matching your filters. Each row includes fields such as uniqueId, title, channel, organization, publicationDate, delivered, opens, opensUnique, clicks, clicksUnique, bounced, and unsubscribed, plus derived rates such as projectedOpenRate.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”When set to true, this endpoint will accept authorization with your API Key.
Request Body
Section titled “Request Body ”object
Page of results to return, starting at 1.
Example
1Sort order by creation date. Defaults to desc.
Only include letters created on or after this date (YYYY-MM-DD).
Example
2026-01-01Only include letters created on or before this date (YYYY-MM-DD).
Example
2026-03-31Channel slugs to restrict results to. Omit to include every channel.
object
Newsletter-tag uniqueId values restricting results to the letters carrying those tags. Get the ids from List newsletter tags. Up to 50 per request, each a string, and a letter must carry every tag you name — two tags return the letters tagged with both, not either. The total in the response counts only the matching letters.
Responses
Section titled “ Responses ”Letter metrics
object
object
Example generated
{ "items": [ { "uniqueId": "example", "title": "example", "channel": "example", "organization": "example", "publicationDate": "example", "delivered": 1, "opens": 1, "opensUnique": 1, "clicks": 1, "clicksUnique": 1, "bounced": 1, "unsubscribed": 1, "projectedOpenRate": 1 } ], "message": "example", "total": 1}Still can’t find what you need? Contact support.