Twilio SendGrid Email Address Validation API

The Twilio SendGrid Email Address Validation API provides real-time detailed information on the validity of email addresses. You can integrate this validation process into your platform's signup form and customize the best use of email address validation for your use case. Email Address Validation is available to [Email API Pro and Premier level accounts](https://sendgrid.com/pricing) only.

OpenAPI Specification

tsg_email_validation_v3.yaml Raw ↑
openapi: 3.1.0
security:
- BearerAuth: []
info:
  title: Twilio SendGrid Email Address Validation API
  summary: ''
  description: 'The Twilio SendGrid Email Address Validation API provides real-time
    detailed information on the validity of email addresses. You can integrate this
    validation process into your platform''s signup form and customize the best use
    of email address validation for your use case.


    Email Address Validation is available to [Email API Pro and Premier level accounts](https://sendgrid.com/pricing)
    only. Prior to upgrading your account to Pro or Premier, you will not see the
    option to create an Email Validation API key. An Email Validation API key is separate
    from and in addition to your other keys, including Full Access API keys.


    You can use this API to:

    - Indicate to users that the address they have entered into a form is invalid.

    - Drop invalid email addresses from your database.

    - Suppress invalid email addresses from your sending to decrease your bounce rate.


    See [**Email Address Validation**](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation)
    for more information.


    You can also view your Email Validation results and metrics in the Validation
    section of the [Twilio SendGrid application user interface](https://docs.sendgrid.com/ui/managing-contacts/email-address-validation).'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: email_validation
servers:
- url: https://api.sendgrid.com
  description: The Twilio SendGrid v3 API
paths:
  /v3/validations/email:
    post:
      operationId: ValidateEmail
      summary: Validate an email
      tags:
      - Email Address Validation
      description: '**This endpoint allows you to validate an email address.**'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The email address that you want to validate.
                source:
                  type: string
                  description: A one-word classifier for where this validation originated.
              required:
              - email
              example:
                email: [email protected]
                source: signup
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    required:
                    - email
                    - verdict
                    - score
                    - local
                    - host
                    - checks
                    - ip_address
                    properties:
                      email:
                        type: string
                        description: The email being validated
                        format: email
                      verdict:
                        type: string
                        description: A generic classification of whether or not the
                          email address is valid.
                        $ref: '#/components/schemas/Verdict'
                      score:
                        type: number
                        description: A numeric representation of the email validity.
                      local:
                        type: string
                        description: The local part of the email address.
                      host:
                        type: string
                        description: The domain of the email address.
                        format: hostname
                      suggestion:
                        type: string
                        description: A suggested correction in the event of domain
                          name typos (e.g., gmial.com)
                      checks:
                        type: object
                        description: Granular checks for email address validity.
                        required:
                        - domain
                        - local_part
                        - additional
                        properties:
                          domain:
                            type: object
                            description: Checks on the domain portion of the email
                              address.
                            required:
                            - has_valid_address_syntax
                            - has_mx_or_a_record
                            - is_suspected_disposable_address
                            properties:
                              has_valid_address_syntax:
                                type: boolean
                                description: Whether the email address syntax is valid.
                              has_mx_or_a_record:
                                type: boolean
                                description: 'Whether the email has appropriate DNS
                                  records to deliver a message. '
                              is_suspected_disposable_address:
                                type: boolean
                                description: Whether the domain appears to be from
                                  a disposable email address service.
                          local_part:
                            type: object
                            description: Checks on the local part of the email address.
                            required:
                            - is_suspected_role_address
                            properties:
                              is_suspected_role_address:
                                type: boolean
                                description: Whether the local part of email appears
                                  to be a role or group (e.g., hr, admin)
                          additional:
                            type: object
                            description: Additional checks on the email address.
                            required:
                            - has_known_bounces
                            - has_suspected_bounces
                            properties:
                              has_known_bounces:
                                type: boolean
                                description: Whether email sent to this address from
                                  your account has bounced.
                              has_suspected_bounces:
                                type: boolean
                                description: Whether our model predicts that the email
                                  address might bounce.
                      source:
                        type: string
                        description: The source of the validation, as per the API
                          request.
                      ip_address:
                        type: string
                        description: The IP address associated with this email.
                required:
                - result
              examples:
                response:
                  value:
                    result:
                      email: [email protected]
                      verdict: Valid
                      score: 0.85021
                      local: cedric
                      host: fogowl.com
                      checks:
                        domain:
                          has_valid_address_syntax: true
                          has_mx_or_a_record: true
                          is_suspected_disposable_address: false
                        local_part:
                          is_suspected_role_address: false
                        additional:
                          has_known_bounces: false
                          has_suspected_bounces: false
                      ip_address: 192.168.1.1
  /v3/validations/email/jobs:
    put:
      operationId: ListEmailJobForVerification
      summary: Request a presigned URL and headers for Bulk Email Address Validation
        list upload.
      tags:
      - Bulk Email Address Validation
      description: '**This endpoint returns a presigned URL and request headers. Use
        this information to upload a list of email addresses for verification.**


        Note that in a successful response the `content-type` header value matches
        the provided `file_type` parameter in the `PUT` request.


        Once you have an `upload_uri` and the `upload_headers`, you''re ready to upload
        your email address list for verification. For the expected format of the email
        address list and a sample upload request, see the [Bulk Email Address Validation
        Overview page](https://www.twilio.com/docs/sendgrid/ui/managing-contacts/email-address-validation/bulk-email-address-validation-overview).

        '
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file_type:
                  type: string
                  description: The format of the file you wish to upload.
                  $ref: '#/components/schemas/FileType'
              required:
              - file_type
              example:
                file_type: csv
      responses:
        '200':
          description: The request was successful. The response contains the URI and
            headers where you will upload your email address list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutValidationsEmailJobs200Response'
              examples:
                response:
                  value:
                    job_id: 01H793APATD899ESMY25ZNPNCF
                    upload_uri: https://example.com/
                    upload_headers:
                    - header: x-amz-server-side-encryption
                      value: aws:kms
                    - header: content-type
                      value: text/csv
        '400':
          description: Bad request. Invalid or missing `file_type` or malformed request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Error message
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: error message
    get:
      operationId: GetValidationsEmailJobs
      summary: This request lists all of a user's Bulk Email Validation Jobs.
      tags:
      - Bulk Email Address Validation
      description: '**This endpoint returns a list of all of a user''s Bulk Email
        Validation Jobs.**'
      responses:
        '200':
          description: The request was successful. The response contains a list of
            all of your Bulk Email Validation Jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidationsEmailJobs200Response'
              examples:
                response:
                  value:
                    result:
                    - id: 01HV9ZZQAFEXW18KFEPTB9YD5E
                      status: Queued
                      started_at: 1712954639
                      finished_at: 0
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: error message
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/validations/email/jobs/{job_id}:
    parameters:
    - name: job_id
      in: path
      description: The ID of the Bulk Email Address Validation Job you wish to retrieve.
      required: true
      schema:
        type: string
    get:
      operationId: GetEmailJobForVerification
      summary: This request returns a single Bulk Email Validation Job.
      tags:
      - Bulk Email Address Validation
      description: '**This endpoint returns a specific Bulk Email Validation Job.
        You can use this endpoint to check on the progress of a Job.**

        '
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetValidationsEmailJobsJobId200Response'
              example:
                response:
                  value:
                    result:
                      id: 01HV9ZZQAFEXW18KFEPTB9YD5E
                      status: Queued
                      segments: 0
                      segments_processed: 0
                      is_download_available: false
                      started_at: 1712954639
                      finished_at: 0
                      errors: []
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: error message
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PutValidationsEmailJobs200Response:
      title: Update Email Validations Jobs 200 Response
      type: object
      properties:
        job_id:
          type: string
          description: The unique ID of the Bulk Email Address Validation Job.
        upload_uri:
          type: string
          description: The URI to use for the request to upload your list of email
            addresses.
        upload_headers:
          type: array
          description: Array containing headers and header values.
          items:
            type: object
            properties:
              header:
                type: string
                description: The name of the header that must be included in the upload
                  request.
              value:
                type: string
                description: The value of the header that must be included in the
                  upload request.
    GetValidationsEmailJobs200Response:
      title: GET Validations Email Jobs 200 Response
      type: object
      properties:
        result:
          type: array
          description: ''
          items:
            type: object
            properties:
              id:
                type: string
                description: The unique ID of the Bulk Email Address Validation Job.
              status:
                type: string
                description: The status of the Bulk Email Address Validation Job.
                $ref: '#/components/schemas/Status'
              started_at:
                description: The ISO8601 timestamp when the Job was created. This
                  is the time at which the upload request was sent to the `upload_uri`.
                type: number
              finished_at:
                description: The ISO8601 timestamp when the Job was finished.
                type: number
    GetValidationsEmailJobsJobId200Response:
      title: GET Validations Email Jobs job_id 200 Response
      type: object
      properties:
        result:
          type: object
          description: ''
          properties:
            id:
              type: string
              description: The unique ID of the Bulk Email Address Validation Job.
            status:
              type: string
              description: The status of the Bulk Email Address Validation Job.
              $ref: '#/components/schemas/Status1'
            segments:
              type: number
              description: The total number of segments in the Bulk Email Address
                Validation Job. There are 1,500 email addresses per segment. The value
                is `0` until the Job `status` is `Processing`.
            segments_processed:
              type: number
              description: The number of segments processed at the time of the request.
                100 segments process in parallel at a time.
            is_download_available:
              type: boolean
              description: Boolean indicating whether the results CSV file is available
                for download.
            started_at:
              description: The ISO8601 timestamp when the Job was created. This is
                the time at which the upload request was sent to the `upload_uri`.
              type: number
            finished_at:
              description: The ISO8601 timestamp when the Job was finished.
              type: number
            errors:
              type: array
              description: Array containing error messages related to the Bulk Email
                Address Validation Job. Array is empty if no errors ocurred.
              items:
                type: object
                properties:
                  message:
                    type: string
                    description: Description of the error encountered during execution
                      of the Bulk Email Address Validation Job.
    ErrorResponse:
      title: Error
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: The message representing the error from the API.
              field:
                type: string
                description: The field associated with the error.
              help:
                type: object
                description: Helper text or docs for troubleshooting.
            required:
            - message
        id:
          type: string
          description: ID representing the error.
      example:
        errors:
        - field: field_name
          message: error message
    Verdict:
      type: string
      enum:
      - Valid
      - Risky
      - Invalid
    FileType:
      type: string
      enum:
      - csv
      - zip
    Status:
      type: string
      enum:
      - Initiated
      - Queued
      - Ready
      - Processing
      - Done
      - Error
    Status1:
      type: string
      enum:
      - Initiated
      - Queued
      - Ready
      - Processing
      - Done
      - Error
  responses: {}
  parameters: {}
  examples: {}
  requestBodies: {}
  headers: {}
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Twilio SendGrid requires you to authenticate with its APIs using
        an API key. The API key must be sent as a bearer token in the Authorization
        header.
tags:
- name: Email Address Validation
  description: The Twilio SendGrid Email Address Validation API
- name: Bulk Email Address Validation
  description: The Twilio SendGrid Bulk Email Address Validation API
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid