Body Required

• id string(uuid) Required

  Unique id for this event. Stable across redeliveries, so it is the dedupe key. Assigned when the state change is recorded rather than when the message is dispatched.

• type string Required

  The topic name, identical to the channel address. Route on this.

  Value is subscriber.status_changed.

• api_version string Required

  The Commune-Version value this payload conforms to. Present on the message itself, not only on the request header, so an event persisted to a consumer's own store stays self-describing.

• occurred_at string(date-time) Required

  RFC 3339 timestamp of the state change, not of the delivery attempt. Use it to order events, since delivery order is not guaranteed.

• newsletter_id string(uuid) | null Required

  The newsletter the change belongs to. This is the tenant boundary: a consumer only ever receives events for newsletters its credential can read. Null only for events that are genuinely not newsletter-scoped, which none of the topics Commune publishes currently are.

• actor object | null Required

  Who caused the change, and null when nobody in particular did.

  Populated on a change made through this API's write operations, where it is the credential, and on a change one of the newsletter's own automations made, where it is the run. Null on every other change: an edit a creator made in the product, an import arriving from a provider, a scheduled job, a delivery result reported by the sending provider. Null is therefore the common case and stays a legitimate value. Read it as "this change was attributed", never as "nothing caused this".

  It never names a person: an api_key actor is the credential and a system actor is an automation run.

  It answers "did this change come in through the API, and under which credential". It is not the field to drop the echo of your own write with: use idempotency_key, which you chose and therefore already know, whereas id here is Commune's own identifier for your credential and no operation reports it back to you. A creator can read that identifier in Commune, but it changes when the credential is replaced, so matching on it puts the loop back silently after a rotation.

  Additional properties are NOT allowed.

  Hide actor attributes Show actor attributes object | null

  • type string Required

    api_key for a change made through this API. system for a change one of the newsletter's own automations made, where id is the automation run and label names the automation: see automation.run.started for what that attribution is for. user is reserved for a change a named person made through an authenticated session and is not emitted.

    An OAuth access token reports as api_key as well. The two credentials are interchangeable everywhere else in this API, and a separate value here would be a distinction a consumer cannot act on.

    Values are user, api_key, or system.

  • id string Required

    Identifier of the actor within its type. For api_key it is the credential's own id and never its secret, and it is the same value that appears in a creator's list of credentials, so an event can be traced back to the integration that caused it.

  • label string | null

    Human-readable name for display. Best effort, may be null.

• idempotency_key string | null Required

  The Idempotency-Key of the API write that caused this change, so a consumer can tie an event back to its own request and collapse the duplicates a retried write would otherwise produce.

  This is how a consumer that writes recognises its own work. Keep the keys you send, and skip any event carrying one of them. You chose the value, so you know it before the event arrives. actor cannot do this job, because Commune's id for your credential is not something this API reports to you.

  Null for every change that did not come in through this API, which is most of them: an edit made in Commune, an import, a scheduled job and a delivery result all have no originating request to key on.

  It reaches every endpoint registered for the newsletter, not only the one that made the write, so choose opaque keys such as UUIDs rather than keys carrying your own business identifiers.

  Maximum length is 255.

• data object Required

  Event-specific body. Narrowed by each concrete event schema below.

  Hide data attributes Show data attributes object

  • subscriber_id string(uuid) Required

    The subscriber this score belongs to, the same identifier the other subscriber.* topics carry.

  • user_id string Required

    The Commune account the score is attributed to. Insights are keyed on the account rather than on the subscription, because half the signal is community activity that belongs to a person and not to a mailing list entry. Always present: an unscored subscriber cannot cross a boundary.

  • email string(email) Required

    Where the newsletter reaches this reader, so a consumer can match the event against its own records without a second call. Resolved from the Commune account when the subscription row itself carries no address.

  • previous_status string | null

    Where a reader sits in the newsletter's engagement ladder, from dormant at the bottom to superfan at the top.

    Assigned by rank inside the newsletter rather than against an absolute score, so it is a statement about this audience and never comparable between two newsletters. It also means a reader can move without doing anything, because the people around them moved.

    Values are superfan, engaged, reader, or dormant.

  • status string Required

    Where a reader sits in the newsletter's engagement ladder, from dormant at the bottom to superfan at the top.

    Assigned by rank inside the newsletter rather than against an absolute score, so it is a statement about this audience and never comparable between two newsletters. It also means a reader can move without doing anything, because the people around them moved.

    Values are superfan, engaged, reader, or dormant.

  • direction string Required

    Which way along the ladder the reader moved, derived from the two statuses so a consumer does not have to hardcode their order. promoted the first time a reader is scored, because there is no earlier position they could have fallen from.

    Values are promoted or demoted.

  • total_score integer Required

    The blended score at the moment of the crossing, summed across the community and the newsletter's email provider. It has no unit and no ceiling, and is meaningful only ranked against the other readers of the same newsletter.

  • velocity string Required

    The last fourteen days of points against the fourteen before them. Read it with direction: a demotion while rising means the audience around this reader moved faster, not that the reader slowed down.

    Values are rising, cooling, or steady.

  • last_action_at string(date-time) | null

    When the reader last did anything that earned points. The reader's own clock, not the scoring pass's, so it sits earlier than occurred_at by up to a full scoring interval. Null for a reader who has never acted.