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: 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