topics

Edit a subscription topic

PUT /v1/topics/{name}

Auth required api.topics.manage

Edits a topic's display name, description, and default subscription status, writing the change through to SES. The topic is addressed by its immutable name (a name in the body is ignored). Git-backed topics are read-only here (409 conflict) — edit them in the connected repository. An unknown name is 404 not_found.

Path parameters

name string required

The topic's org-unique name (the same identifier GET /v1/topics exposes). An unknown name is 404 not_found.

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.

200 The updated topic application/json

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

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated application/problem+json

404 Resource not found application/problem+json

409 The mutation is rejected by a state rule rather than a bad request — e.g. editing a git-backed (read-only) definition. The code is conflict. application/problem+json

422 Query parameter or path value failed validation application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json

503 An upstream dependency — the AWS SES account connected to this org — refused, throttled, or did not answer in time. The 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

504 An upstream dependency — the AWS SES account connected to this org — refused, throttled, or did not answer in time. The 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

curl -X PUT 'https://api.sendops.dev/v1/topics/string' \ -H "Authorization: Bearer $SENDOPS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"string","display_name":"string","description":"string","default_subscription_status":"OPT_IN"}'

{ "name": "string", "display_name": "string", "description": "string", "default_subscription_status": "OPT_IN", "subscriber_count": 0, "origin": "managed", "source_path": "string", "status": "active", "created_at": "2026-05-17T20:00:00Z", "updated_at": "2026-05-17T20:00:00Z" }