Get a segment's engagement over time

GET

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

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/segments/1/engagement-timeline?api=true&dateFrom=example&dateTo=example' \
  --header 'Authorization: Bearer <token>'

• Production

Returns a segment’s daily unique-engager rates (open / click / click-to-open / bounce) across a date window.

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

Response

The daily series is returned under items. Each point carries date, deliveredContacts, uniqueOpeners, uniqueClickers, bouncedContacts, openRate, clickRate, clickToOpenRate, and bounceRate. Days with no delivery activity are omitted rather than returned as zero rows.

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.

channel

string

Restrict the timeline to the given channel identifier (slug).

Responses

200

200 OK

Media type application/json

object

items

Array<object>

object

date

string

deliveredContacts

integer

uniqueOpeners

integer

uniqueClickers

integer

bouncedContacts

integer

openRate

number

clickRate

number

clickToOpenRate

number

bounceRate

number

message

string

total

integer

Example

{
  "items": [
    {
      "date": "2026-06-07",
      "deliveredContacts": 412,
      "uniqueOpeners": 198,
      "uniqueClickers": 24,
      "bouncedContacts": 3,
      "openRate": 48.1,
      "clickRate": 5.8,
      "clickToOpenRate": 12.1,
      "bounceRate": 0.7
    },
    {
      "date": "2026-06-14",
      "deliveredContacts": 428,
      "uniqueOpeners": 221,
      "uniqueClickers": 31,
      "bouncedContacts": 2,
      "openRate": 51.6,
      "clickRate": 7.2,
      "clickToOpenRate": 14,
      "bounceRate": 0.5
    },
    {
      "date": "2026-06-21",
      "deliveredContacts": 435,
      "uniqueOpeners": 209,
      "uniqueClickers": 28,
      "bouncedContacts": 5,
      "openRate": 48,
      "clickRate": 6.4,
      "clickToOpenRate": 13.4,
      "bounceRate": 1.1
    }
  ],
  "message": "Segment engagement timeline retrieved.",
  "total": 3
}