Export a report by email
const url = 'https://api.tryletterhead.com/api/v3/reports/export';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"api":true,"reportType":2,"from":"2026-09-01","to":"2026-09-30","channels":["morning-brief","weekend-edition"],"recipients":["[email protected]"]}'};
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/reports/export \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "api": true, "reportType": 2, "from": "2026-09-01", "to": "2026-09-30", "channels": [ "morning-brief", "weekend-edition" ], "recipients": [ "[email protected]" ] }'Builds a CSV report across the newsletters and date range you choose, then emails a download link to each recipient. The request returns as soon as the export is queued; the file arrives by email, usually within a few minutes. Each download link works for 7 days.
Choose the report with reportType:
1— Clicks. One row per link per edition: URL, total clicks, unique clicks, the edition, its letter ID, and the newsletter.2— Engagement. One row per edition published in the range: sent, delivered, accepted, bounces (hard and soft, with rates), total opens, unique opens, unique confirmed opens, total clicks, unique clicks, and unsubscribes.3— Growth. One row per newsletter: total audience, subscribers, new subscribers, not subscribed, pending opt-in, unsubscribed, and cleaned, plus the size of each engagement group (Loyalists, New & Engaged, Casual, Fading, Ghosts, Single Newsletter) and how much each changed over the range.
These are rolled-up figures per edition, per link, or per newsletter. They don’t list individual contacts — to read one contact’s engagement, use Get a contact’s engagement breakdown.
from and to are calendar days and both are included in full.
This is a company-level (v3) request. Authenticate with a company API key as a Bearer token.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
Required. Set to true to authenticate with an API key.
Which report to build — 1 clicks, 2 engagement, 3 growth.
First day of the range, as YYYY-MM-DD.
Last day of the range, as YYYY-MM-DD. Must be on or after from.
The slugs of the newsletters to include. No duplicates.
The email addresses to send the download link to, up to 25. No duplicates.
Example
{ "api": true, "reportType": 2, "from": "2026-09-01", "to": "2026-09-30", "channels": [ "morning-brief", "weekend-edition" ], "recipients": [ ]}Responses
Section titled “ Responses ”The export was queued. The download link arrives by email.
object
Example
{ "items": [], "message": "Report export started.", "total": 0}A required field is missing or invalid — for example, an unknown reportType, a to date before from, or more than 25 recipients.
Still can’t find what you need? Contact support.