Email Validation API - Verify and Append Names

Clean a mailing list and learn something about it at the same time. Every address comes back with a verdict, the reason behind it, a quality score, and the first name, last name, gender and birth year the provider holds on that address. One flat row per address.

What this actor does

• Validates and enriches in the same pass. Most list cleaning tells you only whether to send. This provider returns the identity on the address alongside the verdict, so a hygiene run doubles as an enrichment run at no extra cost: first name, last name, full name, gender and birth year, plus the mailbox part and any plus-tag on the address.
• Returns the reason, not just the verdict. Every row carries one of five verdicts and one of eleven reason codes underneath it. That is what separates a receiving server that timed out and will verify perfectly on a retry from a mailbox that genuinely does not exist. Both are offered as filters.
• Suggests a fix for a typo. When an address looks like a misspelling of a real domain, the provider returns what it thinks was meant. That is the difference between throwing away a signup and recovering it, since a person who typed one wrong character in a common webmail domain is still a real subscriber.
• Scores quality from zero to one hundred. The verdict alone is blunt. The score lets you keep the stronger risky addresses and drop the weak ones rather than losing a whole verdict class.
• Flags catch-all, disposable, free, role, no-reply and full mailboxes. Each is a separate column and a separate filter, so a list can be shaped for B2B outreach, for transactional mail or for a newsletter without three different runs.
• Batches without losing the results. The provider accepts up to fifty thousand addresses in one batch, but above one thousand it stops returning results in the response and offers a download file instead, which cannot be read without leaving the API. Batches are therefore capped at one thousand, which keeps every result inline. Results are matched back to your input by address rather than by position, so a collapsed duplicate never shifts the rest onto the wrong rows.
• Waits properly rather than guessing. A batch still running answers with a non-final status, which the polling loop watches for. A partially finished batch is never read as a finished one.
• Keeps the key out of every log line. This provider accepts the key only as a request parameter, never as a header, so the actor makes sure the real request URL is never written to a log.
• Never charges for a miss. Only rows carrying a resolved verdict are billed.

Input

Field	What it does
emails	Addresses to validate.
states	Keep only these verdicts.
reasons	Keep only these reason codes.
excludeFreeEmail	Drop free consumer mailboxes.
excludeRoleAccounts	Drop shared inboxes such as info and support.
excludeDisposable	Drop throwaway addresses.
excludeAcceptAll	Drop addresses on catch-all domains.
excludeNoReply	Drop unattended sender addresses.
requireMxRecord	Keep only domains that can receive mail at all.
requireName	Keep only addresses with a person's name attached.
minScore	Keep only addresses at or above this quality score.
smtpCheck	Probe the receiving mail server. On by default.
acceptAllCheck	Additionally test whether the domain accepts everything.
retryUnknown	Let the provider re-check undecided addresses.
forceSingle	Send every address as its own request.
timeout	Seconds allowed per address, on the single address route.
batchSize	Addresses per batch, up to one thousand.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave addresses with no verdict out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "validate",
  "query": "jane.doe@example.com",
  "email": "jane.doe@example.com",
  "state": "deliverable",
  "reason": "accepted_email",
  "score": 100,
  "domain": "example.com",
  "user": "jane.doe",
  "tag": null,
  "acceptAll": false,
  "disposable": false,
  "free": false,
  "role": false,
  "noReply": false,
  "mailboxFull": false,
  "mxRecord": true,
  "smtpProvider": "google",
  "didYouMean": null,
  "firstName": "Jane",
  "lastName": "Doe",
  "fullName": "Jane Doe",
  "gender": "female",
  "birthYear": 1987,
  "durationSeconds": 0.42,
  "error": null,
  "raw": { }
}

Frequently asked questions

What does an email validation API actually check?

It works in layers. The address is checked for correct syntax, the domain is looked up for mail exchanger records, and then the receiving mail server is contacted over SMTP and asked whether that specific mailbox exists. On top of that the provider applies its own knowledge of disposable providers, role addresses, no-reply senders and catch-all configurations. Each row returns the verdict of that whole process plus the reason code that decided it and a zero to one hundred quality score.

What is the difference between the verdict and the reason code?

The verdict is one of deliverable, undeliverable, risky, unknown or duplicate. The reason code is the detail underneath it, and it is where the useful decisions live. Two addresses can both come back as unknown when one hit a mail server that timed out and will verify fine on a retry, while the other could not be connected to at all. Filtering on the reason code lets you retry the first group and drop the second, instead of discarding both.

Does it really return the person's name?

Yes, where the provider holds it. Alongside the deliverability answer you get first name, last name, full name, gender and birth year for the address, plus the mailbox part and any plus-tag. That means a list clean is also an enrichment pass, which matters when the alternative is running the same list through two services and paying twice. Use the require a name filter when enrichment rather than hygiene is the point of the run.

What is a catch-all domain and why does it matter?

A catch-all domain is configured to accept mail for every possible mailbox, whether or not it exists. An SMTP check against any address there comes back positive and tells you nothing about the individual mailbox. The provider flags these, and the verdict comes back as risky rather than deliverable. Turning on the catch-all test makes the run slower per address and is worth it whenever you need to know whether a deliverable verdict actually means anything.

How large can a batch be, and why is it capped at one thousand?

The provider itself accepts up to fifty thousand addresses in one batch. Above one thousand, though, it stops putting the results in the response and instead offers a download file, which an actor cannot read without leaving the API entirely. So batches here are capped at one thousand, which keeps every result inline and costs nothing but one more request per additional thousand addresses.

When does it use the single address route instead of batching?

Whenever a per address timeout is set, because only the single address route honours one, and for very short lists where waiting for a batch to start and finish costs more than just asking. You can also force it with the always use the single address route option, which is worth doing when you want rows arriving as the run goes rather than in blocks after each batch completes.

Should I turn off the SMTP check?

Only if speed matters more than the answer. With it off the run does syntax and domain level checks and nothing else, which is fast and much less conclusive: it can tell you a domain is dead but not that a mailbox is. It is on by default for that reason. Leave the automatic retry on as well, since a greylisting receiving server very often answers on the second attempt and an unknown that could have been a deliverable is a wasted credit.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from Emailable, which is the provider whose email validation API this actor calls, created on their dashboard. Your own plan, credit balance and terms apply. Paste the key into the apiKey field, where it is stored as an Apify secret. This provider accepts the key only as a request parameter and not as a header, so the actor makes sure the real request URL never reaches a log line. Note that the provider also issues test keys, and a test key on a live route is rejected the same way an invalid key is.

What happens when an address returns nothing?

An undeliverable address is a verdict, not a miss: the provider telling you a mailbox does not exist is exactly the question you asked, so that row is written and billed like any other. A miss is an address the provider returned no verdict for at all, and those are written with found: false and never billed. Set skipNotFound to true to leave them out of the dataset entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each address resolved into the dataset, and never for misses, for rows dropped by the filters, or for duplicates. Apify platform usage is included in the per-result price. Your own API provider's credit balance is separate and billed by them.

Keyword map

email validation API, email verification API, bulk email validator, email list cleaning, SMTP verification, MX record check, catch-all detection, disposable email detection, role account detection, no-reply detection, email typo correction, did you mean suggestion, email quality score, name append from email, gender append, demographic append, bounce rate reduction, sender reputation, list hygiene, signup form validation, B2B list cleaning