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 delivery.complained.

• 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

  • delivery_id string(uuid) Required

    The article_deliveries row.

  • article_id string(uuid) Required
  • send_id string(uuid) Required

    The send run this delivery belonged to.

  • subscriber_id string(uuid) Required
  • email string(email) Required

    The address as it was at send time. Snapshotted onto the delivery row, so it does not follow a later change to the subscriber.

  • provider_message_id string | null

    The email provider's id for this message, the correlator the inbound webhook matched on. Null only if the row was written without one.

  • status string Required

    The delivery row's status after this event was applied. Because the state machine is forward-only, it is not always the event's own name: an open recorded after a click leaves the row on clicked.

    Values are queued, sent, delivered, opened, clicked, bounced, complained, or failed.

  • reason string | null Required

    Why the row settled as a complaint. Providers rarely elaborate, so expect a constant string.

    Maximum length is 1000.