Learn how to validate email addresses.
Email validation plays a critical role in increasing the deliverability rate of email messages sent to potential leads. It allows the user to determine the validity of the email, whether it’s valid or not, or whether there’s some risk associated in having the email bounce.
The email validation flow will usually follow these steps:
POST /email-validations/
with a list of emails that will be validated
In the response, follow the URL provided in response._links.self.href
Continue polling the endpoint while respecting the Retry-After
HTTP Header
When validation completes, the results are in response.results
If the results are larger than the default limit, then follow the URL provided in response._links.next.href
Field | Type | Description |
---|---|---|
id | string | The ID of the email validation operation |
status | string | The status of the email validation operation: |
queued : The validation operation hasn’t started yet | ||
processing : The validation operation is in-progress | ||
completed : The validation operation terminated successfully | ||
canceled : The validation operation terminated due to being canceled | ||
error : The validation operation terminated with an error; see _errors for more details | ||
results | array of email_validation_result | The validation results for the emails provided; default number of results range from 1 up to 100 |
_links | array of links | Contains useful links related to this resource |
_errors | array of errors | Contains the errors if the operation fails |
Field | Type | Description |
---|---|---|
email | string | The email address that went through the validation process |
catch_all | boolean | Whether the domain has been configured to catch all emails or not |
result | string | The result of the validation: |
deliverable : The email provider has confirmed that the email address exists and can receive emails | ||
risky : The email address may result in a bounce or low engagement, usually if it’s a catch-all, mailbox is full, or disposable | ||
unknown : Unable to receive a response from the email provider to determine the status of the email address | ||
undeliverable : The email address is either incorrect or does not exist |
Request
A batch of emails can be sent to the email validation service, up to 100,000 entries:
Response
This will return a 202 Accepted
indicating that the email validation will soon be started:
HTTP Headers
Location
: GET
points back to the email validations object that was createdLinks
self
- GET
points back to the email validations object that was createdRequest
The Email Validation object can be polled in order to receive results:
Response
Will return a 200
OK while the operation hasn’t yet terminated.
HTTP Headers
Retry-After
- indicates how long to wait until performing another GET
requestLinks
self
- GET
points back to the same object
next
- GET
points to the next page of entries, when available
prev
- GET
points to the previous page of entries, when available
Request
When the email validation operation has terminated, the results can be retrieved using the same url:
Response
The response will display up to 100 results:
If the results contains more than 100 entries, then pagination is required transverse them all and can be done using the links such as:response._links.next.href
(e.g. GET /email-validations/1?page[size]=100&page[after]=foo@example.com
).
Links
self
- GET
points back to the same object
next
- GET
points to the next page of entries, when available
prev
- GET
points to the previous page of entries, when available
Request
You can cancel an email validation operation that’s still running by sending a PATCH
request:
Only "status"
is supported in this request, any other field will be ignored.
Response
The response will display any available results up until the point the email validation operation was canceled.
If the results contains more than 100 entries, then pagination is required transverse them all and can be done using the links such as:response._links.next.href
(e.g. GET /email-validations/1?page[size]=100&page[after]=foo@example.com
).
Links
self
- GET
points back to the same object
next
- GET
points to the next page of entries, when available
prev
- GET
points to the previous page of entries, when available