Email Validation

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

Email Validation Object

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

Email Validation Result Object

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

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 traverse 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" }
  }
}

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

Home

Guides

Email Validation Object

Email Validation Result Object

Email Validation Endpoints

Start Email Validation

Email Validation Polling

Retrieving Email Validation Results

Cancelling a running Email Validation operation

​Email Validation Object

​Email Validation Result Object

​Email Validation Endpoints

​Start Email Validation

​Email Validation Polling

​Retrieving Email Validation Results

​Cancelling a running Email Validation operation

Email Validation Object

Email Validation Result Object

Email Validation Endpoints

Start Email Validation

Email Validation Polling

Retrieving Email Validation Results

Cancelling a running Email Validation operation