samva-dev

samva-dev Newsletters API

Newsletters, their consent topics, and publishing settings

GitHub OpenAPI

Operations 5

GET /v1/newsletters List newsletters #
POST /v1/newsletters Create a newsletter #
GET /v1/newsletters/{id} Get a newsletter #
PATCH /v1/newsletters/{id} Update a newsletter #
DELETE /v1/newsletters/{id} Delete a newsletter #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/samva-dev/openapi/samva-dev-newsletters-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-email-domain-verification-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-contact-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-template-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-conversation-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-message-schema.json
📊
JSONSchema
https://artifacts.apis.io/samva-dev/json-schema/samva-dev-mailbox-message-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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-newsletters-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

samva-dev-newsletters-api-openapi.yml Raw ↑ 
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:
    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
    NewsletterCreatePayload:
      type: object
      properties:
        topicId:
          anyOf:
          - $ref: '#/components/schemas/TopicId'
          - type: 'null'
        name:
          anyOf:
          - type: string
            minLength: 1
          - 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
    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
    NamespaceId:
      type: string
      pattern: ^ns_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: NamespaceId
    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
    UnauthorizedError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - UnauthorizedError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: false
    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
    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
    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
    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
    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