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 import.completed.

• 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

  • kind string Required

    articles and subscribers ingest rows. migration is the finalize step that moves a newsletter onto native sending, which ingests nothing.

    Values are articles, subscribers, or migration.

  • source string | null Required

    Where the rows came from: an ESP slug such as kit or beehiiv, csv for an uploaded list, or rss for a feed. Null when the run has no single source, which is the migration case.

  • imported_count integer | null Required

    Rows that actually landed. Not the size of what was offered: both import paths skip duplicates, and the subscriber upsert preserves the status of a row that already existed rather than overwriting it. Null for migration, which ingests nothing.

    Rows the run could not take are not reported. Per-row failures are swallowed so one bad row cannot end the run, and none of the ingest paths counts them apart from the duplicates it skipped on purpose, so a count here would be a guess.

    Minimum value is 0.

  • started_at string(date-time) | null

    When the run began. Null when it was not recorded, so treat the duration as best effort.

  • completed_at string(date-time) Required

    When the run ended. Equal to occurred_at.