Twilio SendGrid Statistics API — Stats

naftiko: 1.0.0-alpha2
info:
  label: Twilio SendGrid Statistics API — Stats
  description: 'Twilio SendGrid Statistics API — Stats. 7 operations. Lead operation: Retrieve email statistics by browser..
    Self-contained Naftiko capability covering one Sendgrid business surface.'
  tags:
  - Sendgrid
  - Stats
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SENDGRID_API_KEY: SENDGRID_API_KEY
capability:
  consumes:
  - type: http
    namespace: tsg_stats_v3-stats
    baseUri: https://api.sendgrid.com
    description: Twilio SendGrid Statistics API — Stats business capability. Self-contained, no shared references.
    resources:
    - name: v3-browsers-stats
      path: /v3/browsers/stats
      operations:
      - name: listbrowserstat
        method: GET
        description: Retrieve email statistics by browser.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: browsers
          in: query
          type: string
          description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter
            multiple times.
    - name: v3-clients-stats
      path: /v3/clients/stats
      operations:
      - name: listclientstat
        method: GET
        description: Retrieve email statistics by client type.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v3-clients-client_type-stats
      path: /v3/clients/{client_type}/stats
      operations:
      - name: getclientstat
        method: GET
        description: Retrieve stats by a specific client type.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v3-devices-stats
      path: /v3/devices/stats
      operations:
      - name: listdevicestat
        method: GET
        description: Retrieve email statistics by device type.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v3-geo-stats
      path: /v3/geo/stats
      operations:
      - name: listgeostat
        method: GET
        description: Retrieve email statistics by country and state/province.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: country
          in: query
          type: string
          description: The country you would like to see statistics for. Currently only supported for US and CA.
    - name: v3-mailbox_providers-stats
      path: /v3/mailbox_providers/stats
      operations:
      - name: listmailboxproviderstat
        method: GET
        description: Retrieve email statistics by mailbox provider.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: mailbox_providers
          in: query
          type: string
          description: The mail box providers to get statistics for. You can include up to 10 by including this parameter
            multiple times.
    - name: v3-stats
      path: /v3/stats
      operations:
      - name: liststat
        method: GET
        description: Retrieve global email statistics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: bearer
      token: '{{env.SENDGRID_API_KEY}}'
  exposes:
  - type: rest
    namespace: tsg_stats_v3-stats-rest
    port: 8080
    description: REST adapter for Twilio SendGrid Statistics API — Stats. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v3/browsers/stats
      name: v3-browsers-stats
      description: REST surface for v3-browsers-stats.
      operations:
      - method: GET
        name: listbrowserstat
        description: Retrieve email statistics by browser.
        call: tsg_stats_v3-stats.listbrowserstat
        with:
          browsers: rest.browsers
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/clients/stats
      name: v3-clients-stats
      description: REST surface for v3-clients-stats.
      operations:
      - method: GET
        name: listclientstat
        description: Retrieve email statistics by client type.
        call: tsg_stats_v3-stats.listclientstat
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/clients/{client-type}/stats
      name: v3-clients-client-type-stats
      description: REST surface for v3-clients-client_type-stats.
      operations:
      - method: GET
        name: getclientstat
        description: Retrieve stats by a specific client type.
        call: tsg_stats_v3-stats.getclientstat
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/devices/stats
      name: v3-devices-stats
      description: REST surface for v3-devices-stats.
      operations:
      - method: GET
        name: listdevicestat
        description: Retrieve email statistics by device type.
        call: tsg_stats_v3-stats.listdevicestat
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/geo/stats
      name: v3-geo-stats
      description: REST surface for v3-geo-stats.
      operations:
      - method: GET
        name: listgeostat
        description: Retrieve email statistics by country and state/province.
        call: tsg_stats_v3-stats.listgeostat
        with:
          country: rest.country
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/mailbox-providers/stats
      name: v3-mailbox-providers-stats
      description: REST surface for v3-mailbox_providers-stats.
      operations:
      - method: GET
        name: listmailboxproviderstat
        description: Retrieve email statistics by mailbox provider.
        call: tsg_stats_v3-stats.listmailboxproviderstat
        with:
          mailbox_providers: rest.mailbox_providers
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/stats
      name: v3-stats
      description: REST surface for v3-stats.
      operations:
      - method: GET
        name: liststat
        description: Retrieve global email statistics
        call: tsg_stats_v3-stats.liststat
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: tsg_stats_v3-stats-mcp
    port: 9090
    transport: http
    description: MCP adapter for Twilio SendGrid Statistics API — Stats. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: retrieve-email-statistics-browser
      description: Retrieve email statistics by browser.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.listbrowserstat
      with:
        browsers: tools.browsers
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-email-statistics-client-type
      description: Retrieve email statistics by client type.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.listclientstat
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-stats-specific-client-type
      description: Retrieve stats by a specific client type.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.getclientstat
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-email-statistics-device-type
      description: Retrieve email statistics by device type.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.listdevicestat
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-email-statistics-country-and
      description: Retrieve email statistics by country and state/province.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.listgeostat
      with:
        country: tools.country
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-email-statistics-mailbox-provider
      description: Retrieve email statistics by mailbox provider.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.listmailboxproviderstat
      with:
        mailbox_providers: tools.mailbox_providers
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieve-global-email-statistics
      description: Retrieve global email statistics
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: tsg_stats_v3-stats.liststat
      outputParameters:
      - type: object
        mapping: $.