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.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/samva-dev:samva-dev-newsletter-domains-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API 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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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:
    PublicationDomainCursor:
      type: string
    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
    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
    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
    OrganizationId:
      type: string
      pattern: ^org_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: OrganizationId
    UnauthorizedError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - UnauthorizedError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    TopicId:
      type: string
      pattern: ^unsub_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: TopicId
    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
    ForbiddenError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ForbiddenError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    InternalError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - InternalError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    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
    NewsletterId:
      type: string
      pattern: ^nl_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: NewsletterId
    FlagDisabledError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - FlagDisabledError
        flag:
          type: string
        message:
          type: string
      required:
      - _tag
      - flag
      - message
      additionalProperties: false
      x-retryable: false
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header