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

# Create a batch email validation job

> Creates an asynchronous batch validation job for up to 1,000 email addresses.



## OpenAPI

````yaml /openapi/generated/email/validations.yml post /email_validations/batch
openapi: 3.1.0
info:
  contact:
    email: support@telnyx.com
  description: API for validating email addresses (single and batch).
  title: Telnyx Email Validations API
  version: 2.0.0
servers:
  - url: https://api.telnyx.com/v2
security:
  - bearerAuth: []
paths:
  /email_validations/batch:
    post:
      tags:
        - Email Validations
      summary: Create a batch email validation job
      description: >-
        Creates an asynchronous batch validation job for up to 1,000 email
        addresses.
      operationId: CreateEmailValidationBatch
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailValidationBatchRequest'
            example:
              emails:
                - user@example.com
                - admin@example.org
              webhook_url: https://example.com/webhooks/email-validation
      responses:
        '202':
          description: Batch validation job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationBatchResponse'
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
        '400':
          description: >-
            Missing or invalid email list, or batch size exceeded. 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/email_ErrorResponse'
              examples:
                invalidEmails:
                  value:
                    errors:
                      - code: '10015'
                        title: Bad Request
                        detail: emails is required and must be an array
        '401':
          $ref: '#/components/responses/email_UnauthorizedResponse'
        '409':
          $ref: '#/components/responses/IdempotencyConflictResponse'
        '413':
          $ref: '#/components/responses/PayloadTooLargeResponse'
        '422':
          description: >-
            Changeset validation error (e.g. invalid webhook_url). Reusing an
            Idempotency-Key with a different request also returns 422 (10027).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_ErrorResponse'
              example:
                errors:
                  - code: '10015'
                    title: Validation Failed
                    detail: webhook_url must be an HTTP or HTTPS URL
                    source:
                      pointer: /data/attributes/webhook_url
        '500':
          $ref: '#/components/responses/email_InternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/email_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 EmailValidationBatch = await
            client.emailValidations.batch.create({
              emails: [],
            });


            console.log(EmailValidationBatch.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_batch = client.email_validations.batch.create(
                emails=[],
            )
            print(email_validation_batch.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\tbatch, err := client.EmailValidations.Batch.New(\n\t\tcontext.TODO(),\n\t\ttelnyx.EmailValidationBatchNewParams{\n\t\t\tEmails: \"emails\",\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", batch.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.batch.BatchCreateParams;

            import java.util.List;


            public final class Main {
                private Main() {}

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

                    BatchCreateParams params = BatchCreateParams.builder()
                        .emails(List.of())
                        .build();
                    var response = client.emailValidations().batch().create(params);
                }
            }
        - lang: Ruby
          source: >-
            require "telnyx"


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


            email_validation_batch =
            telnyx.email_validations.batch.create(emails: [])


            puts(email_validation_batch)
        - 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_batch = $client->emailValidations->batch->create(
                emails: [],
              );

              var_dump($email_validation_batch);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            telnyx email-validations:batch create \
              --api-key 'My API Key' \
              --emails emails
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:
    CreateEmailValidationBatchRequest:
      type: object
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
            description: >-
              Email address to validate. Any string is accepted; validation
              results indicate whether the address is valid. Blank strings are
              discarded and counted in duplicates_removed; if all entries are
              blank, returns 400.
        webhook_url:
          type: string
          format: uri
          maxLength: 2048
          pattern: ^https?://
          description: >-
            URL for batch completion webhook. Empty string is treated as
            omitted. SSRF-protected; private/reserved IPs and internal hostnames
            are rejected.
      required:
        - emails
    EmailValidationBatchResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/EmailValidationBatch'
      required:
        - data
    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
    EmailValidationBatch:
      type: object
      description: Shape returned by the create endpoint. Includes duplicates_removed.
      properties:
        record_type:
          type: string
          enum:
            - email_validation_batch
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/EmailValidationBatchStatus'
        total:
          type: integer
          minimum: 0
        duplicates_removed:
          type: integer
          minimum: 0
        webhook_url:
          type: string
          format: uri
      required:
        - record_type
        - id
        - status
        - total
        - duplicates_removed
    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
    EmailValidationBatchStatus:
      type: string
      enum:
        - pending
        - processing
        - completed
        - failed
  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:
    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
    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/email_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/email_ErrorResponse'
    email_InternalServerErrorResponse:
      description: Internal server error (10019).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/email_ErrorResponse'
          example:
            errors:
              - code: '10019'
                title: Internal Server Error
                detail: Failed to create batch validation
    email_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/email_ErrorResponse'
          example:
            errors:
              - code: '10016'
                title: Service Unavailable
                detail: >-
                  The email domain service is temporarily unavailable. Please
                  try again later.
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````