samva-dev

samva-dev Analytics API

Messaging analytics, channel stats, and data export. Every date range is half-open — `after` inclusive, `before` exclusive — and may span at most 366 days. Both bounds are absolute ISO-8601 instants carrying `Z` or a numeric offset; a bare calendar date is rejected, because reading it as UTC midnight would shift every bucket for an organization outside UTC. `AnalyticsQueryError` refuses a longer span and a `before` sent without an `after`, which bounds nothing. Omitting both bounds reports the organization's whole history. Calendar buckets follow the organization's timezone.

GitHub OpenAPI

Operations 6

GET /v1/analytics/stats Get message volume analytics #
GET /v1/analytics/channel-stats Get channel performance analytics #
GET /v1/analytics/top-contacts List top contacts by message volume #
GET /v1/analytics/hourly-distribution Get hourly message distribution #
GET /v1/analytics/delivery-metrics Get message delivery metrics #
POST /v1/analytics/export Export messaging analytics data #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/samva-dev/openapi/samva-dev-analytics-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-analytics-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-analytics-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Samva Analytics 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: Analytics
  description: Messaging analytics, channel stats, and data export. Every date range is half-open — `after` inclusive, `before` exclusive — and may span at most 366 days. Both bounds are absolute ISO-8601 instants carrying `Z` or a numeric offset; a bare calendar date is rejected, because reading it as UTC midnight would shift every bucket for an organization outside UTC. `AnalyticsQueryError` refuses a longer span and a `before` sent without an `after`, which bounds nothing. Omitting both bounds reports the organization's whole history. Calendar buckets follow the organization's timezone.
paths:
  /v1/analytics/stats:
    get:
      tags:
      - Analytics
      operationId: analytics.getStats
      parameters:
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: groupBy
        in: query
        schema:
          anyOf:
          - type: string
            enum:
            - day
            - week
            - month
          - type: 'null'
        required: false
      - name: channel
        in: query
        schema:
          anyOf:
          - type: string
            enum:
            - email
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  volumeHistory:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        email:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                      required:
                      - date
                      - email
                      additionalProperties: false
                required:
                - volumeHistory
                additionalProperties: false
        '400':
          description: AnalyticsQueryError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryError'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '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 outbound message counts over the half-open selected instant range, grouped by organization-local calendar day, week, or month. A range with traffic returns every bucket in it, including the ones that saw none; a range with no outbound traffic at all returns no buckets. A range with no `before` runs through the current instant, so its quiet trailing buckets are reported as zero.
      summary: Get message volume analytics
      x-samva-scope: analytics:read
  /v1/analytics/channel-stats:
    get:
      tags:
      - Analytics
      operationId: analytics.getChannelStats
      parameters:
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: object
                    properties:
                      sent:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      deliveryRate:
                        type: number
                      uniqueOpenedMessages:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      openTrackingEligibleDeliveredMessages:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      uniqueMessageOpenRate:
                        type: number
                      uniqueClickedMessages:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      clickTrackingEligibleDeliveredMessages:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      uniqueMessageClickRate:
                        type: number
                      bounceRate:
                        type: number
                    required:
                    - sent
                    - deliveryRate
                    - uniqueOpenedMessages
                    - openTrackingEligibleDeliveredMessages
                    - uniqueMessageOpenRate
                    - uniqueClickedMessages
                    - clickTrackingEligibleDeliveredMessages
                    - uniqueMessageClickRate
                    - bounceRate
                    additionalProperties: false
                required:
                - email
                additionalProperties: false
        '400':
          description: AnalyticsQueryError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryError'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '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 aggregate delivery metrics plus unique-message email Open and Click rates over the selected date range. `sent` counts every outbound message accepted in the range; each rate is taken over the messages the channel actually attempted, so one still waiting to be sent neither helps nor hurts it. Each engagement rate uses the corresponding tracking-eligible delivered-message cohort; repeated provider observations do not inflate the numerator.
      summary: Get channel performance analytics
      x-samva-scope: analytics:read
  /v1/analytics/top-contacts:
    get:
      tags:
      - Analytics
      operationId: analytics.getTopContacts
      parameters:
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: limit
        in: query
        schema:
          anyOf:
          - type: integer
            maximum: 100
            exclusiveMinimum: 0
          - type: 'null'
        required: false
      - name: sortBy
        in: query
        schema:
          anyOf:
          - type: string
            enum:
            - sent
            - received
            - total
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      anyOf:
                      - type: string
                      - type: 'null'
                    email:
                      anyOf:
                      - type: string
                      - type: 'null'
                    phone:
                      anyOf:
                      - type: string
                      - type: 'null'
                    messageCount:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                  required:
                  - id
                  - name
                  - email
                  - phone
                  - messageCount
                  additionalProperties: false
        '400':
          description: AnalyticsQueryError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryError'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '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 the contacts your organization exchanged the most messages with over the selected date range. `sortBy` chooses the traffic `messageCount` reports and ranks by: `sent` counts outbound messages addressed to the contact, `received` counts inbound messages the contact sent you, and `total` (the default) counts both. Contacts with no traffic in the range are omitted, and at most 100 are returned.'
      summary: List top contacts by message volume
      x-samva-scope: analytics:read
  /v1/analytics/hourly-distribution:
    get:
      tags:
      - Analytics
      operationId: analytics.getHourlyDistribution
      parameters:
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    hour:
                      type: string
                    count:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                  required:
                  - hour
                  - count
                  additionalProperties: false
        '400':
          description: AnalyticsQueryError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryError'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '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 outbound message counts over the half-open selected instant range, bucketed by organization-local hour. Empty ranges return no rows; non-empty ranges include all 24 hours.
      summary: Get hourly message distribution
      x-samva-scope: analytics:read
  /v1/analytics/delivery-metrics:
    get:
      tags:
      - Analytics
      operationId: analytics.getDeliveryMetrics
      parameters:
      - name: after
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: before
        in: query
        schema:
          anyOf:
          - type: string
            x-samva-schema: AbsoluteInstant
          - type: 'null'
        required: false
      - name: channel
        in: query
        schema:
          anyOf:
          - type: string
            enum:
            - email
          - type: 'null'
        required: false
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  deliveredRate:
                    type: number
                  failedRate:
                    type: number
                  pendingRate:
                    type: number
                  avgDeliveryTimeMs:
                    type: number
                required:
                - deliveredRate
                - failedRate
                - pendingRate
                - avgDeliveryTimeMs
                additionalProperties: false
        '400':
          description: AnalyticsQueryError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryError'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '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 delivered, failed, and pending rates plus average delivery time for the outbound messages accepted in the selected date range, optionally filtered by channel. Every accepted message falls into exactly one of the three, so they always sum to 100%: a complaint counts as delivered because the message arrived, a bounce counts as failed, and anything the provider has not resolved yet counts as pending. Mail your organization received is not rated here.'
      summary: Get message delivery metrics
      x-samva-scope: analytics:read
  /v1/analytics/export:
    post:
      tags:
      - Analytics
      operationId: analytics.exportData
      parameters: []
      security:
      - apiKey: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                  mimeType:
                    type: string
                  filename:
                    type: string
                required:
                - content
                - mimeType
                - filename
                additionalProperties: false
        '400':
          description: AnalyticsQueryError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryError'
        '401':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '403':
          description: ForbiddenError
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '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: 'Exports one record per outbound message accepted in the given date range as CSV or JSON and returns the file content inline. CSV follows RFC 4180: fields containing a quote, comma, or line break are quoted with embedded quotes doubled, and records are separated by CRLF. At most 10,000 records are returned, newest first.'
      summary: Export messaging analytics data
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                after:
                  type: string
                  x-samva-schema: AbsoluteInstant
                before:
                  type: string
                  x-samva-schema: AbsoluteInstant
                format:
                  anyOf:
                  - type: string
                    enum:
                    - csv
                    - json
                  - type: 'null'
                includeChannels:
                  anyOf:
                  - type: array
                    items:
                      type: string
                      enum:
                      - email
                  - type: 'null'
              required:
              - after
              - before
              additionalProperties: false
        required: true
      x-samva-scope: analytics:read
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
    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
    AnalyticsQueryError:
      type: object
      properties:
        _tag:
          type: string
          enum:
          - AnalyticsQueryError
        message:
          type: string
      required:
      - _tag
      - message
      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
    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
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header