List a newsletter's articles
The newsletter's articles, most recently published first, ordered by posted_at descending with articles that never got a date last.
Two gates apply and neither can be turned off. An article stamped with an audience is returned only to a credential that may read that audience: the newsletter's owner, an admin or editor, or a subscriber holding one of the article's tags. An article whose posted_at is in the future is not returned at all until that moment passes, so a scheduled article never leaks early through this collection.
content is never included here, whatever ?fields= asks for. An article body is large enough that returning a page of them is the wrong default, so read it from GET /articles/{article}.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/articles
- 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: content: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 an article is in its life. A credential holding only read permissions ever sees sent and nothing else. An imported article is always sent, since Commune sees it after the provider delivered it.
Return only articles in this state. A credential holding only read permissions may ask for sent alone, since a draft or a failed send is not published. Repeat the parameter to accept several.
true returns only articles imported from the newsletter's provider, false only articles written in Commune. Omit for both.
Return only articles stamped with this subscriber tag, by tag id. Needs content: read, because the audience of an article is not public.
Response
A page of articles, each without content.
Example response
{
"pagination": {
"next_cursor": "Y3Vyc29yOjE3NTY0MjM2MDAwMDA6MDE5MmM4"
},
"data": [
{
"short_id": "k7Rm2xQp",
"newsletter": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
},
"authors": [
{
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
],
"thread": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.