Newsletters

Retrieve a newsletter

Read one newsletter by id or by handle. A newsletter has no short_id: its handle is the short, human readable identifier, and it is what the web profile at /n/{handle} resolves on.

get/newsletters/{newsletter}

Request

Base URL: https://api.usecommune.com
URL: https://api.usecommune.com/newsletters/{newsletter}
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

expandstring

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.

fieldsstring

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.

Response

The newsletter.

object'newsletter' required

Always newsletter.

idstring uuid required

Stable identifier.

handlestring required

The short, unique, URL safe name. Resolves the public profile at /n/{handle} and is accepted anywhere {newsletter} is.

namestring required

Display name, as the creator writes it.

descriptionstring nullable

The profile blurb. Sanitised HTML, not plain text, because creators format it. Treat it as untrusted markup and render it in a sandboxed context.

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.

image_urlstring uri nullable

Square avatar for the newsletter.

website_urlstring uri nullable

The creator's own site, if they linked one.

languagestring nullable

Best known language of the newsletter's writing as a BCP 47 tag. Detected from recent articles rather than declared, so treat it as a hint. Null before enough has been published to tell.

chat_create_permission'editors' | 'subscribers' | 'anyone'

Who may start a new chat thread in this community.

allow_non_subscriber_chatboolean

Whether people who have not subscribed may reply in existing threads.

created_atstring date-time required

When the newsletter was connected to or created on Commune.

updated_atstring date-time

When the profile last changed.

Example response

{
  "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.