List newsletters
The newsletters your credential reaches.
This is the operation to call first. A credential is granted a list of newsletters, and everything else in this API is addressed by an identifier from that list: this is where those identifiers come from, and it is what an integration calls when it holds a credential and does not yet know which newsletters it is for.
Most credentials reach exactly one, and this answers one item for them. A credential granted several answers several. A credential whose owner has lost their standing on a newsletter stops reaching it, and this answers one item fewer, or an empty page rather than an error.
It is not a directory of Commune. There is no way to see a newsletter you were not granted, here or anywhere else in this API, and a filter below narrows this list rather than searching outside it.
Ordered newest first, and paged like every other collection.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters
- 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)
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 newsletter is published from. commune means Commune itself sends the email. Every other value is an email service provider whose posts Commune imports. rss covers any feed that is not one of the named providers.
Return only newsletters published through this provider. Repeat the parameter to accept several.
Return only the newsletter with this handle, among the ones your credential reaches. Zero or one item.
A handle is unique across Commune, but this is a filter and not a lookup: a handle your credential was not granted answers an empty page, exactly as it would if no such newsletter existed.
GET /newsletters/{newsletter} also accepts a handle and answers 404 rather than an empty page, which is what you want when you are after a single object.
Response
A page of newsletters.
Example response
{
"pagination": {
"next_cursor": "Y3Vyc29yOjE3NTY0MjM2MDAwMDA6MDE5MmM4"
},
"data": [
{
"handle": "the-weekly",
"language": "en",
"owner": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
},
"featured_article": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.