Download a segment's engagement over time (CSV)

GET

/api/v3/contacts/segments/{segmentId}/engagement-timeline/csv

const url = 'https://api.tryletterhead.com/api/v3/contacts/segments/1/engagement-timeline/csv?api=true&dateFrom=example&dateTo=example';
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/segments/1/engagement-timeline/csv?api=true&dateFrom=example&dateTo=example' \
  --header 'Authorization: Bearer <token>'

Streams the same daily unique-engager series as Segment engagement timeline, but as a downloadable CSV file (Content-Type: text/csv, Content-Disposition: attachment).

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

Response

A CSV file with the header row date,deliveredContacts,uniqueOpeners,uniqueClickers,bouncedContacts,openRate,clickRate,clickToOpenRate,bounceRate followed by one row per day in the window.

Authorizations

bearerAuth

Parameters

Path Parameters

segmentId

required

integer

The segment’s identifier. This is the numeric id returned by List segments — not a UUID.

Query Parameters

api

required

boolean

Set to true.

dateFrom

required

string

Start of the window (inclusive), e.g. 2026-06-01.

dateTo

required

string

End of the window (inclusive). Must be on or after dateFrom.

Responses

200

200 OK

text/csv

string

Example

"date","deliveredContacts","uniqueOpeners","uniqueClickers","bouncedContacts","openRate","clickRate","clickToOpenRate","bounceRate"
2026-06-07,412,198,24,3,48.1,5.8,12.1,0.7
2026-06-14,428,221,31,2,51.6,7.2,14,0.5
2026-06-21,435,209,28,5,48,6.4,13.4,1.1

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