Body Required

• id string(uuid) Required

  Unique id for this event. Stable across redeliveries, so it is the dedupe key. It is the primary key of the row the publisher wrote, which means it is assigned when the state change is recorded, not 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 21 topics currently are.

• actor object | null Required

  Who caused the change. ALWAYS null today and consumers must treat it that way: the public API is currently read-only, so nothing that reaches this catalog was triggered through it, and Commune does not backfill an actor for changes made in the product UI or by a cron. The field exists now so that populating it, once writes exist, is an additive change rather than a new envelope version.

  Additional properties are NOT allowed.

  Hide actor attributes Show actor attributes object | null

  • type string Required

    user for a change a person made through an authenticated session, api_key for a public API write, system for a cron or webhook ingest with no human behind it.

    Values are user, api_key, or system.

  • id string Required

    Identifier of the actor within its type. A user id for user, a key id (never the secret) for api_key, a stable job name for system.

  • label string | null

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

• idempotency_key string | null Required

  ALWAYS null today. Once the public API accepts writes this carries the Idempotency-Key header of the write that caused the change, so a consumer can tie an event back to its own request and collapse the duplicates a retried write would otherwise produce. Null stays a legitimate value even then: a change made in the product UI or by a cron has no originating request to key on.

  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.