Subscribers

Retrieve a subscriber

Read one subscriber by id. Needs audience: read, on a newsletter the credential reaches. The same person subscribing to two newsletters is two subscribers, and neither newsletter sees the other's.

get/subscribers/{subscriber}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/subscribers/{subscriber}
  • 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

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 subscriber.

object'subscriber' required

Always subscriber.

idstring uuid required

Stable identifier for this membership.

emailstring email required

Where the newsletter reaches this person. Returned on every subscriber, including one with a Commune account behind them.

For a subscriber with no account it is the address they subscribed with. For one with an account it is the address on that account, which is where the article is actually delivered. Never null.

This is the one place in the API an address appears. It is a property of the subscription rather than of the person, so it is never on a public profile, never on an expanded author, and never reachable from a credential granted another newsletter. Reading it needs audience: read, counts against the tighter audience rate limit budget, and is recorded in Commune's audit log with the credential and how many subscribers it read.

status'subscribed' | 'unsubscribed' | 'bounced' | 'complained' | 'pending' required

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.

source'commune' | 'imported' | 'unknown'

How the subscription was made. commune when the subscription was made on Commune: the person pressed subscribe, finished signup or accepted an invitation, or the newsletter's own integration added them with POST /newsletters/{newsletter}/subscribers. imported when they arrived in an import of the newsletter's provider list or a file.

Not the same question as whether Commune grew the list. Somebody who subscribes through Commune to a newsletter whose provider already held their address is commune here, even though the creator's list did not get longer.

unknown for a subscription recorded before Commune kept this. It is stated rather than left out, so "Commune does not know" cannot be mistaken for imported.

created_atstring date-time required

When Commune first recorded the subscription.

synced_atstring date-time nullable

When this row was last reconciled with the newsletter's provider. Null for a commune newsletter, which has no provider to reconcile with.

Example response

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