List a newsletter's subscribers
The newsletter's subscribers, most recent first. Needs audience: read, and returns email addresses, so a credential that can call this holds the newsletter's list.
This is Commune's own record of the audience. For a commune newsletter it is the source of truth. For a newsletter connected to an outside provider it is a partial cache of that provider's list, filled in by imports and by people who joined through Commune, and it is not the newsletter's subscriber count of record. Ask the provider for that number, and do not present a count derived from this collection as a total.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/subscribers
- 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: audience: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 subscription stands. Source of truth for a commune newsletter. For a newsletter connected to an outside provider it reflects what Commune last saw of the provider's state.
Return only subscribers in this state. Defaults to subscribed. Repeat the parameter to accept several.
Return only subscribers holding this tag, by tag id.
Return only subscribers whose source is this. commune is the people who subscribed through Commune, imported the rows that came from the newsletter's provider or a file, and unknown the ones Commune recorded before it kept the answer. Omit for all three.
Filtered on the same value the field reports, so a page can never be missing a subscriber the field would have labelled this way.
Response
A page of subscribers, most recently added first.
Example response
{
"pagination": {
"next_cursor": "Y3Vyc29yOjE3NTY0MjM2MDAwMDA6MDE5MmM4"
},
"data": [
{
"newsletter": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
},
"user": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
},
"tags": [
{
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
]
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.