samva-dev Newsletters API
Newsletters, their consent topics, and publishing settings
Newsletters, their consent topics, and publishing settings
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-newsletters-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 Newsletters 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: Newsletters
description: Newsletters, their consent topics, and publishing settings
paths:
/v1/newsletters:
get:
tags:
- Newsletters
operationId: newsletters.list
parameters:
- name: namespaceId
in: query
schema:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Newsletter'
required:
- items
additionalProperties: false
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError | FlagDisabledError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ForbiddenError'
- $ref: '#/components/schemas/FlagDisabledError'
'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: List visible newsletters and their consent topics and publishing settings. The topic namespace bounds access.
summary: List newsletters
x-samva-scope: contacts:read
post:
tags:
- Newsletters
operationId: newsletters.create
parameters:
- name: idempotency-key
in: header
schema:
anyOf:
- type: string
minLength: 1
maxLength: 255
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 255
- type: 'null'
required: false
security:
- apiKey: []
responses:
'201':
description: Newsletter
content:
application/json:
schema:
$ref: '#/components/schemas/Newsletter'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError | FlagDisabledError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ForbiddenError'
- $ref: '#/components/schemas/FlagDisabledError'
'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 an opt-in topic, or adopts topicId. Name is required when creating a topic. A topic belongs to at most one newsletter. Sending defaults and subscriptions belong to the topic.
summary: Create a newsletter
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterCreatePayload'
required: true
x-idempotent: true
x-samva-scope: contacts:create
/v1/newsletters/{id}:
get:
tags:
- Newsletters
operationId: newsletters.get
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/NewsletterId'
required: true
security:
- apiKey: []
responses:
'200':
description: Newsletter
content:
application/json:
schema:
$ref: '#/components/schemas/Newsletter'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError | FlagDisabledError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ForbiddenError'
- $ref: '#/components/schemas/FlagDisabledError'
'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: Read one newsletter, including its consent topic ID, issue project, archive status, and hosted slug.
summary: Get a newsletter
x-samva-scope: contacts:read
patch:
tags:
- Newsletters
operationId: newsletters.update
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/NewsletterId'
required: true
- name: idempotency-key
in: header
schema:
anyOf:
- type: string
minLength: 1
maxLength: 255
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 255
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: Newsletter
content:
application/json:
schema:
$ref: '#/components/schemas/Newsletter'
'401':
description: UnauthorizedError
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: ForbiddenError | FlagDisabledError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ForbiddenError'
- $ref: '#/components/schemas/FlagDisabledError'
'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: Update named publishing settings. An enabled archive requires an opt-in topic and a hosted slug. Null clears the slug when the archive is disabled.
summary: Update a newsletter
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewsletterUpdatePayload'
required: true
x-idempotent: true
x-samva-scope: contacts:update
delete:
tags:
- Newsletters
operationId: newsletters.remove
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/NewsletterId'
required: true
- name: idempotency-key
in: header
schema:
anyOf:
- type: string
minLength: 1
maxLength: 255
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 255
- type: 'null'
required: false
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 | FlagDisabledError
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ForbiddenError'
- $ref: '#/components/schemas/FlagDisabledError'
'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: Withdraws the public archive and removes the issue repository. The consent topic and its subscriptions remain.
summary: Delete a newsletter
x-idempotent: true
x-samva-scope: contacts:delete
components:
schemas:
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
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
NewsletterCreatePayload:
type: object
properties:
topicId:
anyOf:
- $ref: '#/components/schemas/TopicId'
- type: 'null'
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'
namespaceId:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
- type: 'null'
archiveEnabled:
anyOf:
- type: boolean
- type: 'null'
publicationSlug:
anyOf:
- type: string
pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
- type: 'null'
- type: 'null'
additionalProperties: false
UnauthorizedError:
type: object
properties:
_tag:
type: string
enum:
- UnauthorizedError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
x-retryable: 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
FlagDisabledError:
type: object
properties:
_tag:
type: string
enum:
- FlagDisabledError
flag:
type: string
message:
type: string
required:
- _tag
- flag
- message
additionalProperties: false
x-retryable: false
NamespaceId:
type: string
pattern: ^ns_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: NamespaceId
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
TemplateProjectId:
type: string
pattern: ^tproj_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: TemplateProjectId
NewsletterId:
type: string
pattern: ^nl_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: NewsletterId
NewsletterUpdatePayload:
type: object
properties:
archiveEnabled:
anyOf:
- type: boolean
- type: 'null'
publicationSlug:
anyOf:
- type: string
pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
- type: 'null'
- type: 'null'
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
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
Newsletter:
type: object
properties:
id:
$ref: '#/components/schemas/NewsletterId'
topicId:
$ref: '#/components/schemas/TopicId'
namespaceId:
anyOf:
- $ref: '#/components/schemas/NamespaceId'
- type: 'null'
name:
type: string
description:
anyOf:
- type: string
- type: 'null'
issueProjectId:
anyOf:
- $ref: '#/components/schemas/TemplateProjectId'
- type: 'null'
archiveEnabled:
type: boolean
publicationSlug:
anyOf:
- type: string
pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
- type: 'null'
createdAt:
type: string
updatedAt:
type: string
required:
- id
- topicId
- namespaceId
- name
- description
- issueProjectId
- archiveEnabled
- publicationSlug
- createdAt
- updatedAt
additionalProperties: false
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header