samva-dev Topics API
Topics and per-channel contact subscriptions
Topics and per-channel contact subscriptions
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/samva-dev:samva-dev-topics-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Samva Topics API
version: 1.0.0
description: Samva is the email API for your app. Send transactional email in one typed call. Delivery events and customer replies come back as signed webhooks, and replies thread to the email they answer.
servers:
- url: https://api.samva.dev
security: []
tags:
- name: Topics
description: Topics and per-channel contact subscriptions
paths:
/v1/topics:
get:
tags:
- Topics
operationId: topics.list
parameters:
- name: namespaceId
in: query
schema:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: TopicList
content:
application/json:
schema:
$ref: '#/components/schemas/TopicList'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Lists visible topics, default first then by name. The organization holds at most 200 topics, so the list is bounded and unpaged.
summary: List topics
x-samva-scope: contacts:read
post:
tags:
- Topics
operationId: topics.create
parameters: []
security:
- apiKey: []
responses:
'201':
description: Topic
content:
application/json:
schema:
$ref: '#/components/schemas/Topic'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'409':
description: ConflictError
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Creates a topic in the caller's or requested namespace. The subscription default is opt_out when omitted. Sending defaults must be compatible with that namespace. An organization holds at most 200 topics.
summary: Create a topic
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TopicCreatePayload'
required: true
x-samva-scope: contacts:create
/v1/topics/check:
get:
tags:
- Topics
operationId: topics.checkSubscription
parameters:
- name: contactId
in: query
schema:
anyOf:
- $ref: '#/components/schemas/ContactId'
- type: 'null'
required: false
- name: email
in: query
schema:
anyOf:
- type: string
- type: 'null'
required: false
- name: phone
in: query
schema:
anyOf:
- type: string
- type: 'null'
required: false
- name: namespaceId
in: query
schema:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
required: false
- name: channel
in: query
schema:
type: string
enum:
- email
required: true
- name: topicIds
in: query
schema:
anyOf:
- type: string
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: TopicSubscriptionCheck
content:
application/json:
schema:
$ref: '#/components/schemas/TopicSubscriptionCheck'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Name exactly one contactId, email, or phone and a channel. Returns effective status, using the topic default when no explicit subscription exists. topicIds is an optional comma-separated list. Addresses resolve within the requested namespace; an unknown address returns contactId null and the effective defaults.
summary: Check topic subscriptions
x-samva-scope: contacts:read
/v1/topics/{id}:
get:
tags:
- Topics
operationId: topics.get
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/TopicId'
required: true
security:
- apiKey: []
responses:
'200':
description: Topic
content:
application/json:
schema:
$ref: '#/components/schemas/Topic'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Returns a visible topic, its sending defaults, and explicit subscription counts by channel and status. Individual subscriptions are read through listSubscriptions.
summary: Get a topic
x-samva-scope: contacts:read
patch:
tags:
- Topics
operationId: topics.update
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/TopicId'
required: true
security:
- apiKey: []
responses:
'200':
description: Topic
content:
application/json:
schema:
$ref: '#/components/schemas/Topic'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'409':
description: ConflictError
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Updates named fields. Changing the default does not change any explicit subscription status. Null clears a sending default.
summary: Update a topic
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TopicUpdatePayload'
required: true
x-samva-scope: contacts:update
delete:
tags:
- Topics
operationId: topics.remove
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/TopicId'
required: true
security:
- apiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
required:
- success
additionalProperties: false
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'409':
description: ConflictError
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Refuses the default topic and any topic a scheduled or running campaign uses.
summary: Delete a topic
x-samva-scope: contacts:delete
/v1/topics/{id}/default:
post:
tags:
- Topics
operationId: topics.setDefault
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/TopicId'
required: true
security:
- apiKey: []
responses:
'200':
description: Topic
content:
application/json:
schema:
$ref: '#/components/schemas/Topic'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Makes this the default category of messages in its namespace. Existing explicit subscription statuses remain unchanged.
summary: Make a topic the default
x-samva-scope: contacts:update
/v1/topics/{id}/subscriptions:
get:
tags:
- Topics
operationId: topics.listSubscriptions
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/TopicId'
required: true
- name: limit
in: query
schema:
anyOf:
- type: integer
maximum: 100
exclusiveMinimum: 0
description: Items per page, at most 100.
- type: 'null'
required: false
- name: cursor
in: query
schema:
anyOf:
- $ref: '#/components/schemas/Cursor'
- type: 'null'
required: false
- name: channel
in: query
schema:
anyOf:
- type: string
enum:
- email
- type: 'null'
required: false
- name: status
in: query
schema:
anyOf:
- type: string
enum:
- subscribed
- unsubscribed
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: TopicSubscriptionPage
content:
application/json:
schema:
$ref: '#/components/schemas/TopicSubscriptionPage'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Returns explicit per-channel subscriptions, newest first, optionally filtered by channel and status. Pass nextCursor as cursor to continue; nextCursor is null on the last page. Contacts without an explicit subscription are absent from this list.
summary: List topic subscriptions
x-samva-scope: contacts:read
post:
tags:
- Topics
operationId: topics.setSubscriptions
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/TopicId'
required: true
security:
- apiKey: []
responses:
'200':
description: TopicSetSubscriptionsResult
content:
application/json:
schema:
$ref: '#/components/schemas/TopicSetSubscriptionsResult'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'402':
description: PaymentRequiredError
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequiredError'
'403':
description: ForbiddenError
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: ResourceNotFoundError
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceNotFoundError'
'422':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: InternalError
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'502':
description: BillingProviderError
content:
application/json:
schema:
$ref: '#/components/schemas/BillingProviderError'
'504':
description: GatewayTimeoutError
content:
application/json:
schema:
$ref: '#/components/schemas/GatewayTimeoutError'
description: Upserts explicit subscribed or unsubscribed status for one channel. Each contact is named by ID, email, or phone. New addresses create contacts in the topic's namespace. Repeating the same status is idempotent.
summary: Set topic subscriptions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TopicSetSubscriptionsPayload'
required: true
x-samva-scope: contacts:update
components:
schemas:
ConflictError:
type: object
properties:
_tag:
type: string
enum:
- ConflictError
message:
type: string
resource:
type: string
id:
anyOf:
- type: string
- type: 'null'
required:
- _tag
- message
- resource
additionalProperties: false
x-category:
- conflict
x-retryable: false
TopicSubscriptionCheck:
type: object
properties:
contactId:
anyOf:
- $ref: '#/components/schemas/ContactId'
- type: 'null'
channel:
type: string
enum:
- email
topics:
type: array
items:
type: object
properties:
topicId:
$ref: '#/components/schemas/TopicId'
topicName:
type: string
status:
type: string
enum:
- subscribed
- unsubscribed
required:
- topicId
- topicName
- status
additionalProperties: false
required:
- contactId
- channel
- topics
additionalProperties: false
ValidationError:
type: object
properties:
_tag:
type: string
enum:
- ValidationError
message:
type: string
fields:
anyOf:
- type: object
additionalProperties:
type: array
items:
type: string
- type: 'null'
required:
- _tag
- message
additionalProperties: false
x-category:
- validation
x-retryable: false
GatewayTimeoutError:
type: object
properties:
_tag:
type: string
enum:
- GatewayTimeoutError
message:
type: string
retryAfterSeconds:
type: number
required:
- _tag
- message
- retryAfterSeconds
additionalProperties: false
x-category:
- transient
x-retryable: true
TopicContactByEmail:
type: object
properties:
email:
type: string
required:
- email
additionalProperties: false
ContactId:
type: string
pattern: ^contact_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: ContactId
TopicCreatePayload:
type: object
properties:
name:
type: string
maxLength: 120
minLength: 1
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 120
description:
anyOf:
- type: string
- type: 'null'
- type: 'null'
namespaceId:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
- type: 'null'
default:
anyOf:
- type: string
enum:
- opt_out
- opt_in
- type: 'null'
defaultSenderId:
anyOf:
- $ref: '#/components/schemas/EmailSenderId'
- type: 'null'
- type: 'null'
replyMailboxId:
anyOf:
- $ref: '#/components/schemas/MailboxId'
- type: 'null'
- type: 'null'
templateId:
anyOf:
- $ref: '#/components/schemas/TemplateId'
- type: 'null'
- type: 'null'
required:
- name
additionalProperties: false
TemplateId:
type: string
pattern: ^tmpl_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TemplateId
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
TopicSubscriptionCounts:
type: object
properties:
email:
type: object
properties:
subscribed:
type: integer
minimum: 0
maximum: 9007199254740991
unsubscribed:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- subscribed
- unsubscribed
additionalProperties: false
required:
- email
additionalProperties: false
BillingProviderError:
type: object
properties:
_tag:
type: string
enum:
- BillingProviderError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
TopicId:
type: string
pattern: ^unsub_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TopicId
ForbiddenError:
type: object
properties:
_tag:
type: string
enum:
- ForbiddenError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
UnauthorizedError:
type: object
properties:
_tag:
type: string
enum:
- UnauthorizedError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: false
TopicContactByPhone:
type: object
properties:
phone:
type: string
required:
- phone
additionalProperties: false
EmailSenderId:
type: string
pattern: ^sender_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: EmailSenderId
TopicSubscription:
type: object
properties:
contactId:
$ref: '#/components/schemas/ContactId'
channel:
type: string
enum:
- email
status:
type: string
enum:
- subscribed
- unsubscribed
source:
type: string
subscribedAt:
anyOf:
- type: string
- type: 'null'
unsubscribedAt:
anyOf:
- type: string
- type: 'null'
createdAt:
type: string
updatedAt:
type: string
required:
- contactId
- channel
- status
- source
- subscribedAt
- unsubscribedAt
- createdAt
- updatedAt
additionalProperties: false
Cursor:
type: string
Topic:
type: object
properties:
id:
$ref: '#/components/schemas/TopicId'
namespaceId:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
name:
type: string
description:
anyOf:
- type: string
- type: 'null'
default:
type: string
enum:
- opt_out
- opt_in
isDefault:
type: boolean
defaultSenderId:
anyOf:
- $ref: '#/components/schemas/EmailSenderId'
- type: 'null'
replyMailboxId:
anyOf:
- $ref: '#/components/schemas/MailboxId'
- type: 'null'
templateId:
anyOf:
- $ref: '#/components/schemas/TemplateId'
- type: 'null'
subscriptions:
$ref: '#/components/schemas/TopicSubscriptionCounts'
createdAt:
type: string
updatedAt:
type: string
required:
- id
- namespaceId
- name
- description
- default
- isDefault
- defaultSenderId
- replyMailboxId
- templateId
- subscriptions
- createdAt
- updatedAt
additionalProperties: false
TopicSetSubscriptionsResult:
type: object
properties:
updated:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- updated
additionalProperties: false
TopicContactRef:
anyOf:
- $ref: '#/components/schemas/TopicContactById'
- $ref: '#/components/schemas/TopicContactByEmail'
- $ref: '#/components/schemas/TopicContactByPhone'
TopicSubscriptionPage:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/TopicSubscription'
nextCursor:
anyOf:
- type: string
- type: 'null'
required:
- items
- nextCursor
additionalProperties: false
NamespaceId:
type: string
pattern: ^ns_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: NamespaceId
MailboxId:
type: string
pattern: ^mbx_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: MailboxId
TopicList:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Topic'
maxItems: 200
required:
- items
additionalProperties: false
PaymentRequiredError:
type: object
properties:
_tag:
type: string
enum:
- PaymentRequiredError
message:
type: string
resource:
type: string
currentUsage:
type: number
limit:
type: number
required:
- _tag
- message
- resource
- currentUsage
- limit
additionalProperties: false
x-category:
- billing
x-retryable: false
TopicSetSubscriptionsPayload:
type: object
properties:
contacts:
type: array
items:
$ref: '#/components/schemas/TopicContactRef'
minItems: 1
maxItems: 1000
channel:
type: string
enum:
- email
status:
type: string
enum:
- subscribed
- unsubscribed
source:
anyOf:
- type: string
minLength: 1
maxLength: 512
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 512
- type: 'null'
required:
- contacts
- channel
- status
additionalProperties: false
ResourceNotFoundError:
type: object
properties:
_tag:
type: string
enum:
- ResourceNotFoundError
resource:
type: string
id:
type: string
message:
type: string
required:
- _tag
- resource
- id
- message
additionalProperties: false
x-category:
- notFound
x-retryable: false
TopicUpdatePayload:
type: object
properties:
name:
anyOf:
- type: string
maxLength: 120
minLength: 1
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 120
- type: 'null'
description:
anyOf:
- type: string
- type: 'null'
- type: 'null'
default:
anyOf:
- type: string
enum:
- opt_out
- opt_in
- type: 'null'
defaultSenderId:
anyOf:
- $ref: '#/components/schemas/EmailSenderId'
- type: 'null'
- type: 'null'
replyMailboxId:
anyOf:
- $ref: '#/components/schemas/MailboxId'
- type: 'null'
- type: 'null'
templateId:
anyOf:
- $ref: '#/components/schemas/TemplateId'
- type: 'null'
- type: 'null'
additionalProperties: false
TopicContactById:
type: object
properties:
contactId:
$ref: '#/components/schemas/ContactId'
required:
- contactId
additionalProperties: false
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header