Recipients tab: list, search and unreachable persons

[Silthus]

Part of #181. Spec: #186. Slice 5 of 11 from #185.

Question

How do we ship this slice as one draft PR on PostHog/posthog behind workflows-audience?

Delivers. The Recipients tab becomes Audience's default: one row per recipient from the listing API, address search, and the "N persons can't be reached" line that opens the persons list already filtered to persons with no email property.

Spec. #186, approved by Michael on 2026-10-01.

Blocked by. #187, #190

Acceptance criteria

• /audience opens Recipients. Columns: Recipient (with a Suppressed tag), All marketing, Topics (explicit subscribed/unsubscribed topics as tags, "No preference on any topic" otherwise), Persons (name, count or "No person"), Last sent (header says it covers 30 days).
• Cursor paging, 50 rows a page. The search box sends search to the API, debounced.
• Above the table, one muted line: "N persons can't be reached because they have no email property". It is hidden at 0. The link opens urls.persons() with a #q= DataTableNode over an ActorsQuery filtered by { type: 'person', key: 'email', operator: 'is_not_set' }.
• Loading, empty ("No recipients yet"), no-match and error states are different screens. The error state asks to narrow the search.
• A row opens /audience/recipients/<email>.
• The frontend uses the generated messaging_recipients types. Stories at full width and ~520px, with screenshots.
• A draft PR on PostHog/posthog with proof (tests plus screenshots for visual work), an adversarial review, and green CI. Never ready, never queued.

Tracking events

• audience unreachable persons opened (count).

Test seam

Jest test through the real recipients logic and the real unreachablePersonsUrl() with the API mocked at the HTTP layer: typing a search issues a request with search, the next page sends the returned cursor, and the unreachable link decodes to an ActorsQuery with the email is_not_set filter. The persons scene itself is not mocked away from the URL contract: decode the q hash the way personsSceneLogic does.

[Silthus]

Worker: impl-191 (Claude Code background agent, claude-opus-5-5), wall-time cap 240 min, worktree /home/coder/posthog/.claude/worktrees/agent-a89ebc0d1630ede6b

[Silthus]

Resolution: draft PostHog/posthog#110513

Branch Silthus:feat/audience-recipients at f507a5a. It is stacked on PostHog#110305 and PostHog#110497, and the review and semgrep base is their merge aac71b95784. The PR is a draft. It is not marked ready, not queued and not merged. Fork CI waits on maintainer approval.

What shipped (behind workflows-audience)

• /audience opens a new Recipients tab: one row per address, cursor paging at 50 a page, and a search that sends search after 300 ms.
• The columns follow the AC. The Last sent header reads "Last sent (30 days)".
• The "N persons can't be reached because they have no email property" line is hidden at 0. It deep-links to urls.persons() with a #q= DataTableNode over an ActorsQuery filtered by email is_not_set, and it tracks audience unreachable persons opened (count).
• Loading, empty, no match and error are separate states. The error asks for a narrower search. A failed next page keeps the current page under the banner.
• Below a 44rem container, Persons and Last sent fold into the Recipient cell, so 520px does not scroll sideways.

Proof bundle

• Red → green: red → green (logic); red → green (default tab); review fixes red → green and red → green. No assertion was weakened.
• Local gate on f507a5a: hogli ci:preflight --strict passed with 0 failures, the diff-aware devex and security semgrep against aac71b95784 found 0 findings, typescript:check is clean, and the Audience Jest files pass (31 tests).
• Screenshots (Storybook, invented data): full width, 520px, empty, no match, error.
• CodeRabbit CLI: skipped. The CLI was signed out, and no person was available to sign in.

Review findings

Lane	Finding	Outcome
GPT-6.1 Sol	A stale failure overrides newer results	Fixed, test first
GPT-6.1 Sol	Next during the search debounce carries the old cursor	Fixed, test first
Fable 5.1	A row opens /audience/recipients/<email>, which has no detail view yet	Accepted: the AC asks for this route, and #193 builds on this PR
Fable 5.1	A failed next page replaces the table	Fixed, test first
Fable 5.1	A double click on Next sends two requests	Fixed, test first
Fable 5.1	A ctrl or meta click skips the tracking event	Accepted: Link skips onClick for new-tab clicks across the app
Fable 5.1	A coverage failure shows a toast	Fixed: renamed to loadAudienceCoverage and allow-listed
Fable 5.1	"1 persons" when one person has no row	Fixed
Fable 5.1	A long topic tag forces sideways scroll	Fixed: the tag uses wrap
Fable 5.1	A blank search shows "No recipients match"	Fixed, test first
Fable 5.1	A long empty-state sentence, and error copy that assumes a search	Fixed
Fable 5.1	The 300 ms debounce leaves the old state up before loading starts	Accepted: the reviewer rated it acceptable
Fable 5.1	Three tests would pass on a broken implementation	Fixed: a component wiring test, a request count, and select and full asserted

Look at first: recipientsLogic.ts. It tracks the shown request apart from the last request. That split drives paging, the stale-response guard, and the choice between the error state and the banner over the table.

Notes for downstream slices

• feat(messaging): add a recipient listing api PostHog/posthog#110497 now names the client messagingRecipientsRetrieve. The generated URL builder still joins a filter array with commas, so Recipient filters with the facet search bar #195 must append repeated filter params itself.
• Recipient detail #193 replaces what /audience/recipients/:email renders. Today that route keeps the Recipients tab.