Create a subscription topic
Creates a new managed subscription-topic definition and writes it
through to the org's SES contact list. name is the stable, immutable
org-unique handle other calls reference the topic by. A name already in
use returns 409 conflict — including a name owned by a git-backed
topic (the repo owns that name). 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.
origin string enum required Where the definition is authored. managed topics are editable via this API (and written through to SES); git topics are synced from a connected repository and read-only here (the repo wins).
One of: managed, git
source_path string optional Repo-relative topic-schema file the definition was synced from. Present only for git-backed topics.
status string enum required Provenance-only lifecycle state. archived marks a git-backed topic whose name was removed from the repo; it reactivates in place if the name returns.
One of: active, archived
created_at string<date-time> required updated_at string<date-time> required code is conflict.
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