> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get email event statistics

> Returns counts and rates for email events over a time range. The default start time is 30 days ago.



## OpenAPI

````yaml /openapi/source/external/email/email.json get /email_events/stats
openapi: 3.0.3
info:
  x-latency-category: responsive
  x-endpoint-cost: light
  title: Telnyx API
  description: >-
    Programmable email: sending, templates, validation, events, agent inboxes,
    drafts, threads, domains & DKIM, suppressions and unsubscribe groups.
  version: 2.0.0
  contact:
    name: Telnyx
    url: https://telnyx.com
servers:
  - url: https://api.telnyx.com/v2
security:
  - BearerAuth: []
tags:
  - name: Email Validations
    description: Validate email addresses synchronously or in asynchronous batches.
  - name: Email Templates
    description: Create, list, retrieve, update, delete, and render Liquid email templates.
  - name: Email Messages
    description: >-
      Send and manage email messages. Legacy `/v2/emails` routes are aliases for
      these endpoints.
  - name: Email Events
    description: Retrieve account-level email events and event statistics.
  - name: Email Inboxes
    description: >-
      Create and manage agent inboxes, retrieve inbound messages and threads,
      and reply to or forward messages.
  - name: Email Drafts
    description: >-
      Create, list, retrieve, update, delete, and send unsent draft messages
      belonging to an agent inbox.
  - name: Email Threads
    description: >-
      Account-wide conversation threads across every inbox, for agents operating
      many inboxes at once.
  - name: Email Domains
    description: Email domain CRUD operations
  - name: Email Domain DNS Records
    description: DNS verification records for email domains
  - name: Email Webhooks
    description: Per-domain webhook endpoints with event subscriptions
  - name: Email Suppressions
    description: Recipient suppression records (`/v2/email_blocks`).
  - name: Email Suppression Imports
    description: Async CSV import of competitor suppression lists.
  - name: Email Unsubscribe Groups
    description: Named groups and group-scoped suppressions.
paths:
  /email_events/stats:
    get:
      tags:
        - Email Events
      summary: Get email event statistics
      description: >-
        Returns counts and rates for email events over a time range. The default
        start time is 30 days ago.
      operationId: GetEmailEventStats
      parameters:
        - $ref: '#/components/parameters/FromTimestamp'
        - $ref: '#/components/parameters/ToTimestamp'
      responses:
        '200':
          description: Email event statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEventStatsResponse'
              example:
                data:
                  record_type: email_event_stats
                  counts:
                    queued: 0
                    sent: 0
                    delivered: 0
                    deferred: 0
                    bounced: 0
                    opened: 0
                    clicked: 0
                    complained: 0
                    unsubscribed: 0
                    failed: 0
                  rates:
                    delivery_rate: 0
                    bounce_rate: 0
                    deferred_rate: 0
                    open_rate: 0
                    click_rate: 0
                    complaint_rate: 0
                  time_range:
                    from: '2024-01-23T18:10:02.574Z'
                    to: '2024-01-23T18:10:02.574Z'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Telnyx from 'telnyx';

            const client = new Telnyx({
              apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
            });

            const response = await client.emailEvents.retrieveStats();

            console.log(response.data);
        - lang: Python
          source: |
            import os
            from telnyx import Telnyx

            client = Telnyx(
                api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
            )
            response = client.email_events.retrieve_stats()
            print(response.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/team-telnyx/telnyx-go\"\n\t\"github.com/team-telnyx/telnyx-go/option\"\n)\n\nfunc main() {\n\tclient := telnyx.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.EmailEvents.GetStats(context.TODO())\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n"
        - lang: Java
          source: |-
            package com.telnyx.sdk.example;

            import com.telnyx.sdk.client.TelnyxClient;
            import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    TelnyxClient client = TelnyxOkHttpClient.fromEnv();

                    var response = client.emailEvents().retrieveStats();
                }
            }
        - lang: Ruby
          source: |-
            require "telnyx"

            telnyx = Telnyx::Client.new(api_key: "My API Key")

            response = telnyx.email_events.retrieve_stats

            puts(response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Telnyx\Client;

            use Telnyx\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API
            Key');


            try {
              $response = $client->emailEvents->retrieveStats();

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx email-events retrieve-stats \
              --api-key 'My API Key'
components:
  parameters:
    FromTimestamp:
      name: from
      in: query
      description: >-
        Inclusive ISO 8601 start timestamp. Defaults to 30 days ago when
        omitted.
      required: false
      schema:
        type: string
        format: date-time
    ToTimestamp:
      name: to
      in: query
      description: >-
        Inclusive ISO 8601 end timestamp. When `from` is provided without `to`,
        defaults to `from + 30 days`.
      required: false
      schema:
        type: string
        format: date-time
  schemas:
    EmailEventStatsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EmailEventStats'
      required:
        - data
    EmailEventStats:
      type: object
      properties:
        record_type:
          type: string
          enum:
            - email_event_stats
        counts:
          $ref: '#/components/schemas/EmailEventCounts'
        rates:
          $ref: '#/components/schemas/EmailEventRates'
        time_range:
          $ref: '#/components/schemas/TimeRange'
      required:
        - record_type
        - counts
        - rates
        - time_range
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
        suppressed:
          type: array
          description: >-
            Present when every recipient is suppressed, so the request is
            rejected and no message is created.
          items:
            $ref: '#/components/schemas/SuppressedRecipient'
      required:
        - errors
    EmailEventCounts:
      type: object
      description: >-
        Recipient-level outcome counts for the queried time range. Each to, cc,
        and bcc recipient counts separately; repeated events of the same type
        for the same message and recipient count once. Partial MTA injection
        results count successful recipients as sent and unsuccessful recipients
        as failed. Only the ten listed event types are counted; other valid
        event types (scheduled, cancelled, sandbox, sending, rejected) are not
        included in stats.
      properties:
        queued:
          type: integer
          minimum: 0
        sent:
          type: integer
          minimum: 0
        delivered:
          type: integer
          minimum: 0
        deferred:
          type: integer
          minimum: 0
        bounced:
          type: integer
          minimum: 0
        opened:
          type: integer
          minimum: 0
        clicked:
          type: integer
          minimum: 0
        complained:
          type: integer
          minimum: 0
        unsubscribed:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
      required:
        - queued
        - sent
        - delivered
        - deferred
        - bounced
        - opened
        - clicked
        - complained
        - unsubscribed
        - failed
    EmailEventRates:
      type: object
      description: Recipient-level event rates as percentages, rounded to 2 decimal places.
      properties:
        delivery_rate:
          type: number
          format: float
          minimum: 0
          description: Delivered recipients / queued recipients as a percentage.
        bounce_rate:
          type: number
          format: float
          minimum: 0
          description: Bounced recipients / queued recipients as a percentage.
        deferred_rate:
          type: number
          format: float
          minimum: 0
          description: Deferred recipients / queued recipients as a percentage.
        open_rate:
          type: number
          format: float
          minimum: 0
          description: Recipients opened / recipients delivered as a percentage.
        click_rate:
          type: number
          format: float
          minimum: 0
          description: Recipients clicked / recipients opened as a percentage.
        complaint_rate:
          type: number
          format: float
          minimum: 0
          description: >-
            Recipients with a complaint feedback report / delivered recipients
            as a percentage.
      required:
        - delivery_rate
        - bounce_rate
        - deferred_rate
        - open_rate
        - click_rate
        - complaint_rate
    TimeRange:
      type: object
      properties:
        from:
          type: string
          format: date-time
          nullable: true
        to:
          type: string
          format: date-time
          nullable: true
      required:
        - from
        - to
    ErrorObject:
      type: object
      properties:
        code:
          type: string
          description: >-
            Telnyx error code. Edge idempotency errors use 10027 or 10036.
            Fallback 404/500 responses from the framework may use string status
            codes ('404', '500') instead.
          enum:
            - '10001'
            - '10006'
            - '10007'
            - '10015'
            - '10016'
            - '10019'
            - recipient_suppressed
            - reputation_suspended
            - '404'
            - '500'
            - '10027'
            - '10036'
        title:
          type: string
        detail:
          description: >-
            Human-readable error detail. Changeset responses may return a
            structured object.
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        source:
          type: object
          additionalProperties: true
          nullable: true
        meta:
          type: object
          additionalProperties: true
          nullable: true
          description: Additional metadata. Present on 401 errors with a documentation URL.
      required:
        - code
        - title
        - detail
    SuppressedRecipient:
      type: object
      properties:
        to:
          type: string
          format: email
          description: Suppressed recipient email address.
        reason:
          type: string
          description: Suppression reason returned by the recipient suppression service.
        scope:
          type: string
          description: Scope at which the suppression applies.
        override_allowed:
          type: boolean
          description: Whether an authorized send may override this suppression.
      required:
        - to
        - reason
        - scope
        - override_allowed
  responses:
    UnauthorizedResponse:
      description: Not authorized (10006).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - code: '10006'
                title: Not authorized
                detail: Invalid API key
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10006
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Telnyx API key supplied as `Authorization: Bearer <token>`. In
        production, auth may be validated by the API gateway and forwarded via
        Telnyx auth headers.

````