List a newsletter's engagement events
The raw engagement stream the insight scores are built from, with both origins unified into one vocabulary: what a reader did inside the community, and what the newsletter's email provider reported about the same person. source says which side an event came from.
These are engagement records, not the events Commune pushes to a consumer. They describe reader behaviour and are read on request. What Commune pushes is the webhooks block of this document.
Ordered by id descending, and the cursor walks the same key, so a warehouse can tail this collection and be sure that nothing inserted mid page is skipped.
Every event is attributed to a Commune account, so a subscriber the newsletter knows only as an email address never appears here even when the provider reported an open for that address.
Needs insights: read. A newsletter whose plan does not include insights answers 402.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/events
- 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.
What a reader did. The first five happen on Commune and the last two are reported by the newsletter's email provider, which is what source records.
Return only events of this kind. Repeat the parameter to accept several.
Which side of the newsletter an event came from. community is behaviour Commune observed itself. esp is behaviour the newsletter's email provider reported, so it arrives on that provider's schedule and is only as complete as that provider's reporting.
Return only events from this origin. community is behaviour Commune observed directly, esp is behaviour the newsletter's email provider reported.
Response
A page of engagement events, most recent first.
Example response
{
"pagination": {
"next_cursor": "Y3Vyc29yOjE3NTY0MjM2MDAwMDA6MDE5MmM4"
},
"data": [
{
"id": "4815162342",
"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.