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.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/insights
- Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: insights:read)
Query parameters
The pagination.next_cursor value from the previous page. Omit it to read the first page. A cursor is opaque, is only valid for the same operation with the same filters, and is not a durable identifier.
How many items to return in this page. This is a page size, not an offset. Fewer items than requested may come back and that does not mean the collection is exhausted, only an absent next_cursor does.
Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.
Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.
Where a reader sits in the newsletter's engagement ladder, from dormant at the bottom to superfan at the top.
Assigned by rank inside the newsletter rather than against an absolute score, so it is a statement about this audience and never comparable between two newsletters. It also means a reader can move without doing anything, because the people around them moved.
Return only subscribers in this lifecycle status. Repeat the parameter to accept several.
Which way a reader's engagement is moving, from the last fourteen days against the fourteen before them. steady also covers a reader with no activity in either window, so read it with status, where that reader is dormant.
Return only subscribers whose engagement is moving this way. Repeat the parameter to accept several.
Response
A page of subscriber insights, highest scoring first.
Example response
{
"pagination": {
"next_cursor": "Y3Vyc29yOjE3NTY0MjM2MDAwMDA6MDE5MmM4"
},
"data": [
{
"newsletter": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
},
"subscriber": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.