> ## 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/generated/email/events.yml get /email_events/stats
openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: API for retrieving email events and event statistics.
  title: Telnyx Email Events API
  version: 2.0.0
servers:
  - url: https://api.telnyx.com/v2
security:
  - bearerAuth: []
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'
        '401':
          $ref: '#/components/responses/email_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
    email_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
            - 'null'
          format: date-time
        to:
          type:
            - string
            - 'null'
          format: date-time
      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
            - 'null'
          additionalProperties: true
        meta:
          type:
            - object
            - 'null'
          additionalProperties: 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:
    email_UnauthorizedResponse:
      description: Not authorized (10006).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
              - code: '10006'
                title: Not authorized
                detail: Invalid API key
                meta:
                  url: https://developers.telnyx.com/docs/overview/errors/10006
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````