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:

  1. POST /email-validations/ with a list of emails that will be validated

  2. In the response, follow the URL provided in response._links.self.href

  3. Continue polling the endpoint while respecting the Retry-After HTTP Header

  4. When validation completes, the results are in response.results

  5. If the results are larger than the default limit, then follow the URL provided in response._links.next.href

​
Email Validation Object

FieldTypeDescription
idstringThe ID of the email validation operation
statusstringThe 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
resultsarray of email_validation_resultThe validation results for the emails provided; default number of results range from 1 up to 100
_linksarray of linksContains useful links related to this resource
_errorsarray of errorsContains the errors if the operation fails

​
Email Validation Result Object

FieldTypeDescription
emailstringThe email address that went through the validation process
catch_allbooleanWhether the domain has been configured to catch all emails or not
resultstringThe 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

​
Email Validation Endpoints

​
Start Email Validation

Request

A batch of emails can be sent to the email validation service, up to 100,000 entries:

POST /email-validations HTTP/1.1
Content-Type: application/json

{	
  "emails": [
		{"email":"foo@example.com"},
		{"email":"bar+baz@example.com"}
	]
}

curl -X POST https://api.amplemarket.com/email-validations \
	-H "Authorization: Bearer {{API Key}}" \
	-H "Content-Type: application/json" \
	-d '{"emails": [{"email":"foo@example.com"}, {"email":"bar+baz@example.com"}]}'

Response

This will return a 202 Accepted indicating that the email validation will soon be started:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /email-validations/1

{
  "id": "1",
  "object": "email_validation",
  "status": "queued",
	"results": [],
	"_links": {
    "self": { "href": "/email-validations/1" }
  }
}

HTTP Headers

  • Location: GET points back to the email validations object that was created

Links

  • self - GET points back to the email validations object that was created

​
Email Validation Polling

Request

The Email Validation object can be polled in order to receive results:

GET /email-validations/{{id}} HTTP/1.1
Content-Type: application/json

curl https://api.amplemarket.com/email-validations/{{id}} \
	-H "Authorization: Bearer {{API Key}}"

Response

Will return a 200 OK while the operation hasn’t yet terminated.

HTTP/1.1 200 OK
Content-Type: application/json
Retry-After: 60

{
  "id": "1",
  "object": "email_validation",
  "status": "processing",
	"results": [],
	"_links": {
    "self": { "href": "/email-validations/1" }
  }
}

HTTP Headers

  • Retry-After - indicates how long to wait until performing another GET request

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

​
Retrieving Email Validation Results

Request

When the email validation operation has terminated, the results can be retrieved using the same url:

GET /email-validations/1 HTTP/1.1
Content-Type: application/json

curl https://api.amplemarket.com/email-validations/{{id}} \
	-H "Authorization: Bearer {{API Key}}"

Response

The response will display up to 100 results:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1",
  "object": "email_validation",
  "status": "completed",
	"results": [
		{
			"object": "email_validation_result",
	    "email": "foo@example.com",
	    "result": "deliverable",
	    "catch_all": false
		},
		{
			"object": "email_validation_result",
	    "email": "bar@example.com",
	    "result": "deliverable",
	    "catch_all": false
		}
	],
	"_links": {
    "self": { "href": "/email-validations/1" },
    "next": { "href": "/email-validations/1?page[size]=100&page[after]=foo@example.com" },
    "prev": { "href": "/email-validations/1?page[size]=100&page[before]=foo@example.com" }
  }
}

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

​
Cancelling a running Email Validation operation

Request

You can cancel an email validation operation that’s still running by sending a PATCH request:

PATCH /email-validations/1 HTTP/1.1
Content-Type: application/json

{
	"status": "canceled"
}

curl -X PATCH https://api.amplemarket.com/email-validations \
	-H "Authorization: Bearer {{API Key}}" \
	-H "Content-Type: application/json" \
	-d '{"status": "canceled"}'

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.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "1",
  "object": "email_validation",
  "status": "canceled",
	"results": [
		{
			"object": "email_validation_result",
	    "email": "foo@example.com",
	    "result": "deliverable",
	    "catch_all": false
		}
  ],
	"_links": {
    "self": { "href": "/email-validations/1" },
    "next": { "href": "/email-validations/1?page[size]=100&page[after]=foo@example.com" },
    "prev": { "href": "/email-validations/1?page[size]=100&page[before]=foo@example.com" }
  }
}

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