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-subscriptions-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 Subscriptions 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: Subscriptions
  description: Recipient-confirmed topic subscriptions
paths:
  /v1/subscriptions:
    post:
      tags:
      - Subscriptions
      operationId: subscriptions.subscribe
      parameters: []
      security:
      - apiKey: []
      responses:
        '200':
          description: SubscribeResult
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeResult'
        '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 | OnboardingReviewRequiredError | FlagDisabledError
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ForbiddenError'
                - $ref: '#/components/schemas/OnboardingReviewRequiredError'
                - $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 | FromAddressRequiredError | BrandAddressRequiredError | CampaignFooterRequiredError
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/FromAddressRequiredError'
                - $ref: '#/components/schemas/BrandAddressRequiredError'
                - $ref: '#/components/schemas/CampaignFooterRequiredError'
        '429':
          description: RateLimitedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedError'
        '500':
          description: InternalError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
        '502':
          description: BillingProviderError | ExternalServiceError
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/BillingProviderError'
                - $ref: '#/components/schemas/ExternalServiceError'
        '503':
          description: SenderNotReadyError | DeliveryUnavailableError
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/SenderNotReadyError'
                - $ref: '#/components/schemas/DeliveryUnavailableError'
        '504':
          description: GatewayTimeoutError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutError'
      description: Sends a confirmation email from your sender. Only the recipient's explicit confirmation creates their contact and subscribes them to the named topic. The link expires after seven days and can be used once. A custom published email template receives confirmUrl. Sending follows ordinary sender, admission, billing, and brand-footer settings. Requires email send authority in addition to the declared contact grants, including the topic subscription change.
      summary: Request subscription confirmation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribePayload'
        required: true
      x-samva-scope: contacts:create contacts:update
components:
  schemas:
    CampaignFooterRequiredError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - CampaignFooterRequiredError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
    SenderNotReadyError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - SenderNotReadyError
        message:
          type: string
        sender:
          type: string
        retryAfterSeconds:
          anyOf:
          - type: number
          - type: 'null'
      required:
      - _tag
      - message
      - sender
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    BrandAddressRequiredError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - BrandAddressRequiredError
        message:
          type: string
        brand:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - _tag
      - message
      - brand
      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
    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
    BillingProviderError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - BillingProviderError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    DeliveryUnavailableError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - DeliveryUnavailableError
        message:
          type: string
        retryAfterSeconds:
          type: number
      required:
      - _tag
      - message
      - retryAfterSeconds
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    FlagDisabledError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - FlagDisabledError
        flag:
          type: string
        message:
          type: string
      required:
      - _tag
      - flag
      - message
      additionalProperties: false
      x-retryable: false
    SubscribeResult:
      type: object
      properties:
        success:
          type: boolean
        expiresAt:
          type: string
      required:
      - success
      - expiresAt
      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
    FromAddressRequiredError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - FromAddressRequiredError
        message:
          type: string
        verifiedDomains:
          type: array
          items:
            type: string
      required:
      - _tag
      - message
      - verifiedDomains
      additionalProperties: false
      x-category:
      - validation
      x-retryable: false
    SubscribePayload:
      type: object
      properties:
        email:
          type: string
          pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$
          maxLength: 320
          description: The recipient email address; confirmation proves consent for this address.
          x-samva-string-checks:
          - id: effect/schema/isMaxLength
            payload:
              maxLength: 320
        topicId:
          $ref: '#/components/schemas/TopicId'
        from:
          type: object
          properties:
            email:
              type: string
            name:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - email
          additionalProperties: false
          description: Your verified email sender. The ordinary send pipeline selects its domain and customer brand.
        templateSlug:
          anyOf:
          - type: string
            pattern: ^(?=.{1,100}$)[a-z0-9]+(?:-[a-z0-9]+)*$
            description: A published email template slug receiving confirmUrl. Omit it to send the default confirmation email.
          - type: 'null'
        consentIp:
          anyOf:
          - type: string
            maxLength: 128
            description: The recipient IP recorded by your server when they requested subscription.
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 128
          - type: 'null'
        consentSource:
          anyOf:
          - type: string
            maxLength: 512
            description: The signup page or source recorded by your server when consent was requested.
            x-samva-string-checks:
            - id: effect/schema/isMaxLength
              payload:
                maxLength: 512
          - type: 'null'
      required:
      - email
      - topicId
      - from
      additionalProperties: false
    ExternalServiceError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ExternalServiceError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - transient
      x-retryable: true
    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
    TopicId:
      type: string
      pattern: ^unsub_[0-9a-hjkmnp-tv-z]{16,24}$
      x-samva-brand: TopicId
    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
    OnboardingReviewRequiredError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - OnboardingReviewRequiredError
        message:
          type: string
        code:
          type: string
          enum:
          - review_required
          - review_in_progress
          - information_required
          - review_rejected
          - identity_review_required
          - identity_review_rejected
          - identity_changed
        decision:
          type: string
          enum:
          - undecided
          - approved
          - rejected
        stage:
          type: string
          enum:
          - collecting
          - automated_review
          - manual_review
          - information_requested
          - complete
        nextAction:
          type: string
          enum:
          - wait_for_review
          - provide_information
          - verify_sending_identity
          - reapply
          - contact_support
        identityId:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - _tag
      - message
      - code
      - decision
      - stage
      - nextAction
      additionalProperties: false
      x-category:
      - validation
      x-retryable: false
    RateLimitedError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - RateLimitedError
        message:
          type: string
        retryAfterSeconds:
          type: number
      required:
      - _tag
      - message
      - retryAfterSeconds
      additionalProperties: false
      x-category:
      - throttling
      - transient
      x-retryable: true
    ForbiddenError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - ForbiddenError
        message:
          type: string
      required:
      - _tag
      - message
      additionalProperties: false
      x-category:
      - auth
      x-retryable: 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
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header