Headers

• Commune-Version string

  The contract version this request is written against. Every version published so far is a release date (YYYY-MM-DD), which is why the examples look like one, but the value is an opaque identifier: match it against the versions this API publishes rather than parsing it, because a future one may not be only a date. An unknown value answers 400 with invalid_version.

  Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships.

  Minimum length is 1.

Query parameters

• cursor string

  The pagination.next_cursor value from the previous page. Omit it to read the first page. A cursor is opaque, is only valid for the same operation with the same filters, and is not a durable identifier.

  Maximum length is 512.

• limit integer

  How many items to return in this page. This is a page size, not an offset. Fewer items than requested may come back and that does not mean the collection is exhausted, only an absent next_cursor does.

  Minimum value is 1, maximum value is 100. Default value is 20.

• fields string

  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.

Responses

• 200 application/json

  The triggers, by topic.

  Hide response attributes Show response attributes object

  • object string Required

    Always list, so a response is self describing.

    Value is list.

  • pagination object Required

    Cursor pagination state. Commune never exposes an offset or a page number: a collection is a moving window, and an offset silently skips or repeats items when the window shifts between two requests.

    Additional properties are NOT allowed.

    Hide pagination attributes Show pagination attributes object

    • has_more boolean Required

      Whether another page exists. When false, next_cursor is null.

    • next_cursor string | null Required

      Pass this back as ?cursor= to read the next page. null on the last page. Opaque, and valid only for the same operation with the same filters.

  • data array[object]

    Every topic that can start an automation, in alphabetical order, each with the property names a condition may use under it.

    Hide data attributes Show data attributes object

    One event an automation can be built on, and what a condition may ask about under it.

    The same for every newsletter, because it describes Commune's event vocabulary rather than anybody's data.

    • object string Required

      Always automation_trigger.

      Value is automation_trigger.

    • topic string Required

      The event that starts a run.

      Every topic Commune publishes is a trigger, including the ones that are not about a subscriber. An automation on article.published can hold conditions and waits; it cannot send an email or move a tag, because there is nobody for those to act on, and saving one that tries is refused rather than left to fail once per event forever.

      GET /automation-triggers says, per topic, which properties its events carry and whether it is about a subscriber. That is what a condition can ask about.

      Values are article.liked, article.published, article.read, article.scheduled, automation.run.completed, automation.run.exited, automation.run.started, billing.subscription.updated, delivery.bounced, delivery.clicked, delivery.complained, delivery.delivered, delivery.opened, domain.verified, highlight.created, import.completed, message.created, send.completed, send.failed, sender.verified, subscriber.created, subscriber.status_changed, subscriber.tagged, subscriber.unsubscribed, thread.created, or thread.published.

    • carries_subscriber boolean Required

      Whether this topic's events are about a subscriber. False means an automation on it cannot send an email or move a tag, because there is nobody for those to act on, and saving one that tries is refused.

    • context object Required

      What a condition step may ask about, for one trigger. One variant per topic, because event is that topic's own payload: a condition about the event is written against the same properties the topic's webhook delivers.

      Each variant lists the property names a condition may use under each of the three branches, rather than their types. A condition is a JSON Schema document, and its own type keyword is what asserts what a value is; what this answers is the question a schema cannot answer about itself, which is whether the path it names can exist at all.

      That question matters because of one asymmetry. JSON Schema treats an absent property as saying nothing, so a condition about a property no payload carries matches every run: the branch silently always takes the same arm, and nothing anywhere reports it. Saving such a condition is refused, naming the path, and this is the list that refusal is computed from.

      subscriber is empty for a topic whose events are not about a subscriber. That emptiness carries three facts at once: such a trigger cannot send an email, cannot apply a tag, and cannot be asked anything about a person.

      steps is empty on every variant, and has to be: its names are an automation's own send_email step ids, so they belong to an automation rather than to a topic. GET /automation-triggers serves these, and the steps of a particular automation are the ids in its own graph.

      One of:

      article.liked context object article.published context object article.read context object article.scheduled context object automation.run.completed context object automation.run.exited context object automation.run.started context object billing.subscription.updated context object delivery.bounced context object delivery.clicked context object delivery.complained context object delivery.delivered context object delivery.opened context object domain.verified context object highlight.created context object import.completed context object message.created context object send.completed context object send.failed context object sender.verified context object subscriber.created context object subscriber.status_changed context object subscriber.tagged context object subscriber.unsubscribed context object thread.created context object thread.published context object

      What a condition may ask about under an automation triggered by article.liked. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is article.liked.

      • event array[string] Required

        The properties article.liked carries in its payload.

        Values are article_id, changed_at, direction, like_count, reader, title, or url.

      • subscriber array[string] Required

        Empty: article.liked is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by article.published. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is article.published.

      • event array[string] Required

        The properties article.published carries in its payload.

        Values are article_id, audience_scoped, published_at, slug, source, title, or url.

      • subscriber array[string] Required

        Empty: article.published is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by article.read. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is article.read.

      • event array[string] Required

        The properties article.read carries in its payload.

        Values are article_id, read_at, reader, title, or url.

      • subscriber array[string] Required

        Empty: article.read is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by article.scheduled. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is article.scheduled.

      • event array[string] Required

        The properties article.scheduled carries in its payload.

        Values are article_id, scheduled_for, or title.

      • subscriber array[string] Required

        Empty: article.scheduled is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by automation.run.completed. A run has a subscriber only when its own trigger did, so these events are treated as not about a subscriber: an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is automation.run.completed.

      • event array[string] Required

        The properties automation.run.completed carries in its payload.

        Values are automation_id, automation_name, chain_depth, completed_at, event_id, run_id, started_at, subscriber_id, or trigger.

      • subscriber array[string] Required

        Empty, and deliberately so even though the payload carries a subscriber_id: that field is null for a run whose own trigger was not about a person, so a trigger that promised a subscriber here would let a creator activate a sequence that mails nobody for half its runs. Read event.subscriber_id in a condition instead.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by automation.run.exited. A run has a subscriber only when its own trigger did, so these events are treated as not about a subscriber: an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is automation.run.exited.

      • event array[string] Required

        The properties automation.run.exited carries in its payload.

        Values are automation_id, automation_name, chain_depth, completed_at, event_id, reason, run_id, started_at, status, subscriber_id, or trigger.

      • subscriber array[string] Required

        Empty, for the reason automation.run.completed gives: a run's own subscriber is optional, so this trigger cannot promise one.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by automation.run.started. A run has a subscriber only when its own trigger did, so these events are treated as not about a subscriber: an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is automation.run.started.

      • event array[string] Required

        The properties automation.run.started carries in its payload.

        Values are automation_id, automation_name, chain_depth, event_id, run_id, started_at, subscriber_id, or trigger.

      • subscriber array[string] Required

        Empty, for the reason automation.run.completed gives: a run's own subscriber is optional, so this trigger cannot promise one.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by billing.subscription.updated. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is billing.subscription.updated.

      • event array[string] Required

        The properties billing.subscription.updated carries in its payload.

        Values are cancel_at_period_end, current_period_end, current_period_start, plan, previous_status, status, subscription_id, or trial_ends_at.

      • subscriber array[string] Required

        Empty: billing.subscription.updated is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by delivery.bounced.

      Hide attributes Show attributes

      • trigger string Required

        Value is delivery.bounced.

      • event array[string] Required

        The properties delivery.bounced carries in its payload.

        Values are article_id, delivery_id, email, provider_message_id, reason, run_id, send_id, source, status, step_id, or subscriber_id.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by delivery.clicked.

      Hide attributes Show attributes

      • trigger string Required

        Value is delivery.clicked.

      • event array[string] Required

        The properties delivery.clicked carries in its payload.

        Values are article_id, delivery_id, email, provider_message_id, run_id, send_id, source, status, step_id, or subscriber_id.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by delivery.complained.

      Hide attributes Show attributes

      • trigger string Required

        Value is delivery.complained.

      • event array[string] Required

        The properties delivery.complained carries in its payload.

        Values are article_id, delivery_id, email, provider_message_id, reason, run_id, send_id, source, status, step_id, or subscriber_id.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by delivery.delivered.

      Hide attributes Show attributes

      • trigger string Required

        Value is delivery.delivered.

      • event array[string] Required

        The properties delivery.delivered carries in its payload.

        Values are article_id, delivery_id, email, provider_message_id, run_id, send_id, source, status, step_id, or subscriber_id.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by delivery.opened.

      Hide attributes Show attributes

      • trigger string Required

        Value is delivery.opened.

      • event array[string] Required

        The properties delivery.opened carries in its payload.

        Values are article_id, delivery_id, email, provider_message_id, run_id, send_id, source, status, step_id, or subscriber_id.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by domain.verified. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is domain.verified.

      • event array[string] Required

        The properties domain.verified carries in its payload.

        Values are domain, domain_id, ssl_status, or verified_at.

      • subscriber array[string] Required

        Empty: domain.verified is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by highlight.created. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is highlight.created.

      • event array[string] Required

        The properties highlight.created carries in its payload.

        Values are article_id, created_at, end_offset, highlight_id, message_id, owner_key, quote, or start_offset.

      • subscriber array[string] Required

        Empty: highlight.created is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by import.completed. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is import.completed.

      • event array[string] Required

        The properties import.completed carries in its payload.

        Values are completed_at, imported_count, kind, source, or started_at.

      • subscriber array[string] Required

        Empty: import.completed is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by message.created. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is message.created.

      • event array[string] Required

        The properties message.created carries in its payload.

        Values are author, content, created_at, message_id, parent_id, short_id, thread_id, thread_level, or url.

      • subscriber array[string] Required

        Empty: message.created is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by send.completed. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is send.completed.

      • event array[string] Required

        The properties send.completed carries in its payload.

        Values are article_id, completed_at, failed_count, recipient_count, send_id, sent_count, or started_at.

      • subscriber array[string] Required

        Empty: send.completed is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by send.failed. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is send.failed.

      • event array[string] Required

        The properties send.failed carries in its payload.

        Values are article_id, failure_reason, or send_id.

      • subscriber array[string] Required

        Empty: send.failed is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by sender.verified. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is sender.verified.

      • event array[string] Required

        The properties sender.verified carries in its payload.

        Values are domain, from_email, from_name, is_default, kind, reply_to_email, sender_id, or verified_at.

      • subscriber array[string] Required

        Empty: sender.verified is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by subscriber.created.

      Hide attributes Show attributes

      • trigger string Required

        Value is subscriber.created.

      • event array[string] Required

        The properties subscriber.created carries in its payload.

        Values are acquisition_source, created_at, email, resubscribed, status, subscriber_id, or user_id.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by subscriber.status_changed.

      Hide attributes Show attributes

      • trigger string Required

        Value is subscriber.status_changed.

      • event array[string] Required

        The properties subscriber.status_changed carries in its payload.

        Values are direction, email, last_action_at, previous_status, status, subscriber_id, total_score, user_id, or velocity.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by subscriber.tagged.

      Hide attributes Show attributes

      • trigger string Required

        Value is subscriber.tagged.

      • event array[string] Required

        The properties subscriber.tagged carries in its payload.

        Values are direction, email, subscriber_id, tag_id, or tag_name.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by subscriber.unsubscribed.

      Hide attributes Show attributes

      • trigger string Required

        Value is subscriber.unsubscribed.

      • event array[string] Required

        The properties subscriber.unsubscribed carries in its payload.

        Values are article_send_id, email, reason, subscriber_id, or unsubscribed_at.

      • subscriber array[string] Required

        The live subscriber fields a condition may read, for a trigger whose events are about a subscriber. Read at evaluation time rather than when the run started, which is the whole reason a condition is useful: asking whether somebody holds a tag means now, three days into the sequence, and not when they subscribed.

        Values are acquired_via_commune, acquisition_source, created_at, email, id, status, subscribed_via, or tags.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by thread.created. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is thread.created.

      • event array[string] Required

        The properties thread.created carries in its payload.

        Values are article_id, audience_scoped, author, content, created_at, short_id, thread_id, url, or visibility.

      • subscriber array[string] Required

        Empty: thread.created is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

      What a condition may ask about under an automation triggered by thread.published. These events are not about a subscriber, so an automation on this trigger can hold conditions and waits but cannot send an email or move a tag.

      Hide attributes Show attributes

      • trigger string Required

        Value is thread.published.

      • event array[string] Required

        The properties thread.published carries in its payload.

        Values are article_id, author, previous_visibility, published_at, published_by, short_id, source, thread_id, url, or visibility.

      • subscriber array[string] Required

        Empty: thread.published is not about a subscriber, so there is nobody for a condition to ask about and no subscriber-requiring action this trigger can take.

        Not more than 0 elements.

      • steps array[string] Required

        The ids of the automation's send_email steps, each of which reports clicked and opened once its delivery has been attributed. Empty on the trigger catalog, where there is no automation and therefore no step.

• 400 application/json

  The request was malformed, and the same request will fail the same way until it is changed. param names the parameter or header at fault when there is exactly one, and allowed_values lists what it accepts when that is a finite set. The code is bad_request for every case below except the last.

  • A query parameter: one the operation does not have, a value outside its set, range or format (an unparseable cursor, an unknown expand path or fields name, an identifier that is not a UUID), or a required one left out, such as q on a search or newsletter when the credential reaches more than one.
  • The request body: not JSON, not the shape the operation reads, a property it does not write, or a value of the wrong type, length or format. param is absent here, since the body is not a parameter, and the message names the property.
  • The Idempotency-Key header, on an operation that changes something: missing, or a value this API will not store.
  • An unrecognised Commune-Version, which answers with its own code, invalid_version, because it is never fixed by changing the body.
  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 401 application/json

  No credential was presented, or it is malformed, unknown, revoked or expired, or it is an access token minted for a different audience.

  Every one of these answers identically, down to the wording and the headers, so a refusal never confirms that a string was once real.

  Hide headers attribute Show headers attribute

  • WWW-Authenticate string

    The authentication scheme this API accepts, and where to find out how to get a credential for it. Always Bearer realm="Commune API", resource_metadata="https://api.usecommune.com/.well-known/oauth-protected-resource".

    resource_metadata is the RFC 9728 pointer to this API's protected resource metadata, which names the authorization server an OAuth client should send its user to. A client holding an API key can ignore it. The header carries no error parameter, not even error="invalid_token", because it describes what this API accepts rather than what was wrong with the credential sent, and the reasons above are deliberately indistinguishable.

    There is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 403 application/json

  The credential is valid but is not allowed to do this. Two codes answer with this status, and error.code says which.

  insufficient_scope: it does not hold the permission. The operation needs, say, audience: read on the newsletter addressed, and this credential holds less than that there. allowed_values carries the permission that was needed, and the message says what the credential does hold on that newsletter, because a credential granted the wrong family and a credential belonging to somebody whose standing on the team has narrowed look identical without it. The answer can differ per newsletter: the same credential may be allowed here and refused on the next one it reaches.

  The same code answers an operation that needs the account permission from a credential that does not carry it. That permission is about the person a credential belongs to rather than about any newsletter, so nothing granted on a newsletter adds up to it. It is granted on the credential itself, when a key is minted or when an authorization asks for account:read.

  And it answers a parameter the credential may send, but not with the value it sent: a filter a credential holding only read permissions may not use, or an expand path whose rows need a permission the operation does not. param names the parameter, and allowed_values carries what this credential may send instead, or is absent when it may send nothing there at all.

  forbidden: it may not act here at all. Either the credential does not reach the newsletter addressed, because it was never granted it or because the person it belongs to can no longer act on it, or it reaches no newsletter at all; param is newsletter, and GET /newsletters lists the ones it does reach. Or, on DELETE /api-keys/{key}, the credential named belongs to somebody else. Neither carries allowed_values, because there is no value to send instead.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 404 application/json

  No such resource, or the key is not allowed to know that it exists. Commune answers 404 rather than 403 where distinguishing the two would leak the existence of private content.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 429 application/json

  Too many requests. Back off and retry after the interval named by the Retry-After response header.

  One of the budgets in RateLimit-Policy ran out, and the RateLimit-* headers on this response say which and when it resets.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

• 500 application/json

  Something failed inside Commune. The request may be retried.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.