samva-dev Newsletter domains API
Custom domains for newsletter archives
Custom domains for newsletter archives
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-newsletter-domains-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 Newsletter domains 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: Newsletter domains
description: Custom domains for newsletter archives
paths:
/v1/newsletters/{id}/domains:
get:
tags:
- Newsletter domains
operationId: newsletterDomains.list
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/NewsletterId'
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/PublicationDomainCursor'
- type: 'null'
required: false
security:
- apiKey: []
responses:
'200':
description: PublicationDomainPage
content:
application/json:
schema:
$ref: '#/components/schemas/PublicationDomainPage'
'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: Returns this newsletter's domains in hostname order with their latest recorded verification status. Removed domains are omitted. Pass nextCursor as cursor for the next page; it is null on the last page. Get a domain to recheck its current DNS and certificate status. Requires newsletters.
summary: List publication domains
x-samva-scope: contacts:read
post:
tags:
- Newsletter domains
operationId: newsletterDomains.add
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:
organizationId:
$ref: '#/components/schemas/OrganizationId'
topicId:
$ref: '#/components/schemas/TopicId'
hostname:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
canonicalHostname:
type: string
phase:
type: string
enum:
- pending
- active
- removing
- removed
- conflict
active:
type: boolean
hostnameStatus:
anyOf:
- type: string
- type: 'null'
sslStatus:
anyOf:
- type: string
- type: 'null'
cname:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationRecords:
type: array
items:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationErrors:
type: array
items:
type: string
required:
- organizationId
- topicId
- hostname
- canonicalHostname
- phase
- active
- hostnameStatus
- sslStatus
- cname
- verificationRecords
- verificationErrors
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: Claims a hostname for an opt-in topic with its public archive enabled and published. Requires newsletters. Pass the same Idempotency-Key header when retrying. The hostname serves no publication until Cloudflare confirms both ownership and SSL are active.
summary: Add a publication domain
requestBody:
content:
application/json:
schema:
type: object
properties:
hostname:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
required:
- hostname
additionalProperties: false
required: true
x-idempotent: true
x-samva-scope: contacts:create
/v1/newsletters/{id}/domains/{hostname}:
get:
tags:
- Newsletter domains
operationId: newsletterDomains.get
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/NewsletterId'
required: true
- name: hostname
in: path
schema:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
required: true
security:
- apiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
organizationId:
$ref: '#/components/schemas/OrganizationId'
topicId:
$ref: '#/components/schemas/TopicId'
hostname:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
canonicalHostname:
type: string
phase:
type: string
enum:
- pending
- active
- removing
- removed
- conflict
active:
type: boolean
hostnameStatus:
anyOf:
- type: string
- type: 'null'
sslStatus:
anyOf:
- type: string
- type: 'null'
cname:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationRecords:
type: array
items:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationErrors:
type: array
items:
type: string
required:
- organizationId
- topicId
- hostname
- canonicalHostname
- phase
- active
- hostnameStatus
- sslStatus
- cname
- verificationRecords
- verificationErrors
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: Rechecks ownership and certificate status, returning DNS verification records. Domains outside this newsletter's organization or namespace return 404.
summary: Get a publication domain
x-samva-scope: contacts:read
delete:
tags:
- Newsletter domains
operationId: newsletterDomains.remove
parameters:
- name: id
in: path
schema:
$ref: '#/components/schemas/NewsletterId'
required: true
- name: hostname
in: path
schema:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
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:
organizationId:
$ref: '#/components/schemas/OrganizationId'
topicId:
$ref: '#/components/schemas/TopicId'
hostname:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
canonicalHostname:
type: string
phase:
type: string
enum:
- pending
- active
- removing
- removed
- conflict
active:
type: boolean
hostnameStatus:
anyOf:
- type: string
- type: 'null'
sslStatus:
anyOf:
- type: string
- type: 'null'
cname:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationRecords:
type: array
items:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationErrors:
type: array
items:
type: string
required:
- organizationId
- topicId
- hostname
- canonicalHostname
- phase
- active
- hostnameStatus
- sslStatus
- cname
- verificationRecords
- verificationErrors
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: Revokes publication lookup before removing the Cloudflare hostname. Pass the same Idempotency-Key header on retries. Pending provider teardown is reported as removing. Removal remains available after the topic archive is disabled.
summary: Remove a publication domain
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
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
PublicationDomainPage:
type: object
properties:
items:
type: array
items:
type: object
properties:
organizationId:
$ref: '#/components/schemas/OrganizationId'
topicId:
$ref: '#/components/schemas/TopicId'
hostname:
type: string
maxLength: 253
pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 253
canonicalHostname:
type: string
phase:
type: string
enum:
- pending
- active
- removing
- removed
- conflict
active:
type: boolean
hostnameStatus:
anyOf:
- type: string
- type: 'null'
sslStatus:
anyOf:
- type: string
- type: 'null'
cname:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationRecords:
type: array
items:
type: object
properties:
type:
type: string
enum:
- CNAME
- TXT
name:
type: string
value:
type: string
required:
- type
- name
- value
additionalProperties: false
verificationErrors:
type: array
items:
type: string
required:
- organizationId
- topicId
- hostname
- canonicalHostname
- phase
- active
- hostnameStatus
- sslStatus
- cname
- verificationRecords
- verificationErrors
additionalProperties: false
nextCursor:
anyOf:
- type: string
- type: 'null'
required:
- items
- nextCursor
additionalProperties: false
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
PublicationDomainCursor:
type: string
OrganizationId:
type: string
pattern: ^org_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: OrganizationId
NewsletterId:
type: string
pattern: ^nl_[0-9a-hjkmnp-tv-z]{16,24}$
x-samva-brand: NewsletterId
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
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header