Skip to main content
POST

​
Good to know

  • Branch on verdict. valid means send, invalid means the address cannot receive mail, and risky means it probably can but deserves a second look. Use reason to explain why.
  • valid is about the domain, not the mailbox. Finowl never connects to the mail server, so it cannot tell whether jane@ exists at a valid domain. Confirm ownership with a verification email when it matters.
  • risky has two causes. disposable addresses work but are usually thrown away within hours. a_record_fallback means the domain has no MX record, which often means mail was never set up.
  • Offer did_you_mean, don’t apply it. For jane@gmail.co, show “Did you mean jane@gmail.com?” and let the user accept it. The address they typed might be correct.
  • Bad syntax is a 200, not an error. Send raw form input and read reason: invalid_syntax. Only an empty or over-long string returns invalid_input.
  • Send internationalized domains as punycode. Convert jane@münchen.de to jane@xn--mnchen-3ya.de first. Unicode domains return reason: invalid_syntax.
  • role doesn’t change the verdict. Addresses like support@ are real, but they reach a team, not a person.
  • dns_unavailable is free. If DNS doesn’t answer, the request returns 503 and is not charged. Try again after a short delay.

Guide: sign-up fraud checks

Validate the email, phone and IP address together when someone registers.

Authorizations

​
Authorization
string
header
required

Your Finowl API key, for example finowl_3f9a.... Create keys in the dashboard under API Keys.

Body

application/json
​
email
string
required

The address to validate. Leading and trailing spaces are removed. Any string from 1 to 254 characters is accepted, so you can send raw form input and read the verdict. Send internationalized domains in punycode (xn--) form. Unicode domains return invalid_syntax.

Required string length: 1 - 254
Example:

"jane@gmail.co"

Response

The check completed. invalid and risky verdicts are still successful responses.

​
email
string
required

The address that was checked, after trimming.

​
verdict
enum<string>
required

The overall answer. Branch on this.

  • valid: the syntax is correct and the domain accepts mail. The mailbox itself is not probed.
  • risky: the address can probably receive mail, but it is disposable or the domain has no MX record and relies on its A or AAAA record.
  • invalid: the address cannot receive mail.
Available options:
valid,
risky,
invalid
​
reason
enum<string>
required

The most important reason for the verdict.

  • accepted (valid): the domain has mail servers.
  • invalid_syntax (invalid): the address is not a well-formed email address.
  • domain_not_found (invalid): the domain does not exist in DNS.
  • null_mx (invalid): the domain publishes a null MX record (RFC 7505), which means it accepts no mail.
  • no_mail_server (invalid): the domain has no MX record and no A or AAAA record.
  • disposable (risky): the domain is a known disposable email service.
  • a_record_fallback (risky): the domain has no MX record, so mail would go to its A or AAAA record (RFC 5321). This often means mail is not set up.
Available options:
accepted,
invalid_syntax,
domain_not_found,
null_mx,
no_mail_server,
disposable,
a_record_fallback
​
syntax_valid
boolean
required

true when the address is well formed.

​
local_part
string
required

The part before the @. Empty when the syntax is invalid and it cannot be found.

​
domain
string
required

The part after the @, lowercased. Empty when the syntax is invalid and it cannot be found.

​
domain_exists
boolean
required

true when the domain exists in DNS. false when the syntax is invalid.

​
mx_found
boolean
required

true when the domain publishes at least one usable MX record.

​
mx_records
string[]
required

The domain's mail server hostnames, most preferred first, lowercase and without a trailing dot. At most 10. Empty when none were found.

Maximum array length: 10
​
mail_provider
enum<string> | null
required

Who runs the domain's mail servers, detected from the MX hostnames. other for any other host. null when there is no MX record. Treat values you don't recognize like other.

Available options:
google,
microsoft,
yahoo,
apple,
zoho,
proton,
yandex,
mimecast,
proofpoint,
fastmail,
gmx,
ovh,
amazon_ses,
other,
null
​
disposable
boolean
required

true when the domain, or a parent domain, is on the open-source list of disposable email services.

​
role
boolean
required

true when the local part, ignoring any +tag, is a role mailbox such as admin, info, sales, support or noreply. Role addresses are usually shared by a team. This does not change the verdict.

​
free_provider
boolean
required

true when the domain is a free personal mailbox provider such as gmail.com, outlook.com or web.de.

​
did_you_mean
string | null
required

A corrected address when the domain looks like a typo of a popular mail domain, such as gmail.co for gmail.com. null otherwise. Suggest it to the user. Never replace the address without asking.