> ## 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.

# Validate a single email address

> Validates a single email address and returns deliverability checks.



## OpenAPI

````yaml /openapi/source/external/email/email.json post /email_validations
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_validations:
    post:
      tags:
        - Email Validations
      summary: Validate a single email address
      description: Validates a single email address and returns deliverability checks.
      operationId: CreateEmailValidation
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailValidationRequest'
            example:
              email: user@example.com
      responses:
        '200':
          description: Email validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationResponse'
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '400':
          description: >-
            Bad Request / Validation Failed (10015). Invalid, duplicate, empty,
            malformed, or overlong Idempotency-Key headers are rejected by Edge
            with HTTP 400 and error code 10015.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - code: '10015'
                    title: Bad Request
                    detail: email is required
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflictResponse'
        '413':
          $ref: '#/components/responses/PayloadTooLargeResponse'
        '422':
          description: >-
            The Idempotency-Key was already used for a different request
            (10027).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - code: '10027'
                    title: Unprocessable Entity
                    detail: >-
                      The server understood the syntax of the request but was
                      unable to process the instructions.
        '503':
          $ref: '#/components/responses/ServiceUnavailableResponse'
      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 EmailValidation = await client.emailValidations.create({
              email: 'email',
            });

            console.log(EmailValidation.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
            )
            email_validation = client.email_validations.create(
                email="email",
            )
            print(email_validation.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\temailValidation, err := client.EmailValidations.New(\n\t\tcontext.TODO(),\n\t\ttelnyx.EmailValidationNewParams{\n\t\t\tEmail: \"email\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", emailValidation.Data)\n}\n"
        - lang: Java
          source: >-
            package com.telnyx.sdk.example;


            import com.telnyx.sdk.client.TelnyxClient;

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

            import
            com.telnyx.sdk.models.emailValidations.EmailValidationCreateParams;


            public final class Main {
                private Main() {}

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

                    EmailValidationCreateParams params = EmailValidationCreateParams.builder()
                        .email("email")
                        .build();
                    var response = client.emailValidations().create(params);
                }
            }
        - lang: Ruby
          source: |-
            require "telnyx"

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

            email_validation = telnyx.email_validations.create(email: "email")

            puts(email_validation)
        - 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 {
              $email_validation = $client->emailValidations->create(
                email: 'email',
              );

              var_dump($email_validation);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx email-validations create \
              --api-key 'My API Key' \
              --email email
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional opaque, unquoted key for safely retrying the same logical
        request. Keys must contain 1 to 255 letters, numbers, hyphens, or
        underscores. Generate a unique UUID v4 for each operation and reuse it
        only when retrying that operation with the same request. Invalid
        headers—including duplicate, empty, malformed, or overlong values—return
        400 with error code 10015. A request already in progress with the same
        key returns 409; reusing the key with a different request returns 422.
        Only successful responses are replayed, for up to 24 hours. Do not
        include sensitive data in the key.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[A-Za-z0-9_-]{1,255}$
      example: 8e03978e-40d5-43e8-bc93-6894a57f9326
  schemas:
    CreateEmailValidationRequest:
      type: object
      properties:
        email:
          type: string
          description: >-
            Email address to validate. Any non-empty string is accepted; invalid
            syntax returns valid=false rather than a request error.
      required:
        - email
    EmailValidationResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EmailValidation'
      required:
        - data
    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
    EmailValidation:
      type: object
      properties:
        record_type:
          type: string
          enum:
            - email_validation
        email:
          type: string
        valid:
          type: boolean
        risk_score:
          type: number
          format: float
          minimum: 0
        did_you_mean:
          type: string
          description: Suggested correction for typo. Omitted when nil.
        checks:
          $ref: '#/components/schemas/EmailValidationChecks'
      required:
        - record_type
        - email
        - valid
        - risk_score
        - checks
    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
    EmailValidationChecks:
      type: object
      properties:
        syntax:
          $ref: '#/components/schemas/EmailValidationCheck'
        mx:
          $ref: '#/components/schemas/EmailValidationCheck'
        disposable:
          $ref: '#/components/schemas/EmailValidationCheck'
        role_based:
          $ref: '#/components/schemas/EmailValidationCheck'
        typo:
          $ref: '#/components/schemas/EmailValidationTypoCheck'
      required:
        - syntax
        - mx
        - disposable
        - role_based
        - typo
    EmailValidationCheck:
      type: object
      properties:
        pass:
          type: boolean
        details:
          type: string
          description: Human-readable check detail. Omitted when nil.
      required:
        - pass
    EmailValidationTypoCheck:
      allOf:
        - $ref: '#/components/schemas/EmailValidationCheck'
        - type: object
          properties:
            suggestion:
              type: string
              description: Suggested correction for common typos. Omitted when nil.
  headers:
    IdempotentReplayed:
      description: >-
        Present with value `true` when Edge replayed a stored successful
        response for the supplied Idempotency-Key. Omitted for first-time
        requests and error responses.
      schema:
        type: boolean
        enum:
          - true
        example: true
  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
    IdempotencyConflictResponse:
      description: >-
        A request with the same Idempotency-Key is still being processed
        (10036). Retry later with the same key and request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - code: '10036'
                title: Resource is being processed
                detail: >-
                  A request with this Idempotency-Key is already being
                  processed.
                source:
                  pointer: /header/Idempotency-Key
    PayloadTooLargeResponse:
      description: Request body exceeds the 8,000,000-byte limit for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - code: '10007'
                title: Unexpected error
                detail: An unexpected error occured.
    ServiceUnavailableResponse:
      description: >-
        Service unavailable (10016), including an unavailable upstream
        dependency or unavailable Edge idempotency protection for a keyed
        request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
              - code: '10016'
                title: Service Unavailable
                detail: >-
                  The email domain service is temporarily unavailable. Please
                  try again later.
  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.

````