Get the recommended send time for a channel's segment

GET

/api/v3/channels/{channelSlug}/segments/{segmentId}/recommended-send-time

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/channels/example/segments/1/recommended-send-time?api=true' \
  --header 'Authorization: Bearer <token>'

• Production

Returns the day of week and time of day this segment’s readers open most often, derived from up to the segment’s last 10 published editions. segmentId=0 addresses the built-in “All active subscribers” segment.

Returns 404 Not Found when the segment doesn’t have enough send history yet (fewer than 3 editions with recorded opens, or fewer than 50 opens total) — never a recommendation built on an unreliable basis.

This endpoint is gated behind an internal feature flag that is not yet enabled for any tenant. While it’s off, the endpoint also returns 404 Not Found, indistinguishable from the insufficient-history case above.

v3 endpoints expect a company API key.

Authorizations

• bearerAuth

Parameters

Path Parameters

channelSlug

required

string

The newsletter’s channel identifier (slug).

segmentId

required

integer

Numeric id of the audience segment. 0 is the built-in “All active subscribers” segment.

Query Parameters

api

required

boolean

Required. Set to true.

Responses

200

200 OK

Media type application/json

object

items

object

recommendedWeekday

string

recommendedIsoWeekday

ISO-8601 weekday, 1=Monday through 7=Sunday.

integer

recommendedHour

Hour of day, 0-23, in timezone.

integer

recommendedTimeLabel

recommendedHour formatted for display, e.g. 8:00 AM.

string

timezone

string

basis

object

editionsAnalyzed

integer

opensAnalyzed

integer

distinctSendHours

How many distinct send hours the analyzed editions actually used — a low number means this recommendation may just be recovering the segment’s current send time rather than finding a better one.

integer

oldestEditionAt

string

newestEditionAt

string

message

string

total

Always 10 for this endpoint — total is not used for pagination here.

integer

Example

{
  "items": {
    "recommendedWeekday": "Tuesday",
    "recommendedIsoWeekday": 2,
    "recommendedHour": 8,
    "recommendedTimeLabel": "8:00 AM",
    "timezone": "America/New_York",
    "basis": {
      "editionsAnalyzed": 10,
      "opensAnalyzed": 412,
      "distinctSendHours": 2,
      "oldestEditionAt": "2026-05-01 08:05:00",
      "newestEditionAt": "2026-08-01 08:05:00"
    }
  },
  "message": "Recommended send time found for segment 0.",
  "total": 10
}

404

404 Not Found — see the cases listed above.

Media type application/json

object

data

Array<object>

object

items

Array<object>

object

message

string

total

integer

Example

{
  "data": [],
  "items": [],
  "message": "Segment 0 has too little open history for a send-time recommendation: 1 editions with open data, 12 opens.",
  "total": 0
}