samva-dev Subscriptions API
Recipient-confirmed topic subscriptions
Recipient-confirmed topic subscriptions
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-subscriptions-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 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:
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
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
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
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
ExternalServiceError:
type: object
properties:
_tag:
type: string
enum:
- ExternalServiceError
message:
type: string
required:
- _tag
- message
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
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
InternalError:
type: object
properties:
_tag:
type: string
enum:
- InternalError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
BillingProviderError:
type: object
properties:
_tag:
type: string
enum:
- BillingProviderError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- transient
x-retryable: true
CampaignFooterRequiredError:
type: object
properties:
_tag:
type: string
enum:
- CampaignFooterRequiredError
message:
type: string
required:
- _tag
- message
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
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
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
maxLength: 120
x-samva-string-checks:
- id: effect/schema/isMaxLength
payload:
maxLength: 120
- 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
UnauthorizedError:
type: object
properties:
_tag:
type: string
enum:
- UnauthorizedError
message:
type: string
required:
- _tag
- message
additionalProperties: false
x-category:
- auth
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
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
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
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
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
SubscribeResult:
type: object
properties:
success:
type: boolean
expiresAt:
type: string
required:
- success
- expiresAt
additionalProperties: false
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header