Create a subscription topic
Creates a new managed subscription-topic definition in the
workspace. name is the stable, immutable org-unique handle other
calls reference the topic by. A name already in use returns
409 conflict. Definition-only: subscriber preferences are set on the
contacts surface.
Request body
Content type: application/json
name string required The topic's immutable org-unique name. Required on create; ignored on edit.
display_name string required description string optional default_subscription_status string enum optional Default subscription status for contacts with no explicit preference.
One of: OPT_IN, OPT_OUT
Responses
Errors follow the RFC 7807 problem format — see the error reference.
name string required Stable topic identifier used in filters and preferences.
display_name string required description string required default_subscription_status string enum required One of: OPT_IN, OPT_OUT
subscriber_count integer<int64> required Contacts effectively subscribed to this topic — those whose explicit
preference is OPT_IN, plus those with no explicit preference on a
topic whose default_subscription_status is OPT_IN. Excludes
master-unsubscribed contacts. This is the set that would be mailed.
status string enum required Lifecycle state. archived never blocks the topic's use.
One of: active, archived
is_default boolean required true for the workspace's default topic: the topic a broadcast or a
marketing workflow send uses when it names none. It cannot be
deleted until another topic is made the default in Settings. At
most one topic is the default; a workspace without a default topic
reports false on every topic.
ses_linked boolean required true when the topic is linked to a topic on your AWS account's SES
contact list. Opt-outs on a linked topic sync both ways: one made on
the SES-hosted unsubscribe page reaches this topic, and one made
here reaches SES. Linking is managed in the dashboard (Adopt,
Unlink, Move); it cannot be changed through the API.
created_at string<date-time> required updated_at string<date-time> required code is conflict.
application/problem+json validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json code is
upstream_unavailable; the status is 503 when the call failed and
504 when it exceeded our deadline.
Retryable. Always accompanied by Retry-After. On a 504 the
outcome is genuinely unknown (the write may have reached SES), so
retries of a non-idempotent call should carry an Idempotency-Key.
The detail string is deliberately generic: the underlying AWS error
describes the customer's own account and is recorded in SendOps logs
against the request_id, not returned here.
application/problem+json code is
upstream_unavailable; the status is 503 when the call failed and
504 when it exceeded our deadline.
Retryable. Always accompanied by Retry-After. On a 504 the
outcome is genuinely unknown (the write may have reached SES), so
retries of a non-idempotent call should carry an Idempotency-Key.
The detail string is deliberately generic: the underlying AWS error
describes the customer's own account and is recorded in SendOps logs
against the request_id, not returned here.
application/problem+json