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 that has delivery activity. Days with no delivery are omitted.

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.