Retrieve a newsletter's headline numbers
One snapshot of a newsletter over a window: how the audience moved, what was published, how much the community talked, and how the email performed. It answers the question a dashboard opens with, in one call rather than six.
Every number is scoped to the window. Pick the window with period, or state it exactly with since and until.
Read audience and publishing carefully before charting them. Commune's record of a newsletter's subscribers is complete only for a commune newsletter. For one connected to an outside provider it is a partial cache of that provider's list, which is why the field is called known_subscribers and not subscriber_count. Do not present it as the newsletter's audience size, and ask the provider for that number instead. publishing.sent counts the articles Commune has a record of and is never a count of emails delivered, which lives in delivery.
Needs insights: read. What a key counts depends on whether it acts for the newsletter, which a key does when it holds write in any family. Such a key counts everything, including drafts, scheduled articles and conversations visible only to subscribers. A key that holds only read permissions is a reader of the published newsletter and counts what a reader can see: publishing.sent covers published articles that are not restricted to a tag, publishing.scheduled is null, community.threads, messages and reactions cover public conversations and the replies in them (an article's own discussion is visible to subscribers only, so it is not among them), and community.highlights covers the articles it can read. audience and delivery are the same for both kinds of key.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/stats
- 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
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.
A named window, counted back from today in UTC. Defaults to 30d. Ignored when since is given, so a request never has to reconcile two conflicting windows.
Start of the window, inclusive, as a date or an RFC 3339 timestamp. Giving this overrides period. A since later than until answers 400. Anything that is neither of those two shapes answers 400 as well, rather than being guessed at: a lenient parser would read 8/1/2026 as a date and give two callers different windows for the same string.
End of the window, exclusive, as a date or an RFC 3339 timestamp. Defaults to now. Only meaningful alongside since.
Response
The newsletter's numbers for the resolved window.
Example response
{
"newsletter": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.