ThreadListItem
The ThreadListItem type of the TypeScript SDK, which threads.list take or answer.
type ThreadListItem = {
exemplar: MessageMeta
flaggedCount: number
labels: string[]
lastReceivedAt: number
messageCount: number
participants: ThreadParticipant[]
threadId: string
unseenCount: number
}Fields
| Field | Type | Description |
|---|---|---|
exemplar | MessageMeta | The conversation's list-row face: the newest live member THAT MATCHED THIS LISTING'S FILTER, or the newest live member when no filter was given. Matching means the same member that qualified the thread — the label and the flag filters together — so ?label=INBOX faces the row with the newest Inbox member and not with your own Sent reply, and ?label=INBOX¬Flags=seen faces it with the unread Inbox message that put the row on screen. This is JMAP's rule for Email/query with collapseThreads. Position is a different question and stays conversation-wide: see lastReceivedAt. |
flaggedCount | number | Flagged (starred) live messages in this conversation, over the same population as messageCount. Read this and not exemplar's flagged flag to decide whether a row shows a star: a star on any other member is otherwise invisible from the list, and so cannot be cleared from it. To clear them all, PATCH /messages with threadIds and flagsClear: ["flagged"]. Not viewer-relative, unlike unseenCount: only seen is a per-viewer overlay. |
labels | string[] | Distinct label names across this conversation's live members, ordered by sort_order then name. Excludes the members the row excludes: those in Trash or Junk outside their own views, and those carrying an excludeRoles role. Limited to the viewer's granted labels. |
lastReceivedAt | number | When this conversation last had activity, in epoch seconds — the newest live member's arrival, ANYWHERE in the thread, which is also what the listing sorts by. May be newer than exemplar.receivedAt: the position is conversation-wide, the exemplar is folder-relative (see exemplar). |
messageCount | number | Live messages in this conversation, across every label — not just the one filtered by. Matches what GET /threads/{threadId} returns, so a row's count agrees with the conversation a client then renders. |
participants | ThreadParticipant[] | Distinct senders in the conversation, oldest first, deduplicated by address — the "Carol, Alice, Bob" line a conversation row shows, which the exemplar alone cannot supply. Conversation-wide like messageCount, so an Inbox row for a thread you replied to lists you as well. Bounded and capped at 8 entries: read from the conversation's opener plus its 20 newest live members, so a long thread reports who started it and who is still in it, and elides the middle. Scoped and filtered like the rest of the row (Trash and Junk members hidden outside their own views), so the Trash view of a conversation lists the people in its trashed half. |
threadId | string | Conversation thread ULID identifier |
unseenCount | number | Unread live messages in this conversation, over the same population as messageCount. Read this and not exemplar's seen flag to decide whether a row is unread: the exemplar is one member and may be read while older ones are not. |
Used by
| Method | What it does |
|---|---|
threads.list | List conversation threads |