List a newsletter's subscriber insights

Per subscriber engagement scoring. Each row blends what a reader did in the newsletter's community with what its email provider reported about them, carries a fourteen day over fourteen day velocity, and lands on a lifecycle status. This is what a CRM or a re engagement automation reads.

Scores are recomputed by a scheduled pass rather than at read time, so a row is only as fresh as the last pass, and last_action_at can be newer than the score that reflects it.

Only people with a Commune account are scored. Someone the newsletter knows only as an email address has no row here rather than a zero score, so the size of this collection is not the size of the audience.

status is assigned by rank within the newsletter rather than by an absolute score, so it moves when the people around a reader move even if that reader did nothing.

Ordered by total_score descending, so the first page is the newsletter's most engaged readers. Needs insights: read, and is one of the reads Commune may put behind a plan: a credential whose newsletter is not entitled answers 402.

?expand=subscriber saves a request per reader. Each insight's subscriber is a reference by default, and acting on the list (say, emailing the readers who are cooling off) would otherwise mean one GET /subscribers/{subscriber} per row. Expanded, every row carries the full Subscriber, the same object that operation returns, including email and status, in this one response. Accepted paths are newsletter and subscriber.

Expanding subscriber puts email addresses in the response, so it also needs audience: read on this newsletter. A credential that holds insights: read without it is refused with 403 insufficient_scope, param set to expand, and allowed_values listing what it may expand instead; it is never handed references in place of the subscribers it asked for. A response that expands subscriber counts against the audience rate limit budget and is recorded in Commune's audit log, like any other read of subscribers.